AGENT SKILL

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 proxy set 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 req for 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

  1. Middleware order documented and covered by an integration test.
  2. Error path test: thrown service error → correct status + envelope, no stack.
  3. Auth test: public, authenticated, and cross-tenant access.
  4. Shutdown test under load.
  5. Load test at peak with event-loop delay measured.

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