3.2 KiB
3.2 KiB
Common Core 模块指引
数据库访问与中文注释约束
- 强制遵守根
../AGENTS.md的“数据库访问与中文代码注释”全部规则：正常业务访问统一为Controller → Service → Repository → Mapper，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。 - 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
职责边界
- 提供不依赖具体业务域的返回模型、异常、基础实体和 MyBatis-Plus 通用配置。
- 不引入订单、仓库、租户等领域实体，不调用业务服务，也不承载 Controller。
快速索引
| 功能 | 入口 |
|---|---|
| 统一响应与分页 | src/main/java/com/baiyue/common/core/api/ApiResponse.java、PageResult.java |
| 返回码与下游 code 还原 | src/main/java/com/baiyue/common/core/api/ResultCode.java；成功码是字符串 "200"，ResultCode.of 的未知 code 降级为 B0001 |
| 业务异常 | src/main/java/com/baiyue/common/core/exception/BizException.java |
| 通用审计字段 | src/main/java/com/baiyue/common/core/model/BaseEntity.java |
| MyBatis-Plus 与审计人 | src/main/java/com/baiyue/common/core/mybatis/ |
| 有限重试与退避 | src/main/java/com/baiyue/common/core/retry/BoundedRetryPolicy.java；供多个服务的 Outbox 复用，不拥有持久化或投递逻辑 |
| 人工重试事务与凭据 | src/main/java/com/baiyue/common/core/outbox/OutboxOperations.java、EventOperationsTokenGuard.java；三个生产服务显式选择本库表及事件白名单，锁定 DEAD 原记录，状态恢复与审计同事务；不访问其他服务数据库或直接投递事件 |
| 逐次投递审计事务 | src/main/java/com/baiyue/common/core/outbox/EventDeliveryJournal.java；领取与STARTED、持有者CAS完成与审计各自同库REQUIRES_NEW事务；HTTP在两个事务之间执行，迟到结果不得写入；JDBC为optional依赖，Print等无数据库服务不被引入JDBC |
| 响应契约测试 | src/test/java/com/baiyue/common/core/ApiResponseTest.java |
修改与验证
- 公共响应、错误码或基础实体变化会影响所有服务；先检索并同步修改全部消费者、测试和契约。当前正式模型不保留旧序列化或数据库兼容分支；若已有不可变外部契约，先单独定义升级规则。
ApiResponse.successful()只认字符串"200"。不得恢复旧成功码"0"，也不得把code改成数字；前端和 Feign 调用方都按字符串严格判断。ResultCode.httpStatus保留错误分类元数据，但普通业务异常的实际 HTTP 状态由common-web/GlobalExceptionHandler统一收敛为 200；真实 HTTP 状态例外见../docs/统一响应约定改造方案-HTTP200.md。- 新能力只有被多个模块稳定复用时才放入本模块。
- 从父目录运行
mvn -pl common-core -am test。