nestjs-architecture-principles

NestJS 架构与原则

根据代码仓库的实际约束做出架构决策。优先选择复杂度最低的设计，同时保护必要的边界，并确保能够安全演进。

执行前冲突检查

在编辑文件或运行任何会改变状态的命令之前，协调当前生效的指令。只读检查可以继续。

前提条件

检查仓库指令、已安装的版本、模块接线、契约、调用方、测试和受影响的命令。保留用户所做的更改。仅在其他生效技能的决策与当前工作重叠时，才阅读这些技能。

主要职责

此技能负责架构层级、能力/模块 API、依赖方向、数据/写入与事务边界、端口以及服务抽取。安装了以下技能且与当前工作相关时，应与其协同：

• nestjs-oop-design-patterns：对象职责、不变量和模式。
• nestjs-features-performance：生命周期、API/安全、测试、运行时和性能。
• nestjs-professional-software-engineering：实现与验证。
• nestjs-code-audit：只读质量证据和去重报告。
• nestjs-feature-audit：特定分支的路线图关卡和功能报告。
• nestjs-git-commit-pr-message：经授权的 Git 发布和 CI 后续工作。

这些是决策边界，而非必需的依赖项。将工作交给其他工作流时，仍须保留领域职责。

冲突检查

检查是否存在互不兼容的编辑/契约、命令顺序或副作用、职责冲突，以及尚未满足的版本、证据、授权或仓库前提条件。按照明确的用户意图、仓库契约、已验证的运行时约束，再到职责范围最窄的技能来解决。每项决策只指定一位负责人；不要为了满足互不兼容的建议而设计并行方案。如果仍存在重大冲突，应在修改前暂停，并询问最少的必要决策。审计必须保持只读；明确的修复授权仅适用于独立的实现阶段。

以证据为先

在建议或更改架构之前：

1. 阅读 package.json、nest-cli.json、TypeScript 配置、引导文件和相关模块。
2. 梳理模块导入图、提供者导出、入口点、持久化职责、传输方式和现有测试。
3. 确定业务能力和具体的变更压力：团队职责归属、独立扩缩容、易变集成、事务边界、安全或交付速度。
4. 用一句话说明当前架构。不要仅凭文件夹名称就将项目称为“整洁架构”或“领域驱动设计（DDD）”。
5. 保留合理的本地惯例。只有当某项惯例损害正确性、安全性、可运维性或明确契约时，才指出问题。

如果任务与版本有关，在使用 API 或命令之前，先核实已安装的 NestJS 版本和最新官方文档。

选择架构层级

使用 references/architecture-ladder.md 中的架构阶梯。

默认方向：

• 从按业务能力组织的模块化单体开始。
• 只有当领域逻辑或基础设施易变性使边界具有价值时，才增加内部层。
• 只有当应用需要隔离可替换的外部关注点时，才增加端口。
• 只有当命令与查询行为确实出现分歧时，才采用 CQRS。
• 只有当服务拥有独立的部署、职责归属、扩缩容、数据或故障边界时，才拆分服务。

切勿仅为让目录结构看起来像某张图，就引入层、总线、仓储、工厂或服务。

保护这些边界

1. 模块只公开小型公共 API。 除非其他模块确实需要使用，否则提供方应保持私有。
2. 业务能力负责维护自身的不变量并执行写入。 其他模块通过导出的应用服务、端口、事件或经过精心设计的只读模型进行协作。
3. 依赖指向策略。 领域代码不得导入 NestJS、ORM、HTTP 类型、队列任务或供应商 SDK。
4. 控制器和传输处理器负责适配。 它们通过框架机制进行身份验证和授权，验证传输输入，调用应用操作，并映射结果。
5. 应用操作负责协调。 它们定义用例流程和事务意图，但不吸收持久化或传输细节。
6. 基础设施负责实现边界。 ORM、消息代理、缓存、文件系统和外部 API 应置于明确的边界之后，前提是它们的易变性或测试成本足以证明这样做的必要性。
7. 循环依赖是设计反馈。 将 forwardRef() 视为最后的兼容手段，而不是默认修复方式。
8. 组合根负责装配。 Nest 模块和提供方负责组装实现；业务对象不得在运行时自行查找依赖。

如需查看整合后的规则集，请加载 references/architecture-rules.md。如需了解 NestJS 边界的详细信息，请加载 references/module-boundaries.md 和 references/dependency-injection.md。

务实地应用原则

将 references/engineering-principles.md 用作决策检验标准，而不是口号。

原则发生冲突时，优先级如下：

1. 正确性、安全性和数据完整性；
2. 明确的外部契约和向后兼容性；
3. 可运维性和故障隔离；
4. 仓库中已确立的惯例；
5. 设计的纯粹性和局部的优雅性。

KISS 不意味着掩盖失败情况。DRY 不意味着抽象偶然的相似性。SOLID 不要求每个动词都对应一个类。YAGNI 不能成为忽视已知需求所要求的边界的借口。

工作流

对于新设计

1. 明确目标、约束、非目标、关键质量属性和预期的变化维度。
2. 选择能够满足这些要求的最低架构层级。
3. 先命名能力和所有权，再命名技术层。
4. 绘制依赖关系和数据所有权。拒绝模糊的写入所有权。
5. 明确同步调用、事件、事务和故障行为。
6. 提出一个推荐设计，并说明它有意不优化的方面。
7. 定义能够守护该决策的架构测试、集成测试和运维检查。

对于实现或重构

1. 从头到尾追踪相关请求、消息或任务。
2. 找出导致问题的最小边界违规。
3. 添加抽象之前，先将行为移至其所属方。
4. 仅当存在多个实现、易变边界或有价值的测试接缝时，才引入端口。
5. 逐步进行更改，并保留公共契约，除非用户要求迁移。
6. 更新受影响的测试、模块装配、文档和调用方。

对于评审

使用 references/architecture-review.md。报告有证据支持的发现，并说明严重性、影响、最小修复方案和验证步骤。边界修复足以解决问题时，不要建议重写。

参考路由

有关面向消费者的承诺以及可执行的 wiring／行为控制，请参阅 module-contracts.md。

任务	加载
应用或审查整合后的架构规则	architecture-rules.md
选择模块化单体、分层架构、六边形架构、CQRS 或服务	architecture-ladder.md
设计功能模块、导出、所有权或移除循环依赖	module-boundaries.md
定义 provider token、端口、作用域、工厂或动态模块	dependency-injection.md
定义数据库所有权、仓储、迁移、事务或 ORM 边界	database-orm.md
决定服务拆分、分布式数据所有权、契约或消息语义	microservices.md
应用 KISS、YAGNI、DRY、内聚、耦合和依赖规则	engineering-principles.md
审查代码库或规划渐进式迁移	architecture-review.md

预期答复

对于架构工作，请让结果便于评估：

• 基线： 当前架构及其依据。
• 决策： 一个推荐方向。
• 原因： 推动该方向的约束和权衡。
• 边界： 模块所有权、依赖方向、数据所有权和集成方式。
• 迁移： 需要变更时，最小且安全的步骤。
• 验证： 测试、图检查、运行时检查和运维信号。

如果没有理由变更架构，请直接说明。