RESTful接口设计
什么是RESTful
REST（Representational State Transfer，表现层状态转换）是一种软件架构风格，而RESTful接口是遵循REST原则设计的API。核心思想是以资源为中心，使用HTTP协议的标准方法实现对资源的CRUD操作。
表现层：客户端需要的各种资源（JSON数据、图片、页面等）
状态转换：用户对资源的操作（GET获取、POST新增、PUT更新、DELETE删除）反映到服务器上
HTTP方法 操作 示例
GET 读取资源 GET /api/v1/users → 获取用户列表
POST 创建资源 POST /api/v1/users → 创建新用户
PUT 全量更新 PUT /api/v1/users/1 → 更新用户1的全部信息
PATCH 部分更新 PATCH /api/v1/users/1 → 更新用户1的部分信息
DELETE 删除资源 DELETE /api/v1/users/1 → 删除用户1
text
RESTful接口文档的四要素
1. 资源命名与URL设计
基本原则：
- 使用名词（不用动词） ✅ GET /users ❌ GET /getUsers
- 使用复数形式 ✅ /users ❌ /user
- 层级关系用路径表示 ✅ /users/1/orders
- URL中使用kebab-case ✅ /user-profiles ❌ /userProfiles
- 包含API版本号 ✅ /api/v1/users
text
2. HTTP方法与操作
| HTTP方法 | CRUD操作 | 是否幂等 | 是否安全 |
|---|---|---|---|
| GET | 读取 | 是 | 是 |
| POST | 创建 | 否 | 否 |
| PUT | 全量更新 | 是 | 否 |
| PATCH | 部分更新 | 否 | 否 |
| DELETE | 删除 | 是 | 否 |
3. 请求与响应格式
请求参数类型：
- Path参数：
/users/:id - Query参数：
/users?page=1&size=10 - Body参数：JSON格式的请求体
响应格式（统一结构）：
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"name": "张三"
}
}
json
4. 错误处理
{
"code": 404,
"message": "用户不存在",
"errors": [
{
"field": "id",
"message": "指定ID的用户不存在"
}
]
}
json
HTTP状态码速查
| 状态码范围 | 含义 | 常见码 |
|---|---|---|
| 1xx | 信息性 | 100 Continue |
| 2xx | 成功 | 200 OK、201 Created、204 No Content |
| 3xx | 重定向 | 301 Moved Permanently、302 Found、304 Not Modified |
| 4xx | 客户端错误 | 400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Found |
| 5xx | 服务端错误 | 500 Internal Server Error、502 Bad Gateway、503 Service Unavailable |
最佳实践：自定义状态码应与HTTP状态码保持一致，前端不需要做额外映射。
接口文档工具推荐
| 工具 | 私有部署 | 开源 | 价格 | 扩展性 | 易用性 | 推荐指数 |
|---|---|---|---|---|---|---|
| ShowDoc | 支持 | 是 | 免费 | ★★★★ | ★★★★★ | ★★★★★ |
| Swagger UI | 支持 | 是 | 免费 | ★★★★★ | ★★★★ | ★★★★★ |
| ReDoc | 支持 | 是 | 免费 | ★★★★★ | ★★★★ | ★★★★ |
| Apifox | 支持 | 否 | 免费版 | ★★★★ | ★★★★★ | ★★★★ |
| YApi | 支持 | 是 | 免费 | ★★★★ | ★★★★ | ★★★★ |
| Rap | 支持 | 是 | 免费 | ★★★ | ★★★ | ★★★ |
| Postman | 云端 | 否 | 免费版 | ★★★★★ | ★★★★ | ★★★ |
| Knife4j | 支持 | 是 | 免费 | ★★★★ | ★★★★ | ★★★ |
推荐：
- 小团队首选 ShowDoc（私有化部署简单，持续更新，提供移动端App）
- Java/Spring项目推荐 Swagger UI
- 追求文档美观可选 ReDoc
ShowDoc简介
ShowDoc 是一个非常适合国内团队的接口文档工具：
- 支持私有化部署（Docker方式安装）
- Markdown格式编写
- 提供API文档和数据字典模板
- 免费提供App端
- 持续更新，社区活跃
部署方式：
# Docker方式安装
docker run -d --name showdoc \
-p 4999:80 \
-v /path/to/showdoc_data:/var/www/html \
star7th/showdoc
bash
接口文档自动生成方案
Swagger UI
Swagger UI是事实上的API文档标准，几乎所有主流后端框架都有对应的Swagger集成库：
| 框架 | 集成库 |
|---|---|
| NestJS | @nestjs/swagger |
| Express | swagger-jsdoc + swagger-ui-express |
| Spring Boot | springfox / springdoc-openapi |
NestJS集成示例：
// 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
ReDoc
ReDoc 是Swagger UI的替代方案，文档渲染更加美观，扩展性更强：
npm install redoc
bash
ReDoc支持OpenAPI 3.0规范，可以与Swagger生成的JSON文件配合使用。
更多接口文档工具
除了上述推荐工具外，国内还有不少优秀的接口文档管理平台：
| 工具 | 特点 | 综合评分 |
|---|---|---|
| RAP（淘宝） | 支持版本管理、开源、有文档、支持项目管理和团队管理、完整的成员权限管理方案 | 23分 |
| Eolink | 一站式API生产力工具，结合设计、文档、自动化测试、监控和团队协作，超30万开发者使用 | 17分 |
| EasyAPI | API管理、测试、监控、文档的综合服务平台 | 17分 |
| Apizza | 极客专属的接口协作管理工具 | 16分 |
| EasyDoc（易文档） | 简洁的在线文档工具 | 17分 |
| ApiPost | 快速生成接口文档，支持导出HTML、Markdown、Word | 17分 |
评分维度：私有化部署（5分）、开源（5分）、价格（5分）、扩展性（5分）、易用性（5分），满分25分。
接口文档定义工具
用于API设计和规范的描述工具：
| 工具 | 特点 |
|---|---|
| Swagger | 流行API文档工具，支持自动生成和在线测试 |
| Apiary | 在线文档撰写、测试和管理，支持API Blueprint和OpenAPI规范 |
| RAML | RESTful API建模语言，简洁易用，支持生成文档和代码 |
| Dredd | 基于API Blueprint和OpenAPI规范的API测试工具，验证文档与实现的一致性 |
接口文档生成工具
| 工具 | 特点 |
|---|---|
| Swagger UI | 基于Swagger规范自动生成，可视化界面与交互功能，生态丰富 |
| ReDoc | 开源，支持OpenAPI规范，文档美观清晰，可自定义主题 |
| Slate | 使用Markdown编写，生成静态HTML页面 |
| Aglio | 基于API Blueprint生成静态HTML页面 |
| Widdershins | 支持OpenAPI/Swagger/API Blueprint，生成Markdown格式 |
最佳实践总结
- 接口文档简洁明了，面向开发者而非普通用户
- 命名风格统一（团队约定URL使用camelCase或kebab-case）
- 包含版本号（
/api/v1/），方便后续升级 - 使用合适的HTTP方法和状态码
- 提供详细的错误信息
- 注意接口安全性（鉴权、信道加密等）
↑