14 KiB
14 KiB
架构决策记录 - 基础实体类和Mapper创建
背景
在完成数据库表结构设计和创建（REQ-010-1）后，需要为9张数据库表创建对应的Java实体类、Mapper接口和XML映射文件，使用MyBatis Plus框架，为后续功能开发提供数据访问基础。
当前系统面临的主要问题包括：
- 缺少Java实体类，无法进行数据持久化操作
- 缺少Mapper接口，无法进行数据库查询和更新
- 缺少XML映射文件，无法配置SQL映射
- 需要处理JSON类型字段的序列化和反序列化
- 需要处理TEXT类型大字段
- 需要保护敏感字段，避免泄露
决策
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 - 相关架构图
- 具体节点: 集成Mapper - 处理集成相关数据的持久化操作
Status
- Draft
- Accepted
- Superceded
参考资料
列出与该决策相关的参考资料，包括文档、文章或其他资源：
- REQ-010-2.md - 基础实体类和Mapper创建需求文档
- REQ-010.md - Salesforce元数据拉取和部署主需求文档
- REQ-010-1.md - 数据库表结构设计和创建
- metadata-module.md - Salesforce Metadata API 模块说明（唯一真源）
- index.md - Salesforce SOAP API Java 客户端参考文档（唯一真源）
- MyBatis Plus 文档 - https://baomidou.com/
- Lombok 文档 - https://projectlombok.org/
- Jackson 文档 - https://github.com/FasterXML/jackson