前言¶
用 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。
