后端开发场景实战
Node.js/Java/Go后端项目的AGENTS.md怎么写
承上启下
前端篇写完了，这篇来说说后端项目怎么整。和前端不一样，后端更关注数据处理、业务逻辑、接口设计这些事。不同的后端技术栈，差别还挺大的。我分别说说我用过的几种主流方案。
Node.js/Express 项目
Node.js 后端最常用的是 Express 或者 NestJS。我先说 Express，因为简单嘛，大家都懂。
# AGENTS.md - Node.js REST API 项目
## 项目概述
Express.js RESTful API 服务，提供用户管理、商品订单等功能。
## 技术栈
- Node.js 18+
- Express.js
- TypeScript
- PostgreSQL + Prisma
- Jest + Supertest
- JWT 认证
## 开发环境
### 安装依赖
```bash
npm install
启动开发服务器
npm run dev # 支持热重载
运行测试
npm test # 单元测试
npm run test:integration # 集成测试
代码检查
npm run lint
npm run typecheck
数据库
npm run db:migrate # 数据库迁移
npm run db:seed # 种子数据
npm run db:studio # Prisma Studio
项目结构
src/
├── controllers/ # 控制器层
├── services/ # 业务逻辑层
├── repositories/ # 数据访问层
├── models/ # 数据模型
├── middleware/ # 中间件
├── routes/ # 路由定义
├── utils/ # 工具函数
└── types/ # 类型定义
API 规范
RESTful 设计原则
- 使用标准 HTTP 方法（GET/POST/PUT/DELETE）
- 资源命名使用复数形式（如 /users, /orders）
- 路径参数使用冒号（如 /users/:id）
响应格式
// 成功响应
{
"data": { ... },
"meta": { "page": 1, "total": 100 }
}
// 错误响应
{
"error": {
"code": "VALIDATION_ERROR",
"message": "请求参数验证失败",
"details": [...]
}
}
状态码使用
- 200: 成功
- 201: 创建成功
- 400: 请求参数错误
- 401: 未认证
- 403: 无权限
- 404: 资源不存在
- 500: 服务器错误
代码规范
控制器规范
- 只做请求解析和响应格式化
- 不包含业务逻辑
- 使用 async/await 处理异步
服务层规范
- 包含所有业务逻辑
- 使用事务保证数据一致性
- 错误抛出自定义异常
数据访问层规范
- 只做数据库操作
- 不包含业务逻辑
- 使用 Prisma Transaction
日志规范
- 禁止使用 console.log
- 使用 pino 日志库
- 区分日志级别（info/warn/error）
- 包含请求 ID 方便追踪
测试要求
测试分层
- 控制器层：请求/响应测试
- 服务层：单元测试（mock 依赖）
- 集成测试：使用测试数据库
测试覆盖率
- 目标：80% 以上
- 提交前必须通过所有测试
安全约束
- 禁止硬编码密钥和凭证
- 敏感配置使用环境变量
- 密码必须使用 bcrypt 哈希存储
- 所有接口实现速率限制
- CORS 配置白名单域名
注意事项
- 中间件顺序：先认证，后业务
- 数据库连接使用连接池
- 大数据量使用分页
- 敏感操作记录日志
## NestJS 项目
NestJS 现在很火，它是基于依赖注入的企业级框架，写法和原生 Express 不太一样。
```markdown
# AGENTS.md - NestJS 微服务项目
## 技术栈
- Node.js 18+
- NestJS 10
- TypeScript
- TypeORM / Prisma
- PostgreSQL
- JWT + Passport
- WebSocket (Socket.io)
## 开发命令
```bash
npm install
npm run start:dev # 开发模式
npm run build # 生产构建
npm run test # 单元测试
npm run test:cov # 带覆盖率
npm run lint
项目结构（NestJS 特色）
src/
├── modules/ # 功能模块
│ ├── users/
│ │ ├── dto/ # 数据传输对象
│ │ ├── entities/ # 实体
│ │ ├── users.controller.ts
│ │ ├── users.service.ts
│ │ └── users.module.ts
├── common/ # 公共模块
│ ├── decorators/ # 自定义装饰器
│ ├── filters/ # 异常过滤器
│ ├── interceptors/ # 拦截器
│ └── guards/ # 守卫
├── config/ # 配置模块
└── database/ # 数据库配置
NestJS 特有规范
模块设计
- 每个功能模块自包含
- 使用 @Module() 装饰器
- 共享模块导出公共 Provider
控制器规范
- 使用 @Controller() 装饰器
- 方法使用 @Get/@Post/@Put/@Delete
- 参数使用 @Body/@Param/@Query
服务层规范
- 使用 @Injectable() 装饰器
- 构造函数注入依赖
- 业务逻辑在服务层
管道/过滤器
- 使用 Class Validator 做参数验证
- 全局异常过滤器处理错误
- 转换管道格式化响应
认证授权
- 使用 @nestjs/passport
- JWT Strategy 实现
- Guards 做权限控制
- Roles 装饰器区分角色
## Java Spring Boot 项目
Java 生态里 Spring Boot 是yyds。这个框架和 Node.js 的风格完全不同，讲究的是一个"约定大于配置"。
```markdown
# AGENTS.md - Spring Boot 微服务项目
## 项目概述
基于 Spring Boot 的用户认证微服务，提供 JWT 认证、OAuth2 集成。
## 技术栈
- Java 17
- Spring Boot 3.2
- Spring Security
- Spring Data JPA
- MySQL 8.0
- Gradle
## 构建与运行
```bash
./gradlew build
./gradlew bootRun
./gradlew test
./gradlew bootJar
项目结构
src/
├── main/
│ ├── java/com/example/app/
│ │ ├── controller/ # REST 控制器
│ │ ├── service/ # 业务逻辑
│ │ ├── repository/ # 数据访问
│ │ ├── model/ # 实体类
│ │ ├── dto/ # 数据传输对象
│ │ ├── config/ # 配置类
│ │ └── exception/ # 异常处理
│ └── resources/
│ └── application.yml
└── test/
└── java/ # 测试代码
编码规范
- 使用 Lombok 减少样板代码
- 控制器返回 ResponseEntity
- 所有异常通过 @ExceptionHandler 处理
- 事务使用 @Transactional 声明
- 使用构造器注入（推荐）
测试规范
- 单元测试：JUnit 5 + Mockito
- 集成测试：@SpringBootTest
- Controller 测试：@WebMvcTest
- 测试数据使用 @Sql 加载
部署说明
- 打包为 JAR：./gradlew bootJar
- Docker：docker build -t app:latest .
- 环境变量参考 .env.example
## Go 项目
Go 后端现在也很火，特别是做高性能API服务的时候。我常用的是 Gin 框架。
```markdown
# AGENTS.md - Go REST API 项目
## 技术栈
- Go 1.21
- Gin Web 框架
- GORM ORM
- PostgreSQL
- Wire 依赖注入
## 开发命令
```bash
go mod download
go run cmd/api/main.go
go test ./...
go test -v -run TestXxx
go build -o bin/api cmd/api/main.go
项目结构
cmd/
api/
main.go
internal/
handler/ # HTTP 处理层
service/ # 业务逻辑层
repository/ # 数据访问层
model/ # 数据模型
middleware/ # 中间件
config/ # 配置
pkg/ # 可复用包
编码规范
- 遵循 Go 官方编码规范
- 使用 gofmt 格式化代码
- 错误处理：使用 fmt.Errorf + %w 包装
- 日志使用 zap 日志库
- 配置使用 Viper 框架
测试要求
- 单元测试使用标准库 testing
- 集成测试使用 testify 框架
- Mock 使用 go mock 工具
- 覆盖率目标：70% 以上
注意事项
- 禁止使用 panic 处理业务错误
- 数据库连接使用连接池
- 敏感信息从环境变量读取
- 使用 context 传递请求上下文
## 后端AGENTS.md的特殊门道
后端项目有几个地方和前端不太一样，单独说说。
数据库操作一定要写清楚。后端最核心的就是数据处理，用什么ORM、数据库迁移怎么跑、测试数据怎么准备，这些都要写。要不然AI给你生成的代码可能连数据库连接都没有。
认证授权机制要说明白。JWT怎么用、Session怎么管理、OAuth怎么整，这些如果不写清楚，AI生成的接口很可能是不带认证的裸接口。
错误处理规范要统一。后端错误处理的方式很多，你得告诉AI用什么方式返回错误信息，是用HTTP状态码还是返回特定的错误格式。
事务处理规则要写明白。哪些操作需要事务、事务怎么控制，这些涉及到数据一致性的问题，AI自己是不可能搞清楚的。
## 小结
后端项目的AGENTS.md，前端篇讲的那套依然适用，但需要更多关注数据库、认证、错误处理这些后端特有的东西。不同的技术栈规范也不太一样，Node.js、Java、Go 各有各的玩法，你得根据自己选的技术栈来调整。
下期聊聊测试和代码重构场景，这是很多人容易忽略但其实特别重要的场景。
---
浙公网安备 33010602011771号