RESTful API 请求和响应格式-洪萨配资

RESTful API 的请求和响应格式详解

在 RESTful API 中，请求和响应的格式设计直接影响 API 的易用性、一致性和可维护性。优秀的格式规范能让前后端开发者快速理解接口行为，减少沟通成本。

1. 总体原则

内容类型统一：几乎全部使用JSON（application/json）作为请求和响应的数据格式。
结构一致：成功响应和错误响应都采用统一的包裹结构，便于客户端统一处理。
清晰、可读：字段命名规范，时间格式标准，返回必要元信息。
避免裸数据：不要直接返回数组或单个对象，而是用包裹对象提供上下文。

2. 请求格式（Request）

2.1 常见 Content-Type

HTTP 方法	典型 Content-Type	说明
POST / PUT / PATCH	`application/json`	最常用，发送 JSON 数据
文件上传	`multipart/form-data`	上传头像、附件等
表单提交	`application/x-www-form-urlencoded`	传统表单（较少用）

2.2 请求体（Body）示例

创建用户（POST /users）

{"name":"张三","email":"zhang@example.com","password":"secret123","age":28,"roles":["user","admin"]}

部分更新用户（PATCH /users/123）

{"name":"张三丰","age":30}

（只包含需要修改的字段）

查询参数（Query Parameters）用于 GET 请求过滤

GET /articles?status=published&tag=rest&sort=-created_at&page=2&limit=20

2.3 请求头（Headers）常用字段

Header	示例值	说明
Content-Type	application/json	请求体格式
Accept	application/json	期望响应格式
Authorization	Bearer eyJhbGciOiJIUzI1NiIs…	JWT 或其他认证令牌
X-API-Key	your-api-key	API Key 认证

3. 响应格式（Response）

3.1 成功响应统一结构（推荐）

方案一：通用包裹（最常用）

{"data":{// 主要数据"id":123,"name":"张三","email":"zhang@example.com","created_at":"2025-12-25T10:00:00Z"},"meta":{// 元信息（可选）"timestamp":"2025-12-25T10:00:01Z","request_id":"abc123-def456"}}

方案二：集合响应（列表 + 分页）

{"data":[{"id":1,"title":"REST 教程"},{"id":2,"title":"API 设计"}],"meta":{"pagination":{"total":156,"page":2,"limit":20,"total_pages":8},"timestamp":"2025-12-25T10:00:01Z"}}

方案三：无数据内容（如 DELETE 成功）

返回204 No Content（无响应体，最推荐）
或返回 200 + 简单结构：

{"data":null,"meta":{"message":"用户删除成功"}}

3.2 错误响应统一结构（非常重要！）

推荐错误格式（Problem Details - RFC 7807 标准）

{"error":{"code":"VALIDATION_ERROR",// 业务错误码（字符串）"message":"请求参数验证失败",// 给开发者的友好提示"details":[// 具体字段错误（可选）{"field":"email","issue":"already_exists","message":"该邮箱已被注册"},{"field":"age","issue":"invalid_range","message":"年龄必须在 18-100 之间"}]}}

响应头：

Content-Type: application/json
HTTP 状态码：400 Bad Request、422 Unprocessable Entity 等

常见错误状态码与 code 对应

HTTP 状态码	推荐 error.code	场景
400	BAD_REQUEST	参数格式错误
401	UNAUTHORIZED	未登录
403	FORBIDDEN	无权限
404	NOT_FOUND	资源不存在
409	CONFLICT	资源冲突（如用户名重复）
422	VALIDATION_ERROR	业务校验失败（最常用）
429	TOO_MANY_REQUESTS	限流
500	INTERNAL_SERVER_ERROR	服务器异常

3.3 字段命名与数据格式规范

项目	推荐规范	示例
字段命名	snake_case（下划线）或 camelCase	`user_id`或`userId`（统一即可）
时间格式	ISO 8601（UTC）	“2025-12-25T10:00:00Z”
布尔值	true / false	“is_active”: true
空值	null（避免空字符串）	“description”: null
枚举	字符串常量	“status”: “published”

4. 完整示例对比

请求

POST /api/v1/users HTTP/1.1 Content-Type: application/json Authorization: Bearer xyz123... { "name": "李四", "email": "li@example.com", "password": "123456" }

成功响应（201 Created）

HTTP/1.1 201 Created Content-Type: application/json Location: /api/v1/users/456 { "data": { "id": 456, "name": "李四", "email": "li@example.com", "created_at": "2025-12-25T10:00:00Z" }, "meta": { "timestamp": "2025-12-25T10:00:01Z" } }

错误响应（422）

HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "error": { "code": "VALIDATION_ERROR", "message": "参数验证失败", "details": [ { "field": "email", "issue": "invalid_format", "message": "邮箱格式不正确" } ] } }