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 的遗留服务）。