kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
469c78cf29
datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0011-entity-mapper-create.md
Kris 469c78cf29 feat: REQ-010-1 完成数据库表结构设计和创建，REQ-010-2 完成基础实体类和Mapper创建需求定义和架构决策 
REQ-010-1 完成内容：
- 创建 6 个数据库表设计（datai_meta_org_config、datai_meta_task、datai_meta_job_execution、datai_meta_component、datai_meta_deploy_history、datai_meta_job_log）
- 设计了合理的索引策略
- 对敏感字段进行了加密存储设计
- 表名前缀统一为 datai_meta_
- 所有表包含标准基础字段

REQ-010-2 完成内容：
- 补充用户故事和细化验收标准
- 创建架构决策记录（MyBatis Plus 注解 + XML 映射文件混合方案）
- 对比了 3 种备选方案
- 分析了决策对系统架构、开发流程、运维管理的影响
- 识别了技术风险、业务风险和实施风险
- 定义了回滚策略和验收标准

文档更新：
- 创建 0010-database-table-design.md 架构决策记录
- 创建 0011-entity-mapper-create.md 架构决策记录
- 创建 0020-database-table-design-create.md 变更记录
- 创建 20260117-database-table-design-create.md 会话记录
- 创建 20260117-database-table-design-create-retro.md 复盘报告
- 创建 011-database-table-design-create.md 提示词文档
- 更新 REQ-010-2.md 需求文档
- 更新 docs/index.md 和 CHANGELOG.md
2026-01-18 19:44:13 +08:00

10 KiB
Raw Blame History

架构决策记录 (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 的具体节点或快照：

Status

  • Draft
  • Accepted
  • Superceded

参考资料

列出与该决策相关的参考资料，包括文档、文章或其他资源：