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 特点

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

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

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

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

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

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

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

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

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）：必选，存放核心业务数据或错误信息。
示例：

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

目录CONTENT

分类类型