API设计原则
核心原则
- • 一致性：统一的命名和结构规范
- • 可预测性：开发者能够预期API行为
- • 简洁性：避免不必要的复杂性
- • 可扩展性：支持未来功能扩展
- • 向后兼容：保护现有集成
RESTful设计风格
遵循REST架构风格，使API更加直观和标准化：
- • 资源导向的URL设计
- • 正确使用HTTP方法
- • 无状态通信
- • 分层系统架构
命名规范
URL路径规范
推荐做法
GET /api/v1/users GET /api/v1/users/123 POST /api/v1/users PUT /api/v1/users/123 DELETE /api/v1/users/123 GET /api/v1/users/123/orders GET /api/v1/orders?user_id=123
避免的做法
GET /api/v1/getUsers POST /api/v1/createUser GET /api/v1/user_list GET /api/v1/Users/123/Orders DELETE /api/v1/removeUser/123 GET /getUserData?id=123
命名规则说明
- • 使用复数名词表示资源集合：
/users、/orders - • 使用小写字母和连字符：
/user-profiles - • 避免动词，让HTTP方法表达操作
- • 嵌套资源应该反映逻辑关系
- • 使用查询参数进行过滤和排序
JSON字段命名
推荐：snake_case
{
"user_id": 123,
"first_name": "张三",
"last_name": "李",
"email_address": "user@example.com",
"created_at": "2024-01-01T00:00:00Z",
"is_active": true,
"profile_image_url": "https://..."
}也可以：camelCase
{
"userId": 123,
"firstName": "张三",
"lastName": "李",
"emailAddress": "user@example.com",
"createdAt": "2024-01-01T00:00:00Z",
"isActive": true,
"profileImageUrl": "https://..."
}HTTP方法使用
GET
获取资源
特性：安全、幂等、可缓存
GET /api/v1/users - 获取用户列表GET /api/v1/users/123 - 获取特定用户GET /api/v1/users?page=2&limit=20 - 分页获取POST
创建资源
特性：非安全、非幂等、不可缓存
POST /api/v1/users - 创建新用户POST /api/v1/users/123/orders - 为用户创建订单POST /api/v1/auth/login - 用户登录PUT
完整更新资源
特性：非安全、幂等、不可缓存
PUT /api/v1/users/123 - 完整更新用户信息PUT /api/v1/users/123/password - 更新密码PATCH
部分更新资源
特性：非安全、非幂等、不可缓存
PATCH /api/v1/users/123 - 部分更新用户信息PATCH /api/v1/users/123/status - 更新用户状态DELETE
删除资源
特性：非安全、幂等、不可缓存
DELETE /api/v1/users/123 - 删除用户DELETE /api/v1/users/123/sessions - 删除用户会话状态码规范
2xx 成功
200
OK
GET、PUT、PATCH请求成功
201
Created
POST请求成功创建资源
204
No Content
DELETE请求成功，无返回内容
4xx 客户端错误
400
Bad Request
请求参数错误或格式不正确
401
Unauthorized
未认证或认证失败
403
Forbidden
已认证但无权限访问
404
Not Found
资源不存在
422
Unprocessable Entity
请求格式正确但数据验证失败
5xx 服务器错误
500
Internal Server Error
服务器内部错误
502
Bad Gateway
网关错误
503
Service Unavailable
服务暂时不可用
错误处理
统一错误响应格式
{
"error": {
"code": "VALIDATION_FAILED",
"message": "请求数据验证失败",
"details": [
{
"field": "email",
"message": "邮箱格式不正确"
},
{
"field": "password",
"message": "密码长度至少8位"
}
],
"timestamp": "2024-01-01T12:00:00Z",
"request_id": "req_123456"
}
}错误响应字段说明
- •
code: 机器可读的错误代码 - •
message: 人类可读的错误描述 - •
details: 详细错误信息（可选） - •
timestamp: 错误发生时间 - •
request_id: 请求ID，便于日志追踪
常见错误类型
- •
INVALID_REQUEST- 请求格式错误 - •
VALIDATION_FAILED- 数据验证失败 - •
AUTHENTICATION_REQUIRED- 需要认证 - •
PERMISSION_DENIED- 权限不足 - •
RESOURCE_NOT_FOUND- 资源不存在 - •
RATE_LIMIT_EXCEEDED- 超出限流
错误处理最佳实践
- • 提供清晰的错误描述
- • 包含解决问题的建议
- • 使用一致的错误格式
- • 避免暴露敏感信息
- • 提供请求ID便于追踪
- • 适当的HTTP状态码