You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
19 KiB
19 KiB
框架配置
**本文引用的文件** - [application.yml](file://crm-app/src/main/resources/application.yml) - [JacksonConfig.java](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java) - [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java) - [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java) - [SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java) - [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java) - [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java) - [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java) - [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java) - [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)目录
简介
本文件聚焦于框架层的关键配置与扩展点，覆盖以下主题：
- Jackson 序列化配置：时间、空值、枚举、字段可见性等常用策略。
- Redis 缓存配置：连接、序列化、超时、重试等关键参数说明与优化建议。
- 雪花ID生成器 SnowflakeIdWorker：工作节点与机器位分配、时钟回拨处理、线程安全与性能要点。
- 元对象填充处理器 MetaObjectFillHandler：自动填充创建人、更新时间等审计字段的机制与自定义方式。
- 相关集成：MyBatis-Plus 的 ID 生成器注入、SQL 注入器、基础实体约定。
项目结构
本项目采用多模块组织，框架级配置集中在 crm-base 模块的 config 包中，应用入口在 crm-app 模块的 application.yml 中进行外部化配置。
graph TB
subgraph "应用层"
APP["crm-app<br/>application.yml"]
end
subgraph "基础能力层"
JCONF["JacksonConfig.java"]
RCONF["RedisConfig.java"]
MPCONF["MybatisPlusConfig.java"]
SQLI["CrmSqlInjector.java"]
META["MetaObjectFillHandler.java"]
SNOWF["SnowflakeIdWorker.java"]
SNOWP["SnowflakeProperties.java"]
CIDG["CustomIdGenerator.java"]
BASEE["BaseEntity.java"]
end
APP --> JCONF
APP --> RCONF
APP --> MPCONF
MPCONF --> META
MPCONF --> CIDG
CIDG --> SNOWF
SNOWF --> SNOWP
MPCONF --> SQLI
MPCONF --> BASEE
图表来源
- application.yml
- JacksonConfig.java
- RedisConfig.java
- MybatisPlusConfig.java
- CrmSqlInjector.java
- MetaObjectFillHandler.java
- SnowflakeIdWorker.java
- SnowflakeProperties.java
- CustomIdGenerator.java
- BaseEntity.java
章节来源
- application.yml
- JacksonConfig.java
- RedisConfig.java
- MybatisPlusConfig.java
- CrmSqlInjector.java
- MetaObjectFillHandler.java
- SnowflakeIdWorker.java
- SnowflakeProperties.java
- CustomIdGenerator.java
- BaseEntity.java
核心组件
- Jackson 序列化配置：统一 JSON 行为（时间格式、空值策略、枚举序列化、字段可见性、时区等）。
- Redis 缓存配置：连接池、序列化、过期策略、异常重试、集群/哨兵模式开关等。
- SnowflakeIdWorker：分布式唯一ID生成，支持可配置的工作节点与数据中心位，具备时钟回拨检测与告警。
- MetaObjectFillHandler：基于 MyBatis-Plus 的元对象填充，实现创建/更新审计字段自动填充。
- MyBatis-Plus 集成：全局 ID 生成器、SQL 注入器、分页插件、乐观锁等。
章节来源
- JacksonConfig.java
- RedisConfig.java
- SnowflakeIdWorker.java
- SnowflakeProperties.java
- MetaObjectFillHandler.java
- MybatisPlusConfig.java
- CrmSqlInjector.java
- BaseEntity.java
架构总览
下图展示了配置类之间的装配关系与数据流向：应用通过 application.yml 提供外部化配置；Spring 容器加载各配置类并注册 Bean；业务代码通过注解或 API 使用这些能力。
graph LR
YML["application.yml"] --> JCONF["JacksonConfig"]
YML --> RCONF["RedisConfig"]
YML --> MPCONF["MybatisPlusConfig"]
MPCONF --> META["MetaObjectFillHandler"]
MPCONF --> CIDG["CustomIdGenerator"]
CIDG --> SNOWF["SnowflakeIdWorker"]
SNOWF --> SNOWP["SnowflakeProperties"]
MPCONF --> SQLI["CrmSqlInjector"]
MPCONF --> BASEE["BaseEntity"]
图表来源
- application.yml
- JacksonConfig.java
- RedisConfig.java
- MybatisPlusConfig.java
- MetaObjectFillHandler.java
- CustomIdGenerator.java
- SnowflakeIdWorker.java
- SnowflakeProperties.java
- CrmSqlInjector.java
- BaseEntity.java
详细组件分析
Jackson 序列化配置
- 作用与默认行为
- 时间类型序列化：统一为字符串格式与时区设置，避免前后端时间解析不一致。
- 空值处理：对 null 字段进行过滤或保留策略控制，减少冗余 JSON。
- 枚举序列化：按名称或序号序列化，保证接口稳定性。
- 字段可见性：仅序列化被注解标记或满足可见性规则的字段。
- 反序列化容错：忽略未知字段、宽松日期解析等。
- 自定义方式
- 通过 JacksonConfig 中的 ObjectMapper 定制模块、注解、格式化器等。
- 结合 @JsonFormat、@JsonIgnore、@JsonProperty 等注解细化模型行为。
- 优化建议
- 合理设置最大嵌套深度与最大数组长度，防止恶意负载导致 OOM。
- 针对热点字段启用快速序列化（如禁用反射开销）以提升吞吐。
- 常见问题
- 时间格式不匹配：检查时区与格式化模板是否一致。
- 空值丢失：确认空值策略与模型注解是否冲突。
章节来源
- JacksonConfig.java
Redis 缓存配置
- 作用与默认行为
- 连接管理：单机/哨兵/集群模式切换，连接池大小、超时、重试次数。
- 序列化策略：键值序列化器选择（JSON、JDK、String 等），影响兼容性与体积。
- 过期策略：默认 TTL、空值缓存策略、缓存穿透/击穿防护。
- 事务与监听：Pipeline、事务、消息监听等高级特性开关。
- 自定义方式
- 通过 RedisConfig 调整序列化器、超时、连接池、Cluster/Sentinel 参数。
- 在业务中使用 StringRedisTemplate/RedisTemplate 操作缓存。
- 优化建议
- 热点 Key 加本地缓存或布隆过滤器降低 Redis 压力。
- 大对象分片存储，避免单个 Key 过大。
- 合理设置过期时间与随机抖动，避免雪崩。
- 常见问题
- 序列化不一致导致读不到缓存：确保生产与消费侧序列化器一致。
- 连接池耗尽：监控连接数与慢查询，调优 pool.max-active 与超时。
章节来源
- RedisConfig.java
雪花ID生成器 SnowflakeIdWorker
- 作用与默认行为
- 生成 64 位长整型 ID，包含时间戳、数据中心位、工作节点位、序列号。
- 线程安全，单调递增，适合高并发场景。
- 支持时钟回拨检测与告警，必要时可回退到安全策略。
- 配置项与默认值
- 数据中心位与工作节点位：由 SnowflakeProperties 提供，需保证集群内唯一。
- 时钟回拨阈值：超过阈值触发告警或降级。
- 自定义方式
- 通过 CustomIdGenerator 将 SnowflakeIdWorker 注入为 MyBatis-Plus 的全局 ID 生成器。
- 可通过环境变量或配置文件动态调整位分配与阈值。
- 优化建议
- 合理划分数据中心位与工作节点位，避免 ID 空间不足。
- 监控时钟回拨事件，配合 NTP 同步服务。
- 常见问题
- ID 重复：检查工作节点位是否冲突、时钟是否回拨。
- ID 非单调：确认序列号溢出与时间戳推进逻辑。
classDiagram
class SnowflakeProperties {
+long datacenterId
+long workerId
+long maxBackwardMs
}
class SnowflakeIdWorker {
+long nextId() long
-long timestamp
-long sequence
-long datacenterId
-long workerId
}
class CustomIdGenerator {
+generateId(entity) Object
}
SnowflakeIdWorker --> SnowflakeProperties : "读取配置"
CustomIdGenerator --> SnowflakeIdWorker : "委托生成"
图表来源
- SnowflakeIdWorker.java
- SnowflakeProperties.java
- CustomIdGenerator.java
章节来源
- SnowflakeIdWorker.java
- SnowflakeProperties.java
- CustomIdGenerator.java
元对象填充处理器 MetaObjectFillHandler
- 作用与默认行为
- 在插入与更新前自动填充审计字段（如创建人、创建时间、更新人、更新时间）。
- 基于 MyBatis-Plus 的 MetaObjectHandler 接口实现，拦截持久化操作。
- 配置与使用
- 在 MybatisPlusConfig 中注册 MetaObjectFillHandler。
- 实体继承 BaseEntity，定义需要自动填充的字段。
- 自定义方式
- 重写填充逻辑，从上下文获取当前用户信息、租户信息等。
- 可按条件跳过某些字段的填充。
- 优化建议
- 避免在填充逻辑中进行远程调用，保持高性能。
- 对批量操作进行性能优化，减少上下文查询。
- 常见问题
- 填充失败：检查处理器是否注册、上下文是否可用。
- 字段未生效：确认实体字段与注解配置是否正确。
sequenceDiagram
participant Biz as "业务代码"
participant MP as "MyBatis-Plus"
participant Handler as "MetaObjectFillHandler"
participant DB as "数据库"
Biz->>MP : 调用 insert/update
MP->>Handler : 执行填充逻辑
Handler-->>MP : 返回填充后的实体
MP->>DB : 执行持久化
DB-->>Biz : 返回结果
图表来源
- MetaObjectFillHandler.java
- MybatisPlusConfig.java
- BaseEntity.java
章节来源
- MetaObjectFillHandler.java
- MybatisPlusConfig.java
- BaseEntity.java
MyBatis-Plus 集成与 SQL 注入器
- 作用与默认行为
- 全局配置 ID 生成器、分页插件、乐观锁、SQL 注入器等。
- CrmSqlInjector 提供通用 SQL 片段与增强方法。
- 配置与使用
- 在 MybatisPlusConfig 中注册各类插件与处理器。
- 在 Mapper 中直接使用增强方法。
- 优化建议
- 合理使用分页与条件构造器，避免全表扫描。
- 对复杂查询进行 SQL 分析与索引优化。
- 常见问题
- 插件冲突：检查插件注册顺序与兼容性。
- SQL 注入风险：使用参数化查询，避免拼接。
章节来源
- MybatisPlusConfig.java
- CrmSqlInjector.java
依赖关系分析
- JacksonConfig 与 RedisConfig 均依赖 Spring 环境，通过 application.yml 提供配置。
- MybatisPlusConfig 依赖 MetaObjectFillHandler、CustomIdGenerator、CrmSqlInjector。
- CustomIdGenerator 依赖 SnowflakeIdWorker，后者依赖 SnowflakeProperties。
- BaseEntity 作为实体基类，被业务实体继承以启用审计字段。
graph TD
JCONF["JacksonConfig"] --> SPRING["Spring 容器"]
RCONF["RedisConfig"] --> SPRING
MPCONF["MybatisPlusConfig"] --> META["MetaObjectFillHandler"]
MPCONF --> CIDG["CustomIdGenerator"]
CIDG --> SNOWF["SnowflakeIdWorker"]
SNOWF --> SNOWP["SnowflakeProperties"]
MPCONF --> SQLI["CrmSqlInjector"]
MPCONF --> BASEE["BaseEntity"]
图表来源
- JacksonConfig.java
- RedisConfig.java
- MybatisPlusConfig.java
- MetaObjectFillHandler.java
- CustomIdGenerator.java
- SnowflakeIdWorker.java
- SnowflakeProperties.java
- CrmSqlInjector.java
- BaseEntity.java
章节来源
- application.yml
- JacksonConfig.java
- RedisConfig.java
- MybatisPlusConfig.java
- MetaObjectFillHandler.java
- CustomIdGenerator.java
- SnowflakeIdWorker.java
- SnowflakeProperties.java
- CrmSqlInjector.java
- BaseEntity.java
性能考虑
- Jackson：启用快速序列化、限制嵌套深度、按需序列化字段。
- Redis：连接池调优、Pipeline 批量操作、热点 Key 本地缓存、避免大对象。
- Snowflake：合理分配位段、监控时钟回拨、避免序列号溢出。
- MyBatis-Plus：分页查询、索引优化、避免 N+1 问题。
[本节为通用指导，无需特定文件来源]
故障排查指南
- Jackson 序列化异常
- 现象：JSON 解析失败、时间格式错误。
- 排查：检查 ObjectMapper 配置、字段注解、时区设置。
- Redis 连接失败
- 现象：连接超时、序列化错误。
- 排查：检查连接参数、序列化器一致性、网络连通性。
- Snowflake ID 重复
- 现象：主键冲突。
- 排查：检查工作节点位唯一性、时钟回拨日志、序列号溢出。
- 元对象填充失效
- 现象：审计字段为空。
- 排查：检查处理器注册、上下文可用性、实体继承关系。
章节来源
- JacksonConfig.java
- RedisConfig.java
- SnowflakeIdWorker.java
- MetaObjectFillHandler.java
结论
通过集中化的框架配置，项目在序列化、缓存、ID 生成与审计填充等方面实现了统一与可扩展。建议在生产环境中持续监控关键指标（序列化耗时、Redis 连接数、ID 生成延迟、填充成功率），并结合业务场景进行参数调优与故障预案设计。
[本节为总结性内容，无需特定文件来源]
附录
- 配置项速查
- Jackson：时间格式、空值策略、枚举序列化、字段可见性。
- Redis：连接池、序列化器、超时、重试、集群/哨兵。
- Snowflake：数据中心位、工作节点位、时钟回拨阈值。
- MetaObjectFillHandler：审计字段、填充时机、上下文来源。
- 最佳实践
- 配置与环境分离，使用配置文件管理不同环境差异。
- 对关键组件添加健康检查与监控告警。
- 定期审查配置变更，避免漂移与不一致。
[本节为补充信息，无需特定文件来源]