nodejs-backend-patterns
Node.js backend architecture: use when building or refactoring Fastify/Express services that need fail-fast schema validation, layered controller/service/repository separation, pooled transactional data access, a single error envelope, or drain-based shutdown.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- nodejs-backend-patterns
- metadata
- { "category": "reference" }
- description
- Node.js backend architecture: use when building or refactoring Fastify/Express services that need fail-fast schema validation, layered controller/service/repository separation, pooled transactional data access, a single error envelope, or drain-based shutdown.
02 资源文件 1
- 参考文档resources/implementation-playbook.md8.3 KB
03 SKILL.md 正文
Node.js Backend Patterns
Operational architecture guide for Node.js backends: fail-fast contracts, layered responsibilities, pooled data access, one envelope, graceful drain.
Stack Defaults
- Default: Fastify + TypeScript + PostgreSQL (
pg) + Zod + Pino. - Express: Use when integrating into existing Express middleware pipelines.
- MongoDB: Use when document datastores are mandated by existing schema design.
Core Steps
1. Define Boundary Contracts (fail-fast)
- Type every public route with explicit schemas for params, query, body, and responses.
- Validate at the HTTP layer; schema failures return 400 before reaching service logic.
- Completion criterion: Every public route defines strict schemas and returns 400 on schema failure.
2. Isolate Responsibilities (layered)
- Controller: Parse HTTP requests, delegate to service, return HTTP response codes.
- Service: Domain and business logic, authorization checks, transaction orchestration.
- Repository: Raw SQL/queries, data mapping, direct database pool interactions.
- Wire components using constructor-based dependency injection.
- Completion criterion: Every controller handles transport only (no SQL/DB imports); every service handles domain logic only (no HTTP request/response imports).
3. Manage Connections & Transactions (pooled)
- Configure database connection pools with explicit max connections, idle timeouts, and connection timeouts.
- Wrap multi-operation writes in atomic transactions (
BEGIN/COMMIT/ROLLBACK). - Release checked-out pool clients in
finallyblocks. - Completion criterion: Every multi-statement write runs in a transaction that rolls back on error; every checked-out pool client is released on all execution paths.
4. Standardize Responses & Errors (envelope)
- Use a single top-level error handler mapping typed
AppErrorsubclasses to status codes. - Return one JSON envelope for success (
{ status: "success", data }) and failure ({ status: "error", code, message }); sanitize messages in production. - Completion criterion: Every request-scoped error passes through the global error handler and returns the failure envelope with a sanitized message.
5. Wire Process Lifecycle (drain)
- Bind
SIGTERMandSIGINTto a coordinated shutdown handler. - Stop accepting new HTTP requests, drain in-flight requests within a grace timeout (e.g., 10s), then close DB pools and cache connections.
- Keep the force-exit timer unref'd so it never holds the event loop open.
- Completion criterion: Application exits with code 0 on termination signal after in-flight connections drain and pools close.
Disclosed Reference
Implementation blueprints — schema definitions, DI container, pool configuration, transaction helper, error handler, shutdown handler — in resources/implementation-playbook.md. Load when implementing any step.
04 同仓库更多 Skills
unslop
Use when writing or editing prose a person will read, or when text sounds AI-generated.
show-me
Use when asked to show, diagram, or walk through how code fits together or what a change does, or before explaining a multi-file flow in prose.
pr
Use when writing or updating a pull request description, or before running `gh pr create`.
commit
Use when writing a commit message, or before running `git commit`.
write-specs
Spec a feature's observable behavior. Use when asked for requirements, when a request says what the system should do but not how, or to capture what a built system already guarantees. Not for how to build it (write-plan).
write-skills
Write, fix, or audit a skill's frontmatter, trigger description, and body. Use when a skill is asked for, never fires, or fires at the wrong moment. Not for a hook (write-hooks) or the plugin manifest and catalog.