Files
persionalBrand/docs/adr/0027-api-module-boundaries-and-route-regression.md

3.0 KiB
Raw Permalink Blame History

0027. API Module 边界与路由防回潮

Context

多品牌 API 已经按 public、customer、admin 领域拆分 Controller,但 AppModule 仍一次性注册所有 Controller 和 Provider,后台 workspace Controller 也承担了 offerings、template、capability、inquiry 等多个资源入口。连续重构后,API 模块需要明确共享层、领域层和根模块的职责边界,并用测试防止后续路由意外变化。

Decision

  • API 根模块只负责组装领域 Module 和全局配置,不直接注册领域 Controller 或业务 Provider。
  • 领域 Module 按职责拆分为 PublicModule、CustomerModule、SessionModule、TenantModule、WorkspaceModule、AdminModule、BookingModule、HealthModule。
  • PrismaService、鉴权、模板工作区、发布快照等跨领域基础设施统一放在 InfrastructureModule,由领域 Module 显式导入。
  • 共享 infrastructure 不得 import feature module;feature 之间的依赖必须通过被导入 Module 的显式 export 暴露。
  • workspace 后台路由按资源拆分 Controller,但保持 URL、方法、请求体和响应契约不变。
  • 路由清单测试锁定拆分后的 admin workspace 与 uploads 路由;新增或迁移路由必须同步更新清单测试。
  • Controller 只处理 transport:路由、DTO、鉴权入口、状态码和响应形状;key 生成、存储、持久化和校验进入 service。

Alternatives

  1. 继续在 AppModule 集中注册所有 Controller 和 Provider:启动简单,但任何领域变更都会触碰根模块,依赖边界无法约束。
  2. 为每个 Controller 建立独立 Module:文件更多,且共享服务容易重复实例化,不适合当前规模。
  3. 只靠 code review 约束路由不变:无法防止路由搬迁或前缀拼写错误,不能作为回归门槛。

Consequences

Positive

  • 领域边界与依赖方向清晰,新增领域时不会继续膨胀根模块。
  • 共享服务单例归属明确,跨 Module 依赖必须在 export / import 中显式声明。
  • 路由清单测试为 API 路径提供防回潮保护,降低连续拆分的风险。
  • Controller 更薄,授权与业务行为更容易通过 service 单测和 HTTP 集成测试分层验证。

Negative

  • Module 数量和文件数量增加,新成员需要先理解组装关系。
  • 路由新增或迁移必须同步维护清单测试。
  • 共享服务放入 infrastructure 前需要确认是否真的跨领域,避免形成新的上帝层。

Migration Plan

  1. 已完成 workspace Controller 和 AppModule 领域化拆分。
  2. 已完成媒体上传 DTO、service 与 controller 边界拆分。
  3. 已加入路由清单测试、上传服务边界测试和完整 HTTP 集成回归。
  4. 后续新增 API 领域时先创建领域 Module,再由根模块组装;新增后台路由必须加入路由清单测试。
  5. 剩余大 Controller 在修改对应领域时按同一规则逐步下沉 service,不做无行为收益的大规模搬迁。