express-architect
Architect-level Express guidance — router/middleware layering, error-handling contracts, validation and auth placement, async handler safety, and the deployment model for a stateless Node service. Use when designing or reviewing an Express API.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- express-architect
- license
- MIT
- metadata
- { "crusor-path": "website-architect/frontend-development-architect/react-architect/nodejs-architect/express-architect", "crusor-domain": "website-architect", "crusor-origin": "original", "crusor-sources": "expressjs.com/en/guide; nodejs.org/api/http", "crusor-triggers": "express, expressjs, express router, express middleware, node http, req res next", "crusor-verified-on": "2026-10-30" }
- description
- Architect-level Express guidance — router/middleware layering, error-handling contracts, validation and auth placement, async handler safety, and the deployment model for a stateless Node service. Use when designing or reviewing an Express API.
- compatibility
- Express 4/5; Node 20+
03 SKILL.md 正文
Express Architect
Express gives you a middleware chain and nothing else. Architecture is the order of that chain and what is allowed to know what.
When to use
- A Node HTTP API where you want explicit control and minimal surface.
- Existing Express app that has become a pile of
app.use. - A service small enough that a framework's conventions would be overhead.
When NOT to use
- Structured, DI-heavy, TypeScript-first service (see
nestjs-architect). - Throughput-critical JSON APIs where schema-first speed matters
(
fastify-architect). - Anything needing async-by-default semantics — Express 4 is callback/promise land; misconfigured async handlers crash or hang.
Decision 1 — Chain order (fixed, documented)
request id → logging → body limit → security headers → cors
→ auth (router-scoped) → validation → handler → error handler
- Error handler is last and has 4 args; it is the only place that formats errors.
- Auth is applied per router, not globally, so public routes are explicit.
- Body size limits before any parsing of untrusted input.
Decision 2 — Layering
routes/ express.Router(), path + validation wiring
controllers/ parse req -> call service -> res
services/ use-cases, no req/res
repos/ DB/queue
- Controllers never contain SQL; services never touch
req. - Mount routers by bounded context (
/v1/orders,/v1/auth). - Async errors: wrap handlers (
asyncHandler) so rejections reach the error middleware — an unhandled rejection in Express 4 is a silent hang.
Decision 3 — Contracts
- One error envelope:
{error: {code, message, details?}}for every failure. - Validation at the edge (zod/joi), typed thereafter; never trust
req.body. - 404 handler for unmatched routes; 405 where methods differ.
- Pagination/filtering parameters validated and capped.
Decision 4 — Runtime and deployment
- Stateless processes; sessions in a store, never in memory.
trust proxyset correctly behind a load balancer, or rate limits and IPs lie.- Graceful shutdown: stop accepting, drain, close DB pool.
- Health endpoints separate liveness from readiness.
Failure modes at scale
- Middleware added "temporarily" that mutates
reqfor everyone. - Async handler throwing → request hangs until timeout.
- Global
app.use(auth)with a growing exception list. - Error messages leaking stack traces in production.
- Business logic duplicated across three route files.
Verification receipts
- Middleware order documented and covered by an integration test.
- Error path test: thrown service error → correct status + envelope, no stack.
- Auth test: public, authenticated, and cross-tenant access.
- Shutdown test under load.
- Load test at peak with event-loop delay measured.
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.