datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0011-entity-mapper-create.md

架构决策记录 - 基础实体类和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 - 相关架构图
• 具体节点: 集成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