基于 AG Kit app-builder 技能的 Express.js REST API 模板实践指南（TypeScript + Prisma + Zod + JWT）

基于 AG Kit app-builder 技能的 Express.js REST API 模板实践指南（TypeScript + Prisma + Zod + JWT）

【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit

本文以 AG Kit 仓库中 app-builder 技能的 express-api 模板 为核心，系统讲解如何从零搭建一个生产可用的 Express.js REST API：包括技术选型、目录分层、中间件装配顺序、统一响应格式、完整搭建步骤与工程化最佳实践。读完本文，你将掌握一套可复制的 Express 5 + TypeScript + Prisma 后端脚手架方案，并理解它如何在 AG Kit 的 Agent 工作流中被自动选用和执行。

一、模板定位：app-builder 技能体系中的 Express API 分支

AG Kit 仓库通过.agents/目录定义项目的 Agent 行为，其中 .agents/skills/app-builder/SKILL.md 是整个应用构建流程的编排器（App Builder），负责"根据自然语言请求判断项目类型、选择技术栈、协调多个专用 Agent"。

该技能内置 13 套项目模板，express-api是其中之一，专用于REST API类项目。在 project-detection.md 的关键词矩阵中，命中api、backend、service、rest等关键词的请求会被归类为 "API Service"，并映射到express-api模板；同一矩阵还给出了冲突消解规则：具体平台（mobile/desktop/cli/extension）优先于业务领域，语法主语（head noun）优先于修饰词，仍无法判定时再向用户提问确认。

从 skills.json 的注册信息可以确认，app-builder是 AG Kit 已注册的正式技能之一（其描述为 "Main application building orchestrator..."），而 templates/SKILL.md 则明确了"选择性阅读"规则：只读取与用户项目类型匹配的那一个模板，避免无关上下文干扰。因此，express-api/TEMPLATE.md是构建 REST API 项目时的唯一技术依据文件。

二、技术栈总览：2026 年稳定版的组合拳

模板顶部声明了一个版本基线："Versions reflect the latest stable line verified 2026-05. Pin to the current stable when scaffolding."（版本反映的是 2026-05 验证过的最新稳定线，脚手架时应锁定当前稳定版）。完整技术栈如下：

组件	技术选型
运行时	Node.js 24（Krypton LTS）
框架	Express 5（稳定版，npm 默认版本）
语言	TypeScript
数据库	PostgreSQL + Prisma
校验	Zod
认证	JWT + bcrypt

各组件在架构中的职责：

• Node.js 24 (Krypton LTS)：长期支持版运行时，与 tech-stack.md 中 Web 应用的默认运行时一致，是 AG Kit 2026 年技术基线的统一底座；
• Express 5：模板明确标注"stable, default on npm"，即 5.x 已是 npm 上的默认版本。Express 5 的关键改进是原生转发 rejected Promise 到错误处理器（见下文最佳实践），这让异步路由错误处理不再依赖手写try/catch包装；
• TypeScript：全程类型化开发，配合 Prisma 提供端到端类型安全；
• PostgreSQL + Prisma：数据库选型与 tech-stack.md 的primary: PostgreSQL, orm: Prisma完全一致；Prisma 负责 schema 定义、迁移（migration）与类型安全的数据库访问；
• Zod：声明式 schema 校验库，在路由边界（route boundary）统一校验所有入参，校验失败后把错误信息结构化传递给错误处理器；
• JWT + bcrypt：认证组合——bcrypt 负责密码哈希存储，JWT 负责无状态令牌签发与验证。

三、目录结构：可测试性的分层骨架

模板给出的目录结构是 REST API 项目的分层骨架：

project-name/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── app.ts # Express app + middleware wiring (no listen) │ ├── server.ts # Bootstrap: listen() — split for testability │ ├── config/ # Environment │ ├── routes/ # Route definitions only │ ├── controllers/ # HTTP layer (req/res, calls services) │ ├── services/ # Business logic │ ├── middlewares/ │ │ ├── auth.ts # JWT verify │ │ ├── error.ts # Error handler │ │ └── validate.ts # Zod validation │ ├── schemas/ # Zod schemas │ └── utils/ ├── tests/ └── package.json

各目录的职责与设计意图：

• app.ts与server.ts分离：这是模板最重要的结构性决策。app.ts只负责创建 Express 应用并装配中间件（不调用listen()），server.ts负责启动引导（调用listen()）。这种拆分让测试可以直接import app而无需真正监听端口（配合 supertest 等工具即可做 HTTP 级集成测试），这是"为可测试性而拆分"的典型做法；
• config/：集中管理环境变量读取与配置对象，遵循"环境驱动配置"（environment-based config）原则，避免配置散落各处；
• routes/：只做路由定义（URL → controller 的映射），不写业务逻辑；
• controllers/：HTTP 层，负责解析req/res、调用 services 并组织响应；
• services/：业务逻辑层，与 HTTP 细节解耦，可独立单元测试；
• middlewares/：按职责拆分的中间件模块——auth.ts（JWT 校验）、error.ts（统一错误处理器）、validate.ts（Zod 校验）；
• schemas/：集中存放 Zod schema，供validate.ts中间件消费；
• tests/：测试目录，与应用代码隔离。

这套"routes → controllers → services"的分层与 AG Kit scaffolding.md 中强调的"Thin routes（路由薄层化）"原则一脉相承：路由层只做分发，逻辑下沉到服务层，保证每一层职责单一、可独立验证。

四、中间件栈：装配顺序即安全与错误处理的保障

模板用表格明确规定了中间件的注册顺序：

顺序	中间件
1	helmet（安全头）
2	cors（跨域）
3	compression（压缩）
4	body parsing（请求体解析）
5	morgan（日志）
6	routes（路由）
7	error handler（最后注册，4 参数签名）

这个顺序背后的工程考量：

• helmet 最先：尽早为所有响应注入安全相关的 HTTP 头（如 CSP、X-Content-Type-Options 等），确保后续任何中间件抛出的响应都已带上安全头；
• cors：在业务路由之前处理跨域预检（preflight）请求；
• compression：对响应体做 gzip 压缩，应放在 body parsing 之前、路由之前，以便压缩逻辑覆盖所有后续中间件产生的响应；
• body parsing：解析 JSON/urlencoded 请求体，为后续路由提供req.body；
• morgan：请求日志，放在路由之前以记录所有业务请求（包括最终 4xx/5xx 状态）；
• routes：核心业务路由；
• error handler 必须最后注册且使用 4 参数签名：Express 通过中间件函数的参数个数识别错误处理器（(err, req, res, next)）。它必须位于所有中间件之后，才能捕获链路上任何环节抛出的错误，并统一转换为标准错误响应。

模板特别注明：Express 5 会自动转发被拒绝的 Promise（auto-forwards rejected promises），无需手动 catch 包装。这意味着在 Express 5 中，异步路由处理器直接throw或返回 rejected Promise 即可被错误处理器捕获，asyncHandler这类包装函数已无必要。

五、API 响应格式：前后端契约的单一规范

模板定义了两类统一的响应结构，作为所有接口的对外契约：

类型	结构
成功	{ success: true, data: {...} }
错误	{ error: "message", details: [...] }

• 成功响应：顶层success: true作为机器可读的成功标志，业务数据统一挂在data字段下，前端可以按固定结构解包，无需为每个接口定制解析逻辑；
• 错误响应：error字段给出人类可读的错误信息，details数组承载结构化错误细节（典型来源是 Zod 校验错误，可逐条列出字段名与错误原因），便于前端定位具体问题字段。

这套规范与中央错误处理器配合：业务代码只需throw一个带状态码与消息的错误，错误处理器统一将其序列化为{ error: "message", details: [...] }，保证所有错误路径输出格式一致，避免散落各处的res.status().json()破坏契约统一性。

六、搭建步骤：从空目录到可运行的完整命令序列

模板给出 7 步搭建流程，下面逐一展开为可直接执行的命令与说明：

1. 创建项目目录

mkdir project-name && cd project-name

2. 初始化 npm

npm init -y

3. 安装运行时依赖

npm install express @prisma/client zod bcrypt jsonwebtoken

依赖	用途
express	Web 框架（5.x）
@prisma/client	Prisma 生成的类型安全客户端
zod	入参声明式校验
bcrypt	密码哈希
jsonwebtoken	JWT 签发与验证

4. 安装开发依赖

npm install -D prisma typescript @types/node @types/express @types/bcrypt @types/jsonwebtoken

prisma作为 CLI 放在 devDependencies，typescript与各库的类型声明同理——运行时不需要它们，但构建与开发必需。

5. 初始化 Prisma

npx prisma init

该命令生成prisma/schema.prisma与.env，随后在schema.prisma中定义数据模型（对应目录结构中的prisma/schema.prisma）。

6. 推送数据库结构

npm run db:push

db:push通常定义为prisma db push，将 schema 直接同步到 PostgreSQL（适合开发初期快速迭代；生产环境建议改用prisma migrate dev生成迁移记录）。

7. 启动开发服务器

npm run dev

dev脚本通常为tsx watch src/server.ts或ts-node-dev之类支持热重载的 TypeScript 运行方式，入口指向src/server.ts（调用listen()的引导文件）。

七、最佳实践：模板沉淀的六条工程准则

模板在末尾列出了六条最佳实践，这是整个模板的精华所在，逐条展开：

1. 拆分app.ts（装配）与server.ts（监听）：让应用可以在测试中被干净地导入（import app from './app'），无需启动真实端口，这是"为可测试性而设计"的最直接体现；
2. 分层架构（routes → controllers → services）：每一层职责单一——路由只做分发、控制器处理 HTTP 细节、服务承载业务逻辑，任意一层都可独立演进与测试；
3. 在路由边界用 Zod 校验所有输入：所有外部输入在进入业务逻辑之前统一经过validate.ts中间件校验，保证服务层只面对已确认合法的数据；
4. 中央错误处理器最后注册：配合 Express 5 自动转发 rejected Promise 的机制，异步错误无需手动包装即可汇聚到统一错误出口，错误响应格式因此全局一致；
5. 环境驱动配置：所有环境相关配置集中在src/config/，通过环境变量注入（DATABASE_URL、JWT_SECRET 等），保证开发/测试/生产环境可切换；
6. 用 Prisma 实现类型安全的数据库访问：由 schema 直接生成客户端类型，查询结果与写入参数在编译期即可校验，从根上减少运行时数据库错误。

八、在 AG Kit 工作流中的落地方式

express-api模板不是孤立的文档，它在 AG Kit 的 Agent 编排体系中拥有明确的使用路径。结合 agent-coordination.md 的流水线可以看到完整链路：

1. Socratic Gate（Phase 0）：编排器先通过提问澄清需求；
2. Project Planner（Phase 1）：生成{task-slug}.md计划文件（强制检查点）；
3. Database Architect（Phase 2）：先设计prisma/schema.prismaschema 与迁移；
4. Backend Specialist（Phase 3）：按本模板的目录结构创建 API 路由、控制器与服务；
5. Security Auditor / Test Engineer（Phase 5）：并行执行漏洞检查与单元测试；
6. DevOps Engineer（Phase 6）：环境配置与预览部署。

值得注意的是，agent-coordination.md 特别指出：DESIGN.md源真值文件仅对含 UI 的项目强制要求，"Skip only for headless APIs or CLI tools"——即 Express API 这类无头服务可跳过设计令牌环节，直接进入数据库与后端开发。这与本模板"无 UI、纯 API"的定位互相印证。

同时，AGENT_FLOW.md 描述了 AG Kit 的 Skill 加载协议：Antigravity 运行时发现.agents/下的 skills 后，按元数据（name/description/when_to_use）加载匹配的技能，express-api模板正是在"创建 REST API 项目"这一场景下被选择性读取并执行的。

结语

express-api模板为 REST API 项目提供了从技术选型、目录分层、中间件装配到统一响应格式、搭建命令、工程最佳实践的一站式方案。它的核心方法论——app/server 分离保障可测试性、分层架构保障可维护性、边界校验与集中错误处理保障健壮性——不仅适用于 AG Kit 的 Agent 自动搭建场景，也完全可以直接作为人工开发 Express 5 后端项目的手册。仓库中其余 12 套模板（Next.js、FastAPI、CLI 等）与 app-builder/SKILL.md 的模板索引可为你提供更多项目类型的脚手架参考。

【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit