前言¶
用 Fastify 搭 REST API 时，路由怎么拆、插件怎么封装、请求校验和响应序列化怎么配，往往要对照官方文档和仓库里的示例来回翻。把 AI 助手拉进协作后，它给出的代码有时偏 Express 习惯，有时忽略 Fastify 的封装边界和 Schema-first 约定。下面介绍 fastify-best-practices 这套 Skill：在构建、配置或排查 Fastify 应用时，让助手按同一套规则文件给出建议与示例。
这是什么¶
fastify-best-practices 是一份面向 AI 辅助开发的说明文档（SKILL.md 及 rules/ 下的分主题规则），用于指导用 JavaScript 或 TypeScript 开发 Fastify 后端与 REST API。官方目录在 mcollina/skills 仓库的 skills/fastify；该仓库由 Matteo Collina 维护，其中 fastify Skill 在仓库索引里描述为「Comprehensive best practices for Fastify development」。Skill 元数据中的触发场景包括：定义路由、实现插件、JSON Schema 校验、错误处理、性能、认证、CORS 与安全头、数据库、WebSocket、生产部署，以及完整请求生命周期（hooks、序列化、Pino 日志）和通过 strip types 的 TypeScript 集成。
核心功能¶
Skill 把实践拆成可单独阅读的规则文件，助手在相关任务下按需加载对应章节。
规则主题（与官方列表一致）¶
| 文件 | 侧重 |
|---|---|
rules/plugins.md |
插件开发与封装 |
rules/routes.md |
路由组织与 handler |
rules/schemas.md |
JSON Schema 校验 |
rules/error-handling.md |
错误处理模式 |
rules/hooks.md |
Hooks 与请求生命周期 |
rules/authentication.md |
认证与授权 |
rules/testing.md |
使用 inject() 做测试 |
rules/performance.md |
性能优化 |
rules/logging.md |
使用 Pino 记录日志 |
rules/typescript.md |
TypeScript 集成 |
rules/decorators.md |
装饰器与扩展 |
rules/content-type.md |
Content-Type 解析 |
rules/serialization.md |
响应序列化 |
rules/cors-security.md |
CORS 与安全头 |
rules/websockets.md |
WebSocket |
rules/database.md |
数据库集成模式 |
rules/configuration.md |
应用配置 |
rules/deployment.md |
生产部署 |
rules/http-proxy.md |
HTTP 代理与 reply.from() |
文档中强调的原则¶
- Encapsulation：插件系统自动封装作用域。
- Schema-first：用 Schema 做校验与序列化。
- Performance：在正确使用内置能力的前提下发挥框架性能取向。
- Async/await：handler 与 hook 均支持异步函数。
- Minimal dependencies：优先 Fastify 内置能力与官方插件。
常见场景下的阅读顺序¶
官方在 Skill 里给出了分场景路径，便于助手或人工按任务跳转：
- 刚接触 Fastify：
plugins.md→routes.md→schemas.md - 加认证：
plugins.md→hooks.md→authentication.md - 做性能：
schemas.md→serialization.md→performance.md - 写测试：
routes.md→testing.md - 上生产：
logging.md→configuration.md→deployment.md
安装与启用¶
Agent Skill 本质是文本指令包，各平台加载方式不同；下列方式来自社区索引 awesome-agent-skills 的通用说明，安装对象指向 GitHub 上的 Skill 源（本 Skill 路径为 mcollina/skills 下的 skills/fastify）。
- npx skills CLI（见 vercel-labs/skills）：
npx skills find fastify
npx skills add mcollina/skills
npx skills list
-
Claude Code：在环境中执行
/skills add，参数为 Skill 的 GitHub 地址（例如仓库 URL 或指向skills/fastify的 raw 路径，以你当前 Claude Code 文档为准）。 -
Claude.ai：在新对话中粘贴
SKILL.md的 raw URL，让模型读取完整说明。 -
Codex / GitHub Copilot 等：按各产品文档中的 Agent Skills 章节，将仓库或 Skill 目录加入技能列表；社区索引将 Cursor、Copilot、Gemini CLI 等列为兼容环境，具体菜单以对应文档为准。
启用后，在对话里描述 Fastify 相关任务（例如「用 TypeScript 加一个带 Schema 的 POST 路由」），助手应匹配 Skill 描述中的触发词（如 Fastify、REST API、server.ts）并读取对应 rules/*.md。
典型用法¶
Skill 自带的 Quick Start 是一段可直接运行的最小服务：开启 Pino 日志、注册 /health、监听 0.0.0.0:3000。
import Fastify from 'fastify'
const app = Fastify({ logger: true })
app.get('/health', async (request, reply) => {
return { status: 'ok' }
})
const start = async () => {
await app.listen({ port: 3000, host: '0.0.0.0' })
}
start()
实际项目里更常见的用法是让助手按规则文件组合能力，例如：在 plugins.md 的封装方式下注册路由模块；在 schemas.md 为 body/query 定义 JSON Schema；在 error-handling.md 统一错误响应；在 testing.md 用 inject() 做无端口 HTTP 测试。上述文件名与能力均来自官方 Skill 目录，不额外虚构业务案例。
适用场景与注意¶
适合谁
- 正在用或打算用 Fastify 写 Node.js 后端、REST API 的团队，希望 AI 输出与框架惯例一致。
- 需要覆盖从路由、插件到部署、WebSocket、数据库的一整条链路，而不是零散代码片段的开发者。
何时应激活 Skill（官方 When to use）
- 开发 Fastify 后端、实现插件与路由 handler。
- 需要架构与模式上的 Fastify 导向建议。
- 使用 TypeScript（含 strip types）、
inject()测试，或配置校验、序列化与错误处理。
注意
- Skill 是「怎么做」的说明，不包含替你安装 Node 依赖或选定云厂商；部署细节以
deployment.md与你自己环境为准。 - 同一仓库 mcollina/skills 还提供
node、oauth等相邻 Skill，OAuth 与 Fastify 集成时可与oauthSkill 配合，但本文仅核实fastify目录内容。 - 助手是否每次都正确选中本 Skill，取决于平台的技能发现与描述匹配；任务描述里带上 Fastify、路由、Schema 等词更稳妥。
结尾¶
fastify-best-practices 把 Fastify 作者维护的实践拆成可检索的规则文件，覆盖请求生命周期、Schema、插件封装到生产部署。若你希望在 AI 协作里少踩「像 Express 但不是 Fastify」的坑，可以把该 Skill 加入常用技能列表。官方地址：https://github.com/mcollina/skills/tree/main/skills/fastify。
