fastify-boilerplate：一个把架构规则写进 CI 的 Fastify 5 起点
Fastify 5 应用程序样板基于干净的架构、领域驱动设计、CQRS、函数式编程、垂直切片架构，用于构建生产级应用程序。
秒懂
- 它是什么？
- marcoturi/fastify-boilerplate 是一套基于 Fastify 5 的 TypeScript 样板，用 Clean Architecture、CQRS 和 DDD 组织代码，并把依赖边界检查放进 CI。它适合想省去架构搭建成本、又不想被框架绑死的团队。
- 适合谁用？
- 适合想要开箱即用的 Fastify 5 架构模板、又愿意接受 Node.js 24 和 pnpm 约束的团队。它把 Clean Architecture、CQRS、DDD 和依赖边界检查固化在代码与 CI 中，省去从零搭建的成本。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 2 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的是架构决策的成本问题
大多数 Fastify 模板只给路由和插件注册，架构要自己搭。这个项目把 Clean Architecture、CQRS、DDD、垂直切片和函数式编程全塞进一个起点里。它解决的问题不是写一个 CRUD 接口，而是让团队在项目第一天就有一套明确的边界，并且用工具强制这些边界。适合的对象是那些已经决定采用领域驱动设计、但不想花两周搭骨架的团队。如果你只需要一个给内部工具用的 API，这个模板的复杂度会变成负担。
架构边界由 dependency-cruiser 在 CI 强制
README 里反复强调架构是框架无关的，核心模式可以迁移到其他语言。它通过 dependency-cruiser 验证层边界，脚本是 pnpm deps:validate，在 CI 阶段跑。这意味着你可以在代码评审里写“这个 import 跨层了”，但更可靠的是机器直接拒绝合并。模块结构按垂直切片组织，每个模块包含自己的组件，而不是按技术类型分层。这种做法的好处是功能内聚，坏处是如果模块划分不当，后期重构模块边界会牵扯大量文件移动。README 没有给出模块组件的具体清单，但从目录结构推断，每个模块大概包含路由、控制器、服务、仓储等。
运行方式：Node.js 24 原生 TypeScript，无构建步骤
这个项目要求 Node.js >= 24，用原生 type stripping 运行 TypeScript，没有 build 步骤，也没有 transpiler。这是它最激进的决定。好处是开发时不用等编译，生产镜像更小。坏处是你的部署环境必须升级到 Node.js 24，否则跑不起来。启动流程是：npx degit marcoturi/fastify-boilerplate my-app，然后 pnpm install，pnpm create:env 复制 .env.example 为 .env，docker compose up postgres -d 启动数据库，pnpm db:migrate 跑迁移，最后 pnpm start 启动开发服务器，默认端口 3000。生产模式用 pnpm start:prod，不带 watch 和 pretty-print。Dockerfile 是多阶段构建，基于 Alpine，以非 root 用户运行，用 dumb-init 处理 PID 1 信号，还内置了 HEALTHCHECK 每 30 秒检查 /health。
REST 与 GraphQL 并存，类型自动发布到 npm
API 层同时提供 REST 和 GraphQL。REST 用 TypeBox 定义 schema，Swagger UI 在 /api-docs 提供交互文档，OpenAPI 3.1.0 JSON 在 /api-docs/json。GraphQL 用 Mercurius，开发环境有 GraphiQL。最特别的是客户端类型生成：pnpm generate:types 会生成 REST 和 GraphQL 的类型，并在每次 release 时自动发布到 npm。这意味着前端团队可以拿到和后端同步的类型包，不用手写接口类型。这个机制依赖运行中的服务器和数据库，所以生成类型前必须先把服务跑起来。如果你只想要 REST，GraphQL 那套依赖和端点会显得多余，但模板没有提供关闭它的开关。
测试策略：Cucumber E2E 加 node:test 单元测试
测试覆盖了三个层次。单元和集成测试用 node:test，不需要额外框架，脚本是 pnpm test:unit，覆盖率用 c8。E2E 测试用 Cucumber 和 Gherkin 语法，脚本是 pnpm test:e2e，但要求 Postgres 正在运行。负载测试用 k6，但 README 没有给出具体脚本。这套组合的好处是测试类型明确，坏处是 E2E 测试的启动条件较多，CI 里必须准备数据库服务。对于一个小型项目，Cucumber 的 Gherkin 层可能显得过重，因为你得维护 feature 文件和 step definitions。如果你只想跑单元测试，pnpm test 就是别名，但别指望它覆盖数据库交互。
工具链：Biome 替代 ESLint 和 Prettier，Commitlint 管提交
代码质量工具选了 Biome，一个工具同时做 lint、格式化和 import 排序，替代了 ESLint 和 Prettier 的组合。README 专门有一节解释为什么选 Biome，理由是减少工具链复杂度。提交规范用 Commitlint 和 Husky，发布用 Semantic Release，版本号自动生成。最近几个 release 是 v2.9.21 到 v2.9.23，间隔一天，说明维护活跃。另一个细节是 AGENTS.md 文件，专门给 AI 助手写架构规则和编码约定。对于用 AI 写代码的团队，这能减少 AI 生成不符合架构的代码。但这也意味着你维护模板时，要同步更新 AGENTS.md，否则 AI 会按旧规则生成代码。
限制与替代方案：不是所有项目都该用
最大的限制是 Node.js >= 24 的硬要求。如果你所在的公司还在用 Node.js 20 LTS，这个模板直接不可用。另一个限制是模板默认包含 GraphQL，但很多 REST-only 项目不需要它，移除 Mercurius 相关代码需要额外工作。还有一个隐患是依赖注入用了 Awilix，如果你不熟悉 DI 容器，调试时会有额外学习成本。替代方案是 fastify-cli 官方脚手架，它只提供基本的插件结构和启动逻辑，没有架构分层。另一个选择是 NestJS，它自带 DI、模块系统和装饰器，但绑定在 Express 或 Fastify 之上，架构风格是命令式的，而不是函数式。fastify-boilerplate 的差异在于它用依赖边界检查工具把架构规则变成可执行的 CI 检查，而 NestJS 靠框架约束。
维护与许可证：MIT 下的活跃项目
项目许可证是 MIT，可以自由使用和修改。维护节奏看起来稳定，最近三周内发布了三个版本，说明上游在持续修复和更新。但作为模板，你需要自己维护 fork 或定期同步上游变更。升级成本主要来自 Node.js 和 Fastify 的版本更新，因为模板直接绑定 Fastify 5。如果 Fastify 6 发布，模板的迁移工作会由上游处理，但你自己的业务代码可能因为插件 API 变化而需要调整。另一个维护点是依赖数量，模板集成了大量插件，每个插件都有自己的版本生命周期，你需要依赖 renovate 或类似工具来跟踪更新。README 没有提供升级模板的具体步骤，所以建议在 fork 时记录上游 commit 的基线，方便日后合并。
编辑结论
适合想要开箱即用的 Fastify 5 架构模板、又愿意接受 Node.js 24 和 pnpm 约束的团队。它把 Clean Architecture、CQRS、DDD 和依赖边界检查固化在代码与 CI 中，省去从零搭建的成本。不适合只需要简单 CRUD 的小服务，也不适合仍停留在 Node.js 20 或 22 的环境，因为原生 TypeScript 运行强制要求 Node.js 24。采用前先确认你的部署环境能升级到 Node.js 24，并跑通 pnpm test:e2e，因为 E2E 测试依赖 Postgres，本地没有 Docker 或数据库会卡住。它的 GraphQL 与 REST 双端点会增加初始理解成本，但依赖边界由 dependency-cruiser 在 CI 强制检查，架构不会悄悄腐烂。
社区笔记