优秀的 API 接口设计遵循一套成熟的设计原则和实践,旨在提升可用性、可维护性、可扩展性和一致性。下面是优秀 API 接口设计的关键特征:
✅ 一、遵循 RESTful 原则(面向资源)
RESTful 是最常见的 Web API 设计风格:
操作 | HTTP 方法 | 示例路径 | 含义 |
获取资源 |
|
| 获取用户列表 |
获取单个资源 |
|
| 获取 ID 为 123 的用户 |
创建资源 |
|
| 创建一个用户 |
更新资源 |
|
| 更新 ID 为 123 的用户 |
删除资源 |
|
| 删除 ID 为 123 的用户 |
✅ 二、清晰统一的 URL 命名规则
- 使用名词表示资源(如
/products
,/orders
) - URL 小写,使用短横线分隔:如
/course-types
而非/courseTypes
- 不要在路径中加入动词(如
/getUser
不推荐)
✅ 三、参数传递方式合理
- 路径参数(Path Param):标识资源,如
/users/123
- 查询参数(Query Param):用于过滤、分页,如
/users?page=2&size=10
- 请求体(Request Body):用于 POST/PUT 时提交结构化数据(JSON)
✅ 四、响应结构规范统一
推荐响应结构统一,例如:
{
"code": 0,
"message": "success",
"data": {
"id": 123,
"name": "张三"
}
}
约定:
code
:状态码(0 表示成功,非 0 表示错误)message
:提示信息data
:具体数据,分页返回时建议增加total
、list
✅ 五、良好的错误处理
- 使用HTTP 状态码表达请求结果(如 200、400、401、404、500)
- 提供详细且友好的错误信息
例如:
{
"code": 10001,
"message": "用户不存在",
"details": "User ID 9999 not found"
}
✅ 六、版本控制(推荐)
- 在路径中加入版本号:
/api/v1/users
- 或者在请求头中控制版本(高级用法)
✅ 七、接口文档完善
使用 Swagger/OpenAPI 规范文档,描述:
- 请求方式
- 参数说明
- 响应结构
- 示例数据
✅ 八、安全性设计
- 使用 HTTPS
- 授权认证机制(如 JWT、OAuth2)
- 防止接口滥用(限流、IP 限制、权限控制)
✅ 九、幂等性设计(重要)
GET/DELETE
天然幂等POST
在创建资源时需考虑幂等性(如幂等键、重试机制)
✅ 十、扩展性考虑
- 返回结构尽量稳定、向后兼容
- 提前预留字段、保留灵活性
- 支持国际化、多语言返回(如错误信息)