Fastify

作者 bobmatnyc718070a7d622MIT77 个星标收录于 2026年10月8日更新于 2026年10月8日仓库2个月前更新

Production Fastify (TypeScript) patterns: schema validation, plugins, typed routes, error handling, security hardening, logging, testing with inject, and graceful shutdown

仅含说明Software Development
AI 生成的概览

用于构建生产级 Fastify TypeScript API 的参考模式，涵盖模式校验、插件与测试。

功能
提供在 TypeScript 中构建 Fastify 后端的指导与代码示例，涵盖使用 Zod 或 TypeBox 类型提供者的模式校验、插件封装、类型化路由、集中式错误处理、安全中间件、日志、优雅关闭，以及使用 inject 进行内存路由测试。它是说明性参考资料而非可执行工具，产出的是模式与代码片段，而不是文件或运行中的服务。
适用场景
适用于构建或审查基于 Fastify 的 TypeScript Node 后端，并希望获得校验、插件结构、错误处理、安全加固或测试方面的成熟模式时。也可用于在 Fastify 与 Express 之间，或在 Zod 与 TypeBox 之间做选择时。
运行要求
不需要脚本或工具，仅为说明性内容。若要实践示例，需要 Node.js 运行时以及 Fastify，可选包包括 Zod、TypeBox、@fastify/helmet、@fastify/cors、@fastify/rate-limit，以及 Vitest 等测试运行器。

Fastify (TypeScript) - Production Backend Framework

Overview

Fastify is a high-performance Node.js web framework built around JSON schema validation, encapsulated plugins, and great developer ergonomics. In TypeScript, pair Fastify with a type provider (Zod or TypeBox) to keep runtime validation and static types aligned.

Quick Start

Minimal server

✅ Correct: basic server with typed response

ts
import Fastify from "fastify";
const app = Fastify({ logger: true });
app.get("/health", async () => ({ status: "ok" as const }));
await app.listen({ host: "0.0.0.0", port: 3000 });

❌ Wrong: start server without awaiting listen

ts
app.listen({ port: 3000 });console.log("started"); // races startup and hides bind failures

Schema Validation + Type Providers

Fastify validates requests/responses via JSON schema. Use a type provider to avoid duplicating types.

Zod provider (recommended for full-stack TypeScript)

✅ Correct: Zod schema drives validation + types

ts
import Fastify from "fastify";import { z } from "zod";import { ZodTypeProvider } from "fastify-type-provider-zod";
const app = Fastify({ logger: true }).withTypeProvider<ZodTypeProvider>();
const Query = z.object({ q: z.string().min(1) });
app.get(  "/search",  { schema: { querystring: Query } },  async (req) => {    return { q: req.query.q };  },);
await app.listen({ port: 3000 });

TypeBox provider (recommended for OpenAPI + performance)

✅ Correct: TypeBox schema

ts
import Fastify from "fastify";import { Type } from "@sinclair/typebox";import { TypeBoxTypeProvider } from "@fastify/type-provider-typebox";
const app = Fastify({ logger: true }).withTypeProvider<TypeBoxTypeProvider>();
const Params = Type.Object({ id: Type.String({ minLength: 1 }) });const Reply = Type.Object({ id: Type.String() });
app.get(  "/users/:id",  { schema: { params: Params, response: { 200: Reply } } },  async (req) => ({ id: req.params.id }),);
await app.listen({ port: 3000 });

Plugin Architecture (Encapsulation)

Use plugins to keep concerns isolated and testable (auth, db, routes).

✅ Correct: route plugin

ts
import type { FastifyPluginAsync } from "fastify";
export const usersRoutes: FastifyPluginAsync = async (app) => {  app.get("/", async () => [{ id: "1" }]);  app.get("/:id", async (req) => ({ id: (req.params as any).id }));};

✅ Correct: register with a prefix

ts
app.register(usersRoutes, { prefix: "/api/v1/users" });

Error Handling

Centralize unexpected failures and return stable error shapes.

✅ Correct: setErrorHandler

ts
app.setErrorHandler((err, req, reply) => {  req.log.error({ err }, "request failed");  reply.status(500).send({ error: "internal" as const });});

Security Hardening (Baseline)

Add standard security plugins and enforce payload limits.

✅ Correct: Helmet + CORS + rate limiting

ts
import helmet from "@fastify/helmet";import cors from "@fastify/cors";import rateLimit from "@fastify/rate-limit";
await app.register(helmet);await app.register(cors, { origin: false });await app.register(rateLimit, { max: 100, timeWindow: "1 minute" });

Graceful Shutdown

Close HTTP server and downstream clients (DB, queues) on SIGINT/SIGTERM.

✅ Correct: close on signals

ts
const close = async (signal: string) => {  app.log.info({ signal }, "shutting down");  await app.close();  process.exit(0);};
process.on("SIGINT", () => void close("SIGINT"));process.on("SIGTERM", () => void close("SIGTERM"));

Testing (Fastify inject)

Test routes in-memory without binding ports.

✅ Correct: inject request

ts
import Fastify from "fastify";import { describe, it, expect } from "vitest";
describe("health", () => {  it("returns ok", async () => {    const app = Fastify();    app.get("/health", async () => ({ status: "ok" as const }));
    const res = await app.inject({ method: "GET", url: "/health" });    expect(res.statusCode).toBe(200);    expect(res.json()).toEqual({ status: "ok" });  });});

Decision Trees

Fastify vs Express

  • Prefer Fastify for schema-based validation, predictable plugins, and high throughput.
  • Prefer Express for minimal middleware and maximal ecosystem familiarity.

Zod vs TypeBox

  • Prefer Zod for app codebases that already standardize on Zod (forms, tRPC, shared types).
  • Prefer TypeBox for OpenAPI generation and performance-critical validation.

Anti-Patterns

  • Skip request validation; validate at boundaries with schemas.
  • Register everything in main.ts; isolate routes and dependencies into plugins.
  • Return raw error objects; return stable error shapes and log the details.

Resources

来源与署名

来源：bobmatnyc/claude-mpm-skills位于toolchains/typescript/frameworks/fastify提交718070a

许可证： MIT

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 bobmatnyc/claude-mpm-skills 的技能

Wordpress Security Validation

bobmatnyc

讲解以安全为先的 WordPress 开发模式，涵盖 nonce、清理、验证与输出转义。

Security772个月前更新

Bug Fix

bobmatnyc

提供结构化的缺陷修复流程：复现、定位根因、修复、验证、补充回归测试并记录 PR。

Software Development772个月前更新

Threat Modeling

bobmatnyc

运行轻量级 STRIDE 威胁建模工作坊，并将识别出的风险转化为缓解措施、工单和测试。

Security772个月前更新

Webapp Testing

bobmatnyc

提供 Playwright 模式的参考指南，用于编写 Web 应用测试，涵盖选择器、等待、断言与调试。

Software Development772个月前更新

Opentelemetry

bobmatnyc

提供使用 OpenTelemetry 为服务埋点并通过 Collector 导出 OTLP 遥测的参考指导。

DevOps & Cloud772个月前更新

Skill Creator

bobmatnyc

指导如何创建、组织并打包模块化的智能体技能，并运用渐进式披露。

AI & Agents772个月前更新

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精选

依据从远程来源获取的 Web Interface Guidelines 审查 UI 代码，并以 file:line 形式报告问题。

Software Development32K5周前更新

Vercel React Native Skills

vercel-labs

精选

React Native 与 Expo 最佳实践规则，涵盖列表性能、动画、导航、UI 模式、状态与 monorepo 配置。

Software Development32K5周前更新

Vercel React Best Practices

vercel-labs

精选

Vercel 的 React 与 Next.js 性能指南，以 70 条规则的形式用于编写、审查和重构代码。

Software Development32K5周前更新