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

# 架构决策记录 (ADR) - 基础实体类和 Mapper 创建

## 背景

REQ-010-2 需求要求为 6 张数据库表创建对应的 Java 实体类、Mapper 接口和 XML 映射文件，使用 MyBatis Plus 框架，为后续功能开发提供数据访问基础。

6 张数据库表包括：
- datai_meta_org_config - Salesforce 组织配置表
- datai_meta_task - 元数据任务定义表
- datai_meta_job_execution - 作业执行记录表
- datai_meta_component - 元数据组件索引表
- datai_meta_deploy_history - 部署历史记录表
- datai_meta_job_log - 作业执行日志表

这些表结构已在 REQ-010-1 中完成设计和创建，现在需要创建对应的数据访问层代码。

约束条件：
- 必须使用 MyBatis Plus 框架
- 必须继承 BaseMapper 获取基础 CRUD 方法
- 必须使用 MyBatis Plus 注解（@TableName、@TableId、@TableField）
- 必须遵循项目编码规范
- 必须依赖于 REQ-010-1 创建的数据库表

面临的挑战：
1. 如何处理 JSON 类型字段的序列化和反序列化
2. 如何处理 TEXT 类型大字段
3. 如何处理敏感字段的查询控制
4. 如何确保代码符合项目编码规范

## 决策

采用 **MyBatis Plus 注解 + XML 映射文件** 的混合方案：

1. **实体类设计**：
   - 使用 MyBatis Plus 注解（@TableName、@TableId、@TableField）进行表映射
   - 使用 Lombok 简化实体类代码（@Data、@Builder、@NoArgsConstructor、@AllArgsConstructor）
   - 使用 Jackson 的 @JsonSerialize 和 @JsonDeserialize 处理 JSON 类型字段
   - 使用 String 类型处理 TEXT 类型大字段
   - 使用 @TableField(select = false) 注解控制敏感字段默认不查询
   - 添加必要的注释说明（类注释、字段注释）

2. **Mapper 接口设计**：
   - 继承 BaseMapper 获取基础 CRUD 方法
   - 使用 @Mapper 注解标记 Mapper 接口
   - 根据需要添加自定义查询方法

3. **Mapper XML 文件设计**：
   - 配置自定义查询方法的 SQL 映射
   - namespace 配置为 Mapper 接口的全限定名
   - resultType 配置为实体类的全限定名
   - 添加必要的注释说明

## 备选方案

### 方案 1：MyBatis Plus 注解 + XML 映射文件（已选择）

**优点**：
- 结合了注解的简洁性和 XML 的灵活性
- 注解用于基础映射，XML 用于复杂查询
- 代码结构清晰，易于理解和维护
- 符合 MyBatis Plus 最佳实践
- 支持自定义查询方法，满足复杂业务需求

**缺点**：
- 需要维护 XML 映射文件
- 代码文件数量较多（实体类 + Mapper 接口 + XML 文件）

### 方案 2：纯 MyBatis Plus 注解（不使用 XML 映射文件）

**优点**：
- 代码文件数量较少（实体类 + Mapper 接口）
- 无需维护 XML 映射文件
- 代码更简洁，减少配置

**缺点**：
- 不支持复杂查询，需要使用 QueryWrapper 或 LambdaQueryWrapper
- QueryWrapper 代码可读性较差，难以维护
- 不支持动态 SQL（如 if、choose、foreach 等）
- 不满足 REQ-010-2 需求中关于 Mapper XML 文件的要求

### 方案 3：纯 MyBatis（不使用 MyBatis Plus）

**优点**：
- 完全控制 SQL 语句
- 支持复杂的查询和动态 SQL
- 代码可读性高

**缺点**：
- 需要手动编写基础 CRUD 方法，代码量大
- 不符合 REQ-010-2 需求中关于使用 MyBatis Plus 框架的约束
- 不符合项目现有技术栈
- 开发效率低，维护成本高

## 影响

### 对系统架构的影响

1. **数据访问层架构**：
   - 建立了统一的数据访问层规范
   - 使用 MyBatis Plus 作为统一的 ORM 框架
   - 为后续功能开发提供了数据访问基础

2. **代码结构**：
   - 实体类：`com.datai.salesforce.metadata.entity`
   - Mapper 接口：`com.datai.salesforce.metadata.mapper`
   - Mapper XML 文件：`resources/mapper`

3. **技术栈一致性**：
   - 与现有项目技术栈保持一致
   - 使用 MyBatis Plus 作为统一的 ORM 框架
   - 使用 Lombok 简化代码

### 对开发流程的影响

1. **开发效率**：
   - 使用 MyBatis Plus 的 BaseMapper，无需手动编写基础 CRUD 方法
   - 使用 Lombok 简化实体类代码，减少样板代码
   - 提高开发效率，减少开发时间

2. **代码质量**：
   - 使用注解进行表映射，减少 XML 配置错误
   - 使用 Jackson 处理 JSON 字段，确保数据一致性
   - 使用 @TableField(select = false) 控制敏感字段查询，提高安全性

3. **可维护性**：
   - 代码结构清晰，易于理解和维护
   - 注释完整，便于后续开发人员理解
   - 符合项目编码规范，便于代码审查

### 对运维管理的影响

1. **性能优化**：
   - 使用 MyBatis Plus 的 BaseMapper，性能优于手动编写的 SQL
   - 使用 Jackson 处理 JSON 字段，性能优于手动序列化
   - 使用 @TableField(select = false) 控制敏感字段查询，减少不必要的数据传输

2. **监控和调试**：
   - MyBatis Plus 提供了完善的日志功能，便于监控和调试
   - XML 映射文件提供了清晰的 SQL 语句，便于性能优化

## 风险

### 技术风险

1. **MyBatis Plus 版本兼容性风险**：
   - **风险描述**：MyBatis Plus 版本升级可能导致注解或 API 变更
   - **影响程度**：中
   - **应对措施**：使用稳定的 MyBatis Plus 版本（3.5+），关注版本更新日志

2. **Jackson 序列化和反序列化风险**：
   - **风险描述**：JSON 字段结构变更可能导致序列化和反序列化失败
   - **影响程度**：中
   - **应对措施**：使用 Jackson 的容错机制，添加异常处理

3. **Lombok 兼容性风险**：
   - **风险描述**：Lombok 版本升级可能导致注解失效
   - **影响程度**：低
   - **应对措施**：使用稳定的 Lombok 版本，确保 IDE 支持

### 业务风险

1. **敏感字段查询控制风险**：
   - **风险描述**：敏感字段可能被误查询，导致数据泄露
   - **影响程度**：高
   - **应对措施**：使用 @TableField(select = false) 注解控制敏感字段默认不查询，需要时显式查询

2. **JSON 字段数据丢失风险**：
   - **风险描述**：JSON 字段序列化和反序列化失败可能导致数据丢失
   - **影响程度**：中
   - **应对措施**：使用 Jackson 的容错机制，添加异常处理和日志记录

### 实施风险

1. **代码规范风险**：
   - **风险描述**：代码不符合项目编码规范，导致代码审查失败
   - **影响程度**：中
   - **应对措施**：严格按照阿里巴巴 Java 开发规范编写代码，使用代码检查工具

2. **Mapper XML 配置风险**：
   - **风险描述**：Mapper XML 配置错误可能导致 SQL 执行失败
   - **影响程度**：中
   - **应对措施**：参考现有 Mapper XML 文件，编写单元测试验证

## 回滚策略

如果决策实施后出现问题，可以采取以下回滚策略：

1. **实体类回滚**：
   - 删除实体类文件
   - 重新创建实体类，使用纯 MyBatis 方式（不使用 MyBatis Plus 注解）

2. **Mapper 接口回滚**：
   - 删除 Mapper 接口文件
   - 重新创建 Mapper 接口，不继承 BaseMapper
   - 手动编写基础 CRUD 方法

3. **Mapper XML 文件回滚**：
   - 删除 Mapper XML 文件
   - 重新创建 Mapper XML 文件，使用纯 MyBatis 方式

4. **依赖回滚**：
   - 移除 MyBatis Plus 依赖
   - 添加 MyBatis 依赖
   - 更新 Spring Boot 配置

回滚步骤：
1. 备份当前代码
2. 删除实体类、Mapper 接口、Mapper XML 文件
3. 重新创建实体类、Mapper 接口、Mapper XML 文件，使用纯 MyBatis 方式
4. 更新项目依赖
5. 编译和测试

## 验收标准

定义验证该决策有效性的具体标准和测试方法：

1. **功能完整性**：
   - [ ] 6 个实体类创建成功，字段映射正确
   - [ ] 6 个 Mapper 接口创建成功，继承 BaseMapper
   - [ ] 6 个 Mapper XML 文件创建成功，配置正确

2. **代码正确性**：
   - [ ] 实体类注解使用正确（@TableName、@TableId、@TableField）
   - [ ] JSON 字段能够正确序列化和反序列化
   - [ ] TEXT 类型大字段能够正确处理
   - [ ] 敏感字段默认不查询（@TableField(select = false)）
   - [ ] Mapper XML 配置正确（namespace、resultType）

3. **代码规范性**：
   - [ ] 代码符合阿里巴巴 Java 开发规范
   - [ ] 代码有清晰的注释说明
   - [ ] 代码结构清晰，易于理解和维护

4. **框架兼容性**：
   - [ ] 代码与 MyBatis Plus 框架兼容
   - [ ] 代码与 Lombok 兼容
   - [ ] 代码与 Jackson 兼容

5. **性能要求**：
   - [ ] 实体类序列化和反序列化耗时不超过 10ms
   - [ ] Mapper 接口查询响应时间不超过 100ms

6. **安全要求**：
   - [ ] 敏感字段（client_secret、password、security_token）默认不查询
   - [ ] JSON 字段序列化和反序列化有异常处理

7. **可用性要求**：
   - [ ] 实体类、Mapper 接口、Mapper XML 文件编译通过，无错误和警告

8. **可维护性要求**：
   - [ ] 代码结构清晰，注释完整，易于理解和维护

测试方法：
1. 编写单元测试，验证实体类、Mapper 接口、Mapper XML 文件的功能正确性
2. 使用代码检查工具（如 Checkstyle、SonarQube）验证代码规范性
3. 使用性能测试工具（如 JMeter）验证性能要求
4. 使用安全测试工具（如 OWASP ZAP）验证安全要求

## 视觉锚点

### 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-1.md](../../requirements/REQ-010-1.md) - 数据库表结构设计和创建需求文档
- [0010-database-table-design.md](0010-database-table-design.md) - 数据库表结构设计和创建架构决策
- [MyBatis Plus 官方文档](https://baomidou.com/) - MyBatis Plus 官方文档
- [Lombok 官方文档](https://projectlombok.org/) - Lombok 官方文档
- [Jackson 官方文档](https://github.com/FasterXML/jackson) - Jackson 官方文档
- [阿里巴巴 Java 开发规范](https://github.com/alibaba/p3c) - 阿里巴巴 Java 开发规范