RESTful API设计原则
REST（Representational State Transfer）是一种软件架构风格，不是标准或协议。RESTful API的设计核心是用HTTP协议的语义来表达操作意图。
核心设计原则
- 资源导向：URL表示资源（名词），不表示操作（动词）
- HTTP方法语义化：用HTTP方法表达操作类型
- 无状态：每个请求包含所有必要信息，不依赖服务端状态
- 统一接口：遵循一致的URL和响应格式规范
HTTP方法与CRUD对应
| HTTP方法 | 操作 | 示例URL | 说明 |
|---|---|---|---|
| GET | 查询 | GET /api/users | 获取用户列表 |
| GET | 查询单个 | GET /api/users/:id | 获取指定用户 |
| POST | 创建 | POST /api/users | 创建新用户 |
| PUT | 全量更新 | PUT /api/users/:id | 更新用户全部信息 |
| PATCH | 部分更新 | PATCH /api/users/:id | 更新用户部分字段 |
| DELETE | 删除 | DELETE /api/users/:id | 删除指定用户 |
URL设计规范
# 好的设计
GET /api/v1/courses # 课程列表
GET /api/v1/courses/123 # 课程详情
POST /api/v1/courses # 创建课程
GET /api/v1/courses/123/reviews # 课程的评价列表
# 不好的设计
POST /api/getCourseList # 用动词
POST /api/deleteCourse # 用POST做删除
GET /api/courseList # 无版本号
text
响应格式规范
{
"code": 200,
"message": "success",
"data": {
"list": [],
"total": 100,
"page": 1,
"pageSize": 20
}
}
json
HTTP状态码使用
| 状态码 | 含义 | 使用场景 |
|---|---|---|
| 200 | 成功 | GET、PUT、PATCH请求成功 |
| 201 | 已创建 | POST请求成功创建资源 |
| 204 | 无内容 | DELETE请求成功 |
| 400 | 请求错误 | 参数验证失败 |
| 401 | 未认证 | 未登录或Token过期 |
| 403 | 禁止访问 | 权限不足 |
| 404 | 未找到 | 资源不存在 |
| 500 | 服务器错误 | 服务端异常 |
接口文档工具
Swagger/OpenAPI
OpenAPI（原Swagger）是RESTful API文档的行业标准。通过YAML/JSON格式的描述文件，自动生成交互式API文档。
在NestJS中集成Swagger非常简单：
// main.ts
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger'
const config = new DocumentBuilder()
.setTitle('知识付费平台API')
.setDescription('平台接口文档')
.setVersion('1.0')
.addBearerAuth()
.build()
const document = SwaggerModule.createDocument(app, config)
SwaggerModule.setup('api-docs', app, document)
typescript
通过装饰器为接口添加文档描述：
@ApiOperation({ summary: '获取课程列表' })
@ApiResponse({ status: 200, description: '返回课程列表' })
@Query('page') page: number
typescript
Apifox
Apifox是国内的API管理工具，集接口设计、调试、Mock、文档于一体。对于中小团队来说，Apifox比单独使用Swagger更高效——可以在一个工具中完成从设计到测试的全流程。
YApi
YApi是去哪儿开源的API管理平台，支持接口管理、Mock服务、自动化测试。适合部署在内网环境使用。
接口文档自动生成
代码即文档
最佳实践是"代码即文档"——通过代码中的注解/装饰器自动生成接口文档，避免文档和代码不同步的问题。
以NestJS + Swagger为例，接口的参数定义、响应格式、描述信息都写在代码中，Swagger自动读取这些信息生成可交互的文档页面。开发者只需要维护代码，文档自动保持同步。
自动生成的工作流
编写API装饰器 → 启动应用 → 访问 /api-docs → 自动生成文档
↓
代码变更 → 文档自动更新 → 无需手动维护
text
这种方式的优点是文档始终和代码保持一致，不会出现"文档过时"的问题。缺点是需要在代码中写装饰器，增加了代码量。但相比手动维护文档的代价，这点额外代码是完全值得的。
↑