用途:为 Node.js 后端开发提供分层架构、TypeScript、校验、错误处理、安全与部署方面的实践模式,适合在构建 REST API 等后端服务时参考。
主要能力:
- 框架选型:按场景推荐 Hono(边缘/无服务器)、Fastify(性能 API)、NestJS(企业团队)、Express(遗留生态),并提示先确认部署目标、冷启动需求与团队经验。
- 分层架构:src/ 下分 routes、middleware、services、repositories、config、types;依赖只能向内(routes -> services -> repositories),路由不含业务逻辑,服务不导入 Request/Response,仓储不抛 HTTP 错误。脚本/原型可用单文件。
- TypeScript:用 import type、interface、unknown 替代 any,z.infer 作单一来源,减少 as 断言,导出函数加显式返回类型;未类型化包用 declare module 声明。
- 校验:Zod 或 TypeBox,仅在边界校验(请求入口、写库前、启动时环境变量),用 .extend()/.pick()/.omit()/.partial()/.merge() 复用 schema。
- 错误处理:AppError 层级(ValidationError 等)与集中处理中间件,asyncHandler 包装异步;给出 400/401/403/404/409/422/429/500 语义。
- API 设计:契约优先,先定义 schema 再写逻辑,生成 OpenAPI 文档;统一错误信封 { error: { code, message, details? } };复数资源名、最多两级嵌套、/api/v1/ 版本、分页查询参数、201 返回 Location、204 无正文。
- 异步与生产:async/await 与 Promise.all/allSettled/race 选择;避免同步方法;用 worker threads、流式处理。启动时校验环境变量失败即崩;提供 /health 与 /ready;Redis 缓存;降载;Fastify 响应 schema;opossum 熔断。
使用方式:先经 search_docs 核对当前框架文档再写代码;完成后运行 tsc --noEmit 与 npm test,确保零错误零警告且无 TypeScript 绕过。
限制:资料未提供具体版本兼容、性能基准来源与完整配置示例;具体收费、平台与效果暂未提供。