04分类类型

API 的分类方式多样，按**架构风格、协议规范**可分为多种类型，其中**RESTful API、GraphQL、SOAP**是最具代表性的三种，它们在设计理念、适用场景和技术特性上差异显著。

## 一、RESTful API

RESTful （Representational State Transfer）API 是基于**REST 架构风格**设计的 API，是目前 Web 领域最主流、应用最广泛的 API 类型。其核心是 “以资源为中心”，通过 HTTP 协议实现客户端与服务器的无状态交互。

https://restfulapi.net/

### 1.1 特点

**资源导向**
将数据或服务抽象为 “资源”（如用户、订单、商品），每个资源通过唯一 URI（统一资源标识符）标识，例如：/users/123（表示 ID 为 123 的用户）、/orders（表示所有订单）。

**利用 HTTP 语义**
严格遵循 HTTP 方法的语义（“动词 + 资源” 模式）：

- GET：获取资源（只读，无副作用）；
- POST：创建新资源；
- PUT：全量更新资源（替换整个资源）；
- PATCH：部分更新资源；
- DELETE：删除资源。

**无状态性**
服务器不存储客户端的状态信息，每次请求必须包含所有必要数据（如身份验证令牌），简化服务器设计，提高可扩展性。

**数据格式灵活**
支持 JSON（主流）、XML、HTML 等，其中 JSON 因轻量、易解析成为首选（例如：GET /users/123返回{"id":123, "name":"Alice"}）。

**依赖 HTTP 状态码**
用 HTTP 状态码表示请求结果（如200 OK、201 Created、404 Not Found、500 Internal Error），语义清晰。

### 1.2 优势

- **简单易懂**：基于 HTTP 协议，开发人员无需学习新协议，易于上手；
- **轻量高效**：数据格式简洁（如 JSON），传输成本低；
- **可扩展性强**：无状态设计支持水平扩展，适合分布式系统；
- **兼容性好**：支持各种客户端（浏览器、移动 APP、第三方服务）。

### 1.3 劣势

- **过度获取 / 不足**：客户端需的数据可能多于或少于接口返回的内容（例如获取用户信息时，接口返回了不需要的地址字段）；
- **多资源请求繁琐**：获取关联资源（如 “用户 + 订单”）需多次调用接口。

### 1.4 场景

- 公开 API（如社交媒体开放平台、支付接口）；
- 移动 APP 后端接口（需轻量化、跨平台）；
- 简单数据交互场景（如查询商品、提交表单）。

## 二、GraphQL

GraphQL 是 Facebook 在 2015 年开源的**数据查询语言和运行时**，旨在解决 RESTful API 的 “过度获取” 和 “多请求” 问题，核心是 “客户端按需获取数据”。

https://graphql.org/

### 2.1 特点

**按需查询**
客户端通过 “查询语句” 明确指定需要的字段，服务器仅返回请求的内容。例如：

```sql
# 客户端查询：只需要用户的id和name，不需要其他字段
query {
  user(id: "123") {
    id
    name
  }
}
```

服务器返回：{"data": {"user": {"id": "123", "name": "Alice"}}}

**单一端点**
通常只有一个 HTTP 端点（如/graphql），所有操作（查询、创建、更新、删除）都通过该端点完成，无需设计多个 URI。

**强类型 Schema**
必须定义 Schema（类型系统），明确资源的结构和可执行的操作（查询Query、修改Mutation、订阅Subscription），例如：

```sql
type User {
  id: ID!
  name: String!
  age: Int
}
type Query {
  user(id: ID!): User
}
```

Schema 是客户端与服务器的 “契约”，确保数据格式一致。

**支持复杂关联查询**
一次请求可获取多个关联资源，例如同时查询 “用户 + 其所有订单”，无需多次调用接口：

```sql
query {
  user(id: "123") {
    name
    orders {  # 关联订单
      id
      price
    }
  }
}
```

**实时数据订阅**
通过Subscription类型支持实时数据推送（如聊天消息、实时通知）。

### 2.2 优势

- **减少网络请求**：一次请求获取所有所需数据，避免 REST 的 “多次调用” 问题；
- **避免过度获取**：客户端完全控制返回字段，节省带宽和解析成本；
- **灵活适应前端变化**：前端需求变更时，无需修改后端接口，只需调整查询语句；
- **强类型校验**：Schema 确保数据类型正确，减少前后端对接错误。

### 2.3 劣势

- **缓存复杂**：REST 可基于 URI 和 HTTP 方法轻松缓存，而 GraphQL 因查询语句动态变化，缓存实现难度高；
- **查询性能风险**：复杂查询（如嵌套多层关联）可能导致服务器压力过大（需通过 “查询深度限制”“复杂度分析” 等手段控制）；
- **学习成本**：需掌握 GraphQL 语法和 Schema 设计，团队需额外培训。

### 2.4 场景

- 前端需求频繁变化的场景（如电商商品详情页、社交 APP 个人主页）；
- 需获取多关联资源的场景（如 “用户 + 文章 + 评论”）；
- 移动端应用（需减少流量消耗）。

## 三、SOAP

SOAP（Simple Object Access Protocol） 是一种**基于 XML 的协议规范**，诞生于 2000 年左右，最初用于跨平台的 “远程过程调用”（RPC），强调 “严格性” 和 “规范性”。

### 3.1 特点

**基于 XML 的消息格式**
所有数据通过 XML 格式传输，且必须包含 “SOAP 信封”（Envelope）结构，包含：

- 头部（Header）：可选，存放元数据（如身份验证、事务 ID）；
- 正文（Body）：必选，存放核心业务数据或错误信息。
  示例：

```xml
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Header>
    <authToken>abc123</authToken>
  </soap:Header>
  <soap:Body>
    <GetUserRequest><id>123</id></GetUserRequest>
  </soap:Body>
</soap:Envelope>
```

**依赖 WSDL 定义服务**
必须通过 WSDL（Web Services Description Language）文件描述 API 的功能、参数、返回值等，客户端需先解析 WSDL 才能调用（类似 “接口说明书”）。

**支持多种协议**
可基于 HTTP、SMTP、TCP 等协议传输，不限于 HTTP（REST 和 GraphQL 通常基于 HTTP）。

**强安全性与事务支持**
内置 WS-Security（安全）、WS-AtomicTransaction（事务）等规范，适合处理敏感数据和复杂业务流程（如银行转账、订单支付）。

### 3.2 优势

- **严格规范**：协议标准化程度高，适合跨企业、跨系统的严格集成；
- **强安全性**：原生支持加密、签名、身份验证，满足金融、医疗等敏感领域需求；
- **事务支持**：可保证复杂操作的原子性（如 “转账失败则回滚”）；
- **兼容性好**：早期系统（如 Java EE、.NET）广泛支持，适合 legacy 系统集成。

### 3.3 劣势

- **重量级**：XML 格式冗余，传输和解析成本高（比 JSON 大 3-5 倍）；
- **灵活性差**：接口变更需同步更新 WSDL，迭代效率低；
- **学习和维护成本高**：需理解 SOAP 协议、WSDL 语法、WS-* 规范，开发复杂度高。

### 3.4 场景

- 企业级系统集成（如 ERP、CRM 系统对接）；
- 金融、支付、医疗等对安全性和事务性要求极高的场景；
- 需兼容旧系统（如基于 SOAP 的遗留服务）。