常见的 API 设计风格
在软件开发中，常见的 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) {nameposts(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 | - | 高 | 低 | 事件通知 |
如何选择 API 风格？
- 公开 API → RESTful 或 GraphQL
- 内部高性能通信 → gRPC
- 实时双向通信 → WebSocket
- 企业级集成 → SOAP（仅限遗留系统）
- 事件驱动架构 → Webhook + RESTful
现代系统常组合使用多种风格，例如：
- 用 RESTful 提供基础 CRUD
- 用 GraphQL 处理复杂查询
- 用 gRPC 处理微服务间通信
- 用 Webhook 实现异步通知