知识库

后端开发规范入口

reference
2026年7月20日阅读约 1 分钟133 字
项目规范
Spring Boot
Spring MVC
traceId

更新于 2026年7月20日

后端开发规范入口

仓库背景

  • 后端统一采用 Java 17、Maven、Spring Boot 3、Spring MVC 和 JUnit 5。
  • 后端是独立 Maven 模块：核心代码位于 backend/src/main/java/com/shgalaxy/assessment/，测试位于 backend/src/test/java/，构建清单位于 backend/pom.xml。
  • HTTP 接口采用 MVC 分层；供应商订单对账核心仍保持无 I/O 的确定性领域决策，由应用服务调用，不把 Web 上下文带入领域模型。

加载方式

本文件在任意后端任务中始终加载；只按当前任务追加主题规则：

任务 追加加载
任意 Java、Maven、后端模型或服务改动 01-foundation.md
下单安全、是否允许重建、供应商标识或人工审核 02-business-safety.md
状态、动作、决策字段、查询次数或时间调度 03-state-decisions.md
重复事件、终态、乱序时间或状态降级 04-idempotency-ordering.md
参数校验、供应商异常数据、错误码或异常处理 05-validation-errors.md
后端测试、Maven 验证、README/DECISIONS/AI_USAGE 06-testing-delivery.md
Controller、REST 接口、请求响应、CORS、日志、审计或 traceId 07-spring-mvc-traceid.md

一个任务涉及多个主题时全部加载。实现 BookingReconciliationService 时应加载 01 至 06；新增或修改 HTTP 接口时还必须加载 07；只改构建配置时通常只需 01 和 06。

优先级

  1. 根目录 AGENTS.md 的公共门禁。
  2. CANDIDATE_TASK.md 的业务要求。
  3. 当前源码、测试和 backend/pom.xml 的真实契约。
  4. 本目录已加载的主题规则。

后端硬性边界

  • 防止重复供应商订单优先于自动恢复和代码简洁。
  • 未知、冲突或不可证明安全的结果不得自动允许重建。
  • 保留 BookingReconciliationService.afterCreate(...) 和 afterQuery(...) 两个清晰业务入口。
  • 决策逻辑保持确定性和可解释性，不读取系统时间或可变全局状态。
  • 分层依赖保持 controller -> service -> repository/client；Controller 不直接访问持久层或供应商客户端。
  • 所有 HTTP 请求统一使用 X-Trace-Id；前端由公共请求客户端传入，后端由一个过滤器统一接收，不在每个 Controller 重复声明。