NestJS Scaffold

主题

核心理念 ​

理解这个项目为什么要这样构建，比记住它的 API 更重要。这篇文章解释本基线模板背后的三个核心理念，以及它们如何相互支撑。

为什么需要定义理念？ ​

一个项目如果只有"如何做"的文档，没有"为什么这么做"的思考，那后来的开发者（包括未来的你，以及 AI 助手）就只能靠猜测来决策。猜测带来不一致，不一致带来混乱。

本项目的三个核心理念不是装饰性的，而是每一个架构决策的来源。

Harness Engineering ​

构建一个能让 AI 可靠协作的环境。

这是这个项目最具前瞻性的核心思想。随着 AI 辅助编程的普及，"怎么写好代码"已经不够了——还需要思考"怎么让 AI 能写好代码"。

Harness Engineering 的核心论点是：AI 的输出质量，70% 取决于你提供给它的环境，30% 才是模型本身的能力。

这个项目所有的"奇怪设计"——详细的 AGENTS.md、精心维护的架构文档、错误码目录、完善的测试套件——本质上都是 Harness Engineering 的产物。它们共同构成一个引导 + 感知 的闭环控制系统：

  • 引导层：AGENTS.md、架构文档、Skill 文档 — 告诉 AI 应该怎么做
  • 感知层：TypeScript 编译、ESLint、Jest、CI 流水线 — 验证 AI 是否真的做对了

想深入了解？看这里：Harness Engineering →

文档即代码 ​

文档和代码同等重要，必须同步演进。

"文档即代码"不是比喻，而是一种工程实践：

  • 文档和代码在同一个仓库里，同一个 PR 里一起提交
  • 文档有自己的质量标准（docs/STANDARD.md），就像代码有 lint 规则
  • 文档有版本号（frontmatter version 字段），和代码版本对应
  • 文档的正确性通过人工 + 工具双重验证（文档漂移审计）

这个项目选择在文档上投入如此多的精力，根本原因是：

  1. Harness Engineering 需要：AI 读取的是文档。如果文档是错的，AI 会基于错误的认知做决策。
  2. 团队协作需要：新成员能快速上手，因为"约定"是文档化的，而不是口耳相传的。
  3. 长期维护需要：六个月后回来看一个设计决策，文档里有"为什么这么选择"的解释，比只有代码好太多了。

衡量"文档即代码"是否真的落地，可以问一个问题：上次修改了某个模块的代码，对应的架构文档有没有同步更新？ 如果没有，这个理念就还停留在口号阶段。

测试驱动开发 ​

测试是功能交付的一部分，不是可选的附属品。

TDD（Test-Driven Development）在这个项目里的含义不是教条式的"先写测试再写代码"，而是一种可操作的质量契约：

对 Service 层：必须有单元测试，Mock 掉 Repository 层，专注验证业务逻辑。这确保了业务规则可以独立于数据库进行验证。

对 API 端点：必须有 E2E 测试，使用真实数据库，验证完整的请求-响应链路。这确保了接口契约的稳定性。

完成的定义：pnpm test 通过是任务完成的硬性门槛，和 pnpm lint 与 pnpm build 并列——不是都过了，就不算完成。

这三个理念相互依存： Harness Engineering 需要测试作为感知传感器，文档即代码让测试的设计意图可被理解，而 TDD 的测试套件又是最可靠的 Harness Engineering 感知层。

开发原则 ​

除了上述三个核心理念，本项目在代码层面严格遵循以下原则。这些原则是开发时的决策框架，而不是架构的全局策略：

除了上述三个核心理念，本项目在代码层面严格遵循以下原则。这些原则是开发时的决策框架，而不是架构的全局策略：

面向切面编程（AOP）

横切关注点（认证、日志、性能监控、异常处理）通过 NestJS 的守卫/拦截器/过滤器机制统一实现，不侵入业务逻辑。如果你发现某段业务 Service 代码里有 try/catch 包着日志，那就说明这个原则被违反了。

SOLID 原则

  • SRP：每个类只有一个被修改的理由（Controller 改接口、Service 改逻辑、Repository 改数据访问）
  • OCP：扩展通过新增实现，不修改现有代码（新守卫通过 APP_GUARD token 注册）
  • DIP：高层模块不依赖底层实现，通过 NestJS IoC 容器注入

其他关键原则

  • DRY：常量在 src/constants/ 定义，工具函数在 src/common/utils/ 维护，不重复实现
  • KISS：最简单的解决方案往往是最好的，能用简单条件判断解决的不用设计模式

这些原则在 AGENTS.md 的第 1 节中有更详细的展开，也是 AI 进行代码审查时的核心依据。

接下来做什么？ ​