392 lines
14 KiB
Markdown
392 lines
14 KiB
Markdown
# 架构决策记录 - 基础实体类和Mapper创建
|
||
|
||
## 背景
|
||
|
||
在完成数据库表结构设计和创建（REQ-010-1）后，需要为9张数据库表创建对应的Java实体类、Mapper接口和XML映射文件，使用MyBatis Plus框架，为后续功能开发提供数据访问基础。
|
||
|
||
当前系统面临的主要问题包括：
|
||
1. 缺少Java实体类，无法进行数据持久化操作
|
||
2. 缺少Mapper接口，无法进行数据库查询和更新
|
||
3. 缺少XML映射文件，无法配置SQL映射
|
||
4. 需要处理JSON类型字段的序列化和反序列化
|
||
5. 需要处理TEXT类型大字段
|
||
6. 需要保护敏感字段，避免泄露
|
||
|
||
## 决策
|
||
|
||
### 1. 实体类创建方案
|
||
|
||
**决策**: 使用MyBatis Plus注解创建实体类，使用Lombok简化代码，使用Jackson处理JSON字段。
|
||
|
||
**理由**:
|
||
- MyBatis Plus注解（@TableName、@TableId、@TableField）可以简化实体类配置
|
||
- Lombok可以简化实体类代码，减少样板代码
|
||
- Jackson可以处理JSON类型字段的序列化和反序列化
|
||
- 使用String类型处理TEXT类型大字段，简单可靠
|
||
- 使用@TableField(select = false)注解保护敏感字段，避免泄露
|
||
|
||
**实现方案**:
|
||
- 使用@TableName注解指定表名
|
||
- 使用@TableId注解标识主键，类型为Long
|
||
- 使用@TableField注解处理字段映射
|
||
- 使用Lombok的@Data、@Builder、@NoArgsConstructor、@AllArgsConstructor注解简化代码
|
||
- 使用Jackson的@JsonSerialize和@JsonDeserialize处理JSON字段
|
||
- 使用String类型处理TEXT类型大字段
|
||
- 使用@TableField(select = false)注解保护敏感字段（client_secret、password、security_token）
|
||
- 添加必要的注释说明（类注释、字段注释）
|
||
- 代码符合阿里巴巴Java开发规范
|
||
|
||
### 2. Mapper接口创建方案
|
||
|
||
**决策**: 创建Mapper接口，继承BaseMapper获取基础CRUD方法，使用@Mapper注解标记Mapper接口。
|
||
|
||
**理由**:
|
||
- BaseMapper提供了基础的CRUD方法，可以减少重复代码
|
||
- @Mapper注解标记Mapper接口，便于MyBatis扫描和注册
|
||
- 根据需要添加自定义查询方法，满足业务需求
|
||
- 代码符合阿里巴巴Java开发规范
|
||
|
||
**实现方案**:
|
||
- 创建Mapper接口，继承BaseMapper获取基础CRUD方法
|
||
- 使用@Mapper注解标记Mapper接口
|
||
- 根据需要添加自定义查询方法
|
||
- 添加必要的注释说明
|
||
- 代码符合阿里巴巴Java开发规范
|
||
|
||
### 3. Mapper XML文件创建方案
|
||
|
||
**决策**: 创建Mapper XML文件，配置SQL映射，使用MyBatis Plus的XML映射语法。
|
||
|
||
**理由**:
|
||
- XML映射文件可以配置复杂的SQL查询
|
||
- MyBatis Plus的XML映射语法简单易用
|
||
- namespace配置正确，对应Mapper接口的全限定名
|
||
- resultType配置正确，对应实体类的全限定名
|
||
- 添加必要的注释说明，提高代码可读性
|
||
- 代码符合MyBatis Plus XML映射语法
|
||
|
||
**实现方案**:
|
||
- 创建Mapper XML文件，配置SQL映射
|
||
- namespace配置正确，对应Mapper接口的全限定名
|
||
- resultType配置正确，对应实体类的全限定名
|
||
- 添加必要的注释说明
|
||
- 代码符合MyBatis Plus XML映射语法
|
||
|
||
### 4. JSON字段处理方案
|
||
|
||
**决策**: 使用Jackson处理JSON类型字段的序列化和反序列化。
|
||
|
||
**理由**:
|
||
- Jackson是Java中常用的JSON处理库，功能强大
|
||
- Jackson可以处理复杂的JSON数据结构
|
||
- Jackson的@JsonSerialize和@JsonDeserialize注解可以自定义序列化和反序列化逻辑
|
||
- Jackson的性能良好，可以满足性能要求
|
||
|
||
**实现方案**:
|
||
- 使用Jackson的@JsonSerialize注解指定序列化器
|
||
- 使用Jackson的@JsonDeserialize注解指定反序列化器
|
||
- 自定义序列化器和反序列化器，处理JSON字段的序列化和反序列化
|
||
- 使用String类型存储JSON字段，使用Jackson进行序列化和反序列化
|
||
|
||
### 5. 大字段处理方案
|
||
|
||
**决策**: 使用String类型处理TEXT类型大字段。
|
||
|
||
**理由**:
|
||
- String类型可以存储TEXT类型大字段
|
||
- String类型简单易用，不需要额外的处理
|
||
- String类型的性能良好，可以满足性能要求
|
||
|
||
**实现方案**:
|
||
- 使用String类型处理TEXT类型大字段
|
||
- 使用@TableField注解处理字段映射
|
||
- 添加必要的注释说明
|
||
|
||
### 6. 敏感字段保护方案
|
||
|
||
**决策**: 使用@TableField(select = false)注解保护敏感字段，默认不查询。
|
||
|
||
**理由**:
|
||
- @TableField(select = false)注解可以保护敏感字段，默认不查询
|
||
- 避免敏感字段泄露，提高系统安全性
|
||
- 需要查询敏感字段时，使用SQL查询指定字段
|
||
|
||
**实现方案**:
|
||
- 使用@TableField(select = false)注解保护敏感字段（client_secret、password、security_token）
|
||
- 默认不查询敏感字段
|
||
- 需要查询敏感字段时，使用SQL查询指定字段
|
||
- 添加必要的注释说明
|
||
|
||
## 备选方案
|
||
|
||
### 1. 实体类创建备选方案
|
||
|
||
**备选方案 1**: 使用XML映射文件创建实体类
|
||
|
||
**优点**:
|
||
- XML映射文件可以配置复杂的字段映射
|
||
- XML映射文件可以处理特殊的字段类型
|
||
|
||
**缺点**:
|
||
- XML映射文件配置复杂，维护成本高
|
||
- XML映射文件不如注解直观
|
||
- 不如MyBatis Plus注解简单易用
|
||
|
||
**备选方案 2**: 使用JPA注解创建实体类
|
||
|
||
**优点**:
|
||
- JPA是标准的ORM框架，易于学习
|
||
|
||
**缺点**:
|
||
- JPA的性能不如MyBatis Plus
|
||
- JPA不如MyBatis Plus灵活
|
||
- 不如MyBatis Plus注解简单易用
|
||
|
||
### 2. Mapper接口创建备选方案
|
||
|
||
**备选方案 1**: 不继承BaseMapper，手动实现CRUD方法
|
||
|
||
**优点**:
|
||
- 可以自定义CRUD方法，满足特殊需求
|
||
|
||
**缺点**:
|
||
- 需要手动实现CRUD方法，代码量大
|
||
- 不如BaseMapper简单易用
|
||
- 不如BaseMapper功能丰富
|
||
|
||
**备选方案 2**: 使用注解配置SQL查询
|
||
|
||
**优点**:
|
||
- 注解配置SQL查询，简单直观
|
||
|
||
**缺点**:
|
||
- 注解配置SQL查询，不如XML映射文件灵活
|
||
- 注解配置SQL查询，不适合复杂的SQL查询
|
||
- 不如XML映射文件功能丰富
|
||
|
||
### 3. Mapper XML文件创建备选方案
|
||
|
||
**备选方案 1**: 不创建XML映射文件，使用注解配置SQL查询
|
||
|
||
**优点**:
|
||
- 注解配置SQL查询，简单直观
|
||
|
||
**缺点**:
|
||
- 注解配置SQL查询，不如XML映射文件灵活
|
||
- 注解配置SQL查询，不适合复杂的SQL查询
|
||
- 不如XML映射文件功能丰富
|
||
|
||
**备选方案 2**: 使用MyBatis Plus的Wrapper构建查询条件
|
||
|
||
**优点**:
|
||
- Wrapper构建查询条件，简单易用
|
||
|
||
**缺点**:
|
||
- Wrapper构建查询条件，不如XML映射文件灵活
|
||
- Wrapper构建查询条件，不适合复杂的SQL查询
|
||
- 不如XML映射文件功能丰富
|
||
|
||
### 4. JSON字段处理备选方案
|
||
|
||
**备选方案 1**: 使用Gson处理JSON字段
|
||
|
||
**优点**:
|
||
- Gson是Google开发的JSON处理库，性能良好
|
||
|
||
**缺点**:
|
||
- Gson的功能不如Jackson丰富
|
||
- Gson的注解不如Jackson灵活
|
||
- 不如Jackson流行
|
||
|
||
**备选方案 2**: 使用Fastjson处理JSON字段
|
||
|
||
**优点**:
|
||
- Fastjson是阿里巴巴开发的JSON处理库，性能良好
|
||
|
||
**缺点**:
|
||
- Fastjson的安全性问题较多，不如Jackson安全
|
||
- Fastjson的功能不如Jackson丰富
|
||
- 不如Jackson流行
|
||
|
||
### 5. 大字段处理备选方案
|
||
|
||
**备选方案 1**: 使用byte[]类型处理TEXT类型大字段
|
||
|
||
**优点**:
|
||
- byte[]类型可以存储二进制数据
|
||
|
||
**缺点**:
|
||
- byte[]类型不如String类型简单易用
|
||
- byte[]类型的性能不如String类型
|
||
- 不如String类型流行
|
||
|
||
**备选方案 2**: 使用Blob类型处理TEXT类型大字段
|
||
|
||
**优点**:
|
||
- Blob类型可以存储二进制数据
|
||
|
||
**缺点**:
|
||
- Blob类型不如String类型简单易用
|
||
- Blob类型的性能不如String类型
|
||
- 不如String类型流行
|
||
|
||
### 6. 敏感字段保护备选方案
|
||
|
||
**备选方案 1**: 使用加密算法加密敏感字段
|
||
|
||
**优点**:
|
||
- 加密算法可以保护敏感字段，提高系统安全性
|
||
|
||
**缺点**:
|
||
- 加密算法增加了系统复杂度
|
||
- 加密算法影响了系统性能
|
||
- 不如@TableField(select = false)注解简单易用
|
||
|
||
**备选方案 2**: 使用视图隐藏敏感字段
|
||
|
||
**优点**:
|
||
- 视图可以隐藏敏感字段，提高系统安全性
|
||
|
||
**缺点**:
|
||
- 视图增加了系统复杂度
|
||
- 视图影响了系统性能
|
||
- 不如@TableField(select = false)注解简单易用
|
||
|
||
## 影响
|
||
|
||
### 对系统架构的影响
|
||
|
||
- 新增9个实体类，包括DataiMetaOrgConfig、DataiMetaTask、DataiMetaPackageItem、DataiMetaComponent、DataiMetaComponentVersion、DataiMetaJobExecution、DataiMetaDeployHistory、DataiMetaDeployComponentResult、DataiMetaJobLog
|
||
- 新增9个Mapper接口，包括DataiMetaOrgConfigMapper、DataiMetaTaskMapper、DataiMetaPackageItemMapper、DataiMetaComponentMapper、DataiMetaComponentVersionMapper、DataiMetaJobExecutionMapper、DataiMetaDeployHistoryMapper、DataiMetaDeployComponentResultMapper、DataiMetaJobLogMapper
|
||
- 新增9个Mapper XML文件，包括DataiMetaOrgConfigMapper.xml、DataiMetaTaskMapper.xml、DataiMetaPackageItemMapper.xml、DataiMetaComponentMapper.xml、DataiMetaComponentVersionMapper.xml、DataiMetaJobExecutionMapper.xml、DataiMetaDeployHistoryMapper.xml、DataiMetaDeployComponentResultMapper.xml、DataiMetaJobLogMapper.xml
|
||
|
||
### 对开发流程的影响
|
||
|
||
- 需要开发人员掌握MyBatis Plus框架，包括实体类注解、Mapper接口、XML映射文件
|
||
- 需要开发人员掌握Lombok框架，包括@Data、@Builder、@NoArgsConstructor、@AllArgsConstructor注解
|
||
- 需要开发人员掌握Jackson框架，包括@JsonSerialize、@JsonDeserialize注解
|
||
- 需要开发人员编写单元测试，验证实体类、Mapper接口、XML映射文件
|
||
|
||
### 对运维管理的影响
|
||
|
||
- 需要运维人员维护数据库表结构，确保表结构与实体类一致
|
||
- 需要运维人员监控数据库性能，确保查询性能满足要求
|
||
|
||
## 风险
|
||
|
||
### 技术风险
|
||
|
||
- **实体类映射风险**: 实体类字段映射错误可能导致数据读写失败
|
||
- **Mapper XML配置风险**: Mapper XML配置错误可能导致SQL执行失败
|
||
- **JSON字段处理风险**: JSON类型字段处理不当可能导致数据丢失
|
||
- **大字段处理风险**: 大字段处理不当可能导致性能问题
|
||
- **框架兼容风险**: MyBatis Plus版本兼容性问题
|
||
|
||
### 业务风险
|
||
|
||
- **数据一致性风险**: 实体类字段映射错误可能导致数据不一致
|
||
- **性能风险**: 大字段处理不当可能导致性能下降
|
||
|
||
### 实施风险
|
||
|
||
- **开发风险**: 实体类、Mapper接口、XML映射文件开发复杂，可能影响开发进度
|
||
- **测试风险**: 实体类、Mapper接口、XML映射文件测试复杂，可能影响测试进度
|
||
|
||
## 回滚策略
|
||
|
||
### 实体类创建回滚策略
|
||
|
||
- 如果实体类字段映射错误，可以修改实体类字段映射，重新编译
|
||
- 如果实体类字段映射影响业务功能，可以删除实体类，重新创建
|
||
|
||
### Mapper接口创建回滚策略
|
||
|
||
- 如果Mapper接口配置错误，可以修改Mapper接口，重新编译
|
||
- 如果Mapper接口影响业务功能，可以删除Mapper接口，重新创建
|
||
|
||
### Mapper XML文件创建回滚策略
|
||
|
||
- 如果Mapper XML配置错误，可以修改Mapper XML，重新编译
|
||
- 如果Mapper XML影响业务功能，可以删除Mapper XML，重新创建
|
||
|
||
### JSON字段处理回滚策略
|
||
|
||
- 如果JSON字段处理错误，可以修改JSON字段处理逻辑，重新编译
|
||
- 如果JSON字段影响业务功能，可以删除JSON字段处理逻辑，重新创建
|
||
|
||
### 大字段处理回滚策略
|
||
|
||
- 如果大字段处理错误，可以修改大字段处理逻辑，重新编译
|
||
- 如果大字段影响业务功能，可以删除大字段处理逻辑，重新创建
|
||
|
||
### 敏感字段保护回滚策略
|
||
|
||
- 如果敏感字段保护错误，可以修改敏感字段保护逻辑，重新编译
|
||
- 如果敏感字段保护影响业务功能，可以删除敏感字段保护逻辑，重新创建
|
||
|
||
## 验收标准
|
||
|
||
### 实体类创建验收标准
|
||
|
||
- 9个实体类创建成功
|
||
- 使用MyBatis Plus的@TableName注解指定表名
|
||
- 使用@TableId注解标识主键，类型为Long
|
||
- 使用@TableField注解处理字段映射
|
||
- 实体类字段与数据库表字段一一对应
|
||
- 实体类处理JSON类型字段的序列化和反序列化（使用Jackson的@JsonSerialize和@JsonDeserialize）
|
||
- 实体类处理TEXT类型大字段（使用String类型）
|
||
- 实体类添加必要的注释说明（类注释、字段注释）
|
||
- 实体类使用Lombok简化代码（@Data、@Builder、@NoArgsConstructor、@AllArgsConstructor）
|
||
- 实体类代码符合阿里巴巴Java开发规范
|
||
|
||
### Mapper接口创建验收标准
|
||
|
||
- 9个Mapper接口创建成功
|
||
- Mapper接口继承BaseMapper获取基础CRUD方法
|
||
- Mapper接口使用@Mapper注解标记
|
||
- Mapper接口添加自定义查询方法（如果需要）
|
||
- Mapper接口代码符合阿里巴巴Java开发规范
|
||
|
||
### Mapper XML文件创建验收标准
|
||
|
||
- 9个Mapper XML文件创建成功
|
||
- XML映射文件namespace配置正确（对应Mapper接口的全限定名）
|
||
- XML映射文件resultType配置正确（对应实体类的全限定名）
|
||
- XML映射文件添加必要的注释说明
|
||
- XML映射文件代码符合MyBatis Plus XML映射语法
|
||
|
||
### 非功能验收标准
|
||
|
||
- 性能要求 - 实体类序列化和反序列化耗时不超过 10ms
|
||
- 性能要求 - Mapper接口查询响应时间不超过 100ms
|
||
- 安全要求 - 敏感字段（client_secret、password、security_token）使用@TableField(select = false)注解，默认不查询
|
||
- 可用性要求 - 实体类、Mapper接口、Mapper XML文件编译通过，无错误和警告
|
||
- 可维护性要求 - 代码结构清晰，注释完整，易于理解和维护
|
||
|
||
## 视觉锚点
|
||
|
||
### Visual Reference
|
||
|
||
引用 Canvas 的具体节点或快照：
|
||
- [Authentication.canvas](../../Authentication.canvas) - 相关架构图
|
||
- **具体节点**: [集成Mapper](node_integration_mapper) - 处理集成相关数据的持久化操作
|
||
|
||
### Status
|
||
|
||
- [x] Draft
|
||
- [ ] Accepted
|
||
- [ ] Superceded
|
||
|
||
## 参考资料
|
||
|
||
列出与该决策相关的参考资料，包括文档、文章或其他资源：
|
||
|
||
- [REQ-010-2.md](../requirements/REQ-010-2.md) - 基础实体类和Mapper创建需求文档
|
||
- [REQ-010.md](../requirements/REQ-010.md) - Salesforce元数据拉取和部署主需求文档
|
||
- [REQ-010-1.md](../requirements/REQ-010-1.md) - 数据库表结构设计和创建
|
||
- [metadata-module.md](../reference-code/com/docs/metadata-module.md) - Salesforce Metadata API 模块说明（唯一真源）
|
||
- [index.md](../reference-code/com/docs/index.md) - Salesforce SOAP API Java 客户端参考文档（唯一真源）
|
||
- MyBatis Plus 文档 - https://baomidou.com/
|
||
- Lombok 文档 - https://projectlombok.org/
|
||
- Jackson 文档 - https://github.com/FasterXML/jackson
|