docs: 记录API模块边界决策
This commit is contained in:
1 parent
2ad009f5c0
commit
0f6ad8b993
1 file changed
+44
@@ -0,0 +1,44 @@
|
||||
# 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,不做无行为收益的大规模搬迁。
|
||||
Reference in new issue
Block a user