常见的 API 设计风格

原创已于 2025-04-15 23:08:57 修改 · 956 阅读

20 ·

CC 4.0 BY-SA版权

文章标签：

#restful

于 2025-04-15 23:08:20 首次发布

API风格专栏收录该内容

1 篇文章

订阅专栏

在软件开发中，常见的 API 设计风格主要有以下几种，每种风格适用于不同的场景和需求：

1. RESTful API (主流)

特点：

基于 HTTP 协议，使用标准方法（GET/POST/PUT/DELETE）
资源导向（URI 表示资源，如 /users）
无状态、可缓存、统一接口
通常返回 JSON/XML

适用场景：

公开的 Web 服务（如 GitHub API）
前后端分离架构
需要简单、易理解的接口

示例：

GET /api/users/123

2. RPC（Remote Procedure Call）

特点：

强调"动作"而非资源（如 /deleteUser）
通常使用 POST 方法（所有操作通过 POST 发送）
协议无关（可通过 HTTP、TCP 等实现）

变种：

JSON-RPC：轻量级，基于 JSON
gRPC：Google 开发的高性能二进制协议（基于 HTTP/2）
XML-RPC：传统 SOAP 的前身

适用场景：

内部微服务通信（如 gRPC）
需要高性能的场景
操作导向的系统（如银行转账）

示例：

POST /rpc
{
  "method": "deleteUser",
  "params": {"id": 123},
  "id": 1
}

3. GraphQL (新兴)

特点：

客户端自定义查询字段
单一端点（通常 /graphql）
强类型系统
减少过度获取（Over-fetching）数据

适用场景：

复杂数据关系的系统（如社交网络）
需要灵活查询的客户端（如移动端）
多数据源聚合

示例：

query {
  user(id: 123) {
    name
    posts(limit: 5) {
      title
    }
  }
}

4. SOAP (传统)

特点：

基于 XML 的协议
严格的 WSDL 规范
内置安全/事务支持
通常通过 HTTP POST 传输

适用场景：

企业级系统（如银行、政府）
需要 ACID 事务的场景
遗留系统集成

示例：

POST /soap
<Envelope>
  <Body>
    <GetUser>
      <Id>123</Id>
    </GetUser>
  </Body>
</Envelope>

5. WebSocket API

特点：

全双工实时通信
保持长连接
适合高频数据推送

适用场景：

实时聊天应用
股票行情推送
在线游戏

示例：

// 客户端代码
socket.send(JSON.stringify({action: "join", room: "news"}));

6. Webhook

特点：

反向 API（服务端主动调用客户端）
事件驱动模型
通常用于异步通知

适用场景：

支付结果回调
CI/CD 流水线触发
第三方服务集成（如 Slack 机器人）

示例：

POST /callback
Content-Type: application/json
{
  "event": "payment_success",
  "order_id": "12345"
}

风格对比表

风格	协议	数据格式	性能	灵活性	学习成本	典型应用
RESTful	HTTP	JSON/XML	中	中	低	公开 Web API
RPC/gRPC	任意	二进制	高	低	中	微服务内部通信
GraphQL	HTTP	JSON	可变	高	高	复杂数据查询
SOAP	HTTP/SMTP	XML	低	低	高	企业级系统
WebSocket	WS/WSS	任意	高	中	中	实时应用
Webhook	HTTP	JSON/XML	-	高	低	事件通知