fastify-architect
Architect-level Fastify guidance — schema-first routing and validation, plugin encapsulation boundaries, hook lifecycle ownership, serialisation performance, and the TypeScript typing patterns that keep schemas and handlers in sync. Use when choosing or reviewing Fastify for a Node API.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- fastify-architect
- license
- MIT
- metadata
- { "crusor-path": "website-architect/frontend-development-architect/react-architect/nodejs-architect/fastify-architect", "crusor-domain": "website-architect", "crusor-origin": "original", "crusor-sources": "fastify.dev/docs/latest; json-schema.org", "crusor-triggers": "fastify, fastify schema, fastify plugin, schema serializer, fastify hooks, json schema route, encapsulation", "crusor-verified-on": "2026-10-30" }
- description
- Architect-level Fastify guidance — schema-first routing and validation, plugin encapsulation boundaries, hook lifecycle ownership, serialisation performance, and the TypeScript typing patterns that keep schemas and handlers in sync. Use when choosing or reviewing Fastify for a Node API.
- compatibility
- Fastify 4/5; Node 20+
03 SKILL.md 正文
Fastify Architect
Fastify's advantages are schemas and encapsulation. Use it without them and you have paid the learning curve for an Express clone.
When to use
- JSON APIs where request/response schemas are the contract.
- Services where throughput and validation speed matter.
- Codebases that benefit from plugin-scoped encapsulation instead of global middleware.
When NOT to use
- Heavy server-rendered pages — an MVC framework is the better tool.
- A team that will not maintain JSON schemas; then schema-first is a liability.
Decision 1 — Schemas are the contract
- Every route declares
schema.body,querystring,params,response. - Response schemas are not optional: they drive fast serialisation and prevent accidental field leakage.
- Schema → TypeScript types via
json-schema-to-tsortypebox, so a schema change breaks compilation, not production. - Validation errors are mapped once (
setErrorHandler) into your envelope.
Decision 2 — Plugins and encapsulation
app.ts register plugins, no routes
plugins/db.ts fastify-plugin (decorates, shares)
routes/v1/*.ts encapsulated routers
fastify-pluginbreaks encapsulation deliberately — use it only for infrastructure that must decorate the root (db, config, auth).- Feature plugins stay encapsulated: their decorators/hooks do not leak.
- Register order matters; document it (config → db → auth → routes).
Decision 3 — Lifecycle hooks
| Hook | Use |
|---|---|
onRequest |
request id, rate limit |
preValidation |
raw body checks |
preHandler |
auth/authorisation, load entity |
onSend |
response headers, mapping |
onClose |
release resources |
- Hooks are applied at the narrowest scope that needs them; a root-level hook affects every route including health checks — usually wrong.
- Async hooks must be awaited: a forgotten
awaitreorders the pipeline. - Auth via
decorate+preHandler, and skip explicit for public routes.
Decision 4 — Performance and deployment
pinologging with redaction; request ids in every line.- Keep the event loop clean: no sync fs/crypto in handlers, offload CPU work to workers.
connectionTimeout/requestTimeoutset explicitly; defaults are generous.- Graceful shutdown on
SIGTERM:fastify.close()after draining.
Failure modes at scale
- Schemas declared for requests but not responses → leaks and slow serialisation.
fastify-pluginused everywhere, encapsulation gone, root decorated by five features.- Root-level auth hook plus a growing
if (route === ...)exception list. - Schema drift from TS types discovered at runtime.
- Error handler that returns 200 with an error body.
Verification receipts
- Every route has body + response schemas (script-checked).
- Validation rejection test: extra field, wrong type, oversized payload.
- Response test: no field outside the schema is serialised.
- Hook scope review: which hooks are root-level and why.
- Load test: throughput and p95 with the real schema set.
04 同仓库更多 Skills
interaction-patterns-architect
Architect-level interaction design in code — choosing established patterns over invented ones, feedback and latency behaviour, destructive-action safeguards, navigation and overlay conventions, and the state model behind every interactive surface. Use when a screen has to behave, not just look.
design-system-ops-architect
Architect-level operation of a design system in code — token pipelines and versioning, component API and variant policy, the catalogue as the contract, adoption metrics, and the governance that stops a system from forking into three. Use when a component library must survive several teams.
design-handoff-architect
Architect-level design handoff — what must be specified before implementation starts, tokens over raw values, responsive and content-limit contracts, state matrices, and the review loop that catches drift between design and code. Use when a design is about to become code.
content-microcopy-architect
Architect-level UI content — where strings live, voice and terminology consistency, error and empty-state copy as part of the interface, translation-ready authoring, and the content model a product needs before it multiplies screens. Use when the words in the interface matter as much as the pixels.
ui-ux-implementation-architect
Architect-level direction for turning a design into working UI — the handoff contract, component ownership versus screen-level layout, interaction and state conventions, design QA gates, and the review habits that keep an implementation faithful without frozen pixels. Use before any specific UI implementation skill.
test-strategy-architect
Architect-level test strategy — allocating assertions across unit, integration, contract and end-to-end layers, designing for testability through dependency boundaries, fixture and data strategy, and the flake and coverage policies that keep a suite trustworthy. Use when defining how a codebase is tested.