0
点赞
收藏
分享

微信扫一扫

优秀的 API 接口都是如何设计的?

优秀的 API 接口设计遵循一套成熟的设计原则和实践,旨在提升可用性、可维护性、可扩展性一致性。下面是优秀 API 接口设计的关键特征:

✅ 一、遵循 RESTful 原则(面向资源)

RESTful 是最常见的 Web API 设计风格:

操作

HTTP 方法

示例路径

含义

获取资源

GET

/users

获取用户列表

获取单个资源

GET

/users/123

获取 ID 为 123 的用户

创建资源

POST

/users

创建一个用户

更新资源

PUT/PATCH

/users/123

更新 ID 为 123 的用户

删除资源

DELETE

/users/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:具体数据,分页返回时建议增加 totallist

✅ 五、良好的错误处理

  • 使用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 在创建资源时需考虑幂等性(如幂等键、重试机制)

✅ 十、扩展性考虑

  • 返回结构尽量稳定、向后兼容
  • 提前预留字段、保留灵活性
  • 支持国际化、多语言返回(如错误信息)
举报

相关推荐

0 条评论