AGENT SKILL

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-ts or typebox, 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-plugin breaks 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 await reorders the pipeline.
  • Auth via decorate + preHandler, and skip explicit for public routes.

Decision 4 — Performance and deployment

  • pino logging with redaction; request ids in every line.
  • Keep the event loop clean: no sync fs/crypto in handlers, offload CPU work to workers.
  • connectionTimeout/requestTimeout set 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-plugin used 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

  1. Every route has body + response schemas (script-checked).
  2. Validation rejection test: extra field, wrong type, oversized payload.
  3. Response test: no field outside the schema is serialised.
  4. Hook scope review: which hooks are root-level and why.
  5. Load test: throughput and p95 with the real schema set.

04 同仓库更多 Skills

SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0