03API概述

## 一、定义

API（Application Programming Interface，应用程序编程接口）是一套**预先定义的规则、协议和工具集**，用于规范不同软件组件（如应用程序、服务、模块）之间的交互方式。其核心作用是**隐藏内部实现细节**，为外部提供标准化的 “接口”，使不同系统能高效、安全地交换数据或调用功能，而无需了解对方的底层逻辑。

简单来说，API 就像 “软件之间的桥梁”：例如，天气 App 通过调用气象局的 API 获取实时数据，电商平台通过调用支付 API 完成交易，这些都是 API 的典型应用。

## 二、类型

### 2.1 按技术实现方式（最常用分类）

- **REST API（Representational State Transfer）**
  目前最流行的 API 类型，基于 HTTP/HTTPS 协议，采用 “资源” 为核心的设计理念，通过 HTTP 方法（GET/POST/PUT/DELETE 等）操作资源（如用户、订单），响应格式多为 JSON（少数为 XML）。
  特点：轻量、灵活、易于理解，适合大多数 Web 服务（如社交平台 API、电商 API）。
- **SOAP API（Simple Object Access Protocol）**
  基于 XML 的协议，定义了严格的规范（如消息格式、错误处理、安全机制），需通过 XML 格式封装请求和响应。
  特点：安全性高（支持 WS-Security）、规范性强，适合企业级复杂场景（如银行、医疗系统的跨机构数据交互），但较笨重，开发成本高。
- **GraphQL API**
  由 Facebook 推出的查询语言，允许客户端**精确指定需要的数据**（而非服务器返回固定结构），减少冗余数据传输。
  特点：灵活高效，适合前端需要动态获取不同字段的场景（如移动应用），但学习成本较高。
- **gRPC API**
  基于 HTTP/2 和 Protocol Buffers（二进制序列化协议）的高性能 API，支持跨语言调用，采用 “远程过程调用（RPC）” 模式，适合服务间高频通信（如微服务架构）。
  特点：传输效率高（二进制协议）、支持流式通信，性能优于 REST。
- **WebSocket API**
  基于 WebSocket 协议的全双工通信 API，支持服务器主动向客户端推送数据（如实时聊天、股票行情更新），区别于 REST 的 “请求 - 响应” 模式。

### 2.2 按使用范围

- **公共 API（Public API）**：开放给外部开发者使用，通常需申请 API 密钥（API Key），有调用限额（如微信开放平台 API、高德地图 API）。
- **私有 API（Private API）**：仅用于内部系统交互（如企业内部前后端分离项目中，前端调用后端的 API），不对外暴露。
- **合作伙伴 API（Partner API）**：仅授权给特定合作伙伴使用（如电商平台与物流公司的 API 对接）。

### 2.3 按功能用途

- **数据 API**：提供数据查询或修改（如获取用户信息、提交订单）。
- **功能 API**：调用特定功能（如支付 API、人脸识别 API、短信发送 API）。
- **系统 API**：操作底层系统资源（如操作系统 API、数据库 API）。

## 三、核心组成部分

无论哪种 API，其交互都围绕以下核心要素展开：

**端点（Endpoint）**
标识 API 资源的 URL（统一资源定位符），是客户端发送请求的目标地址。
例：https://api.example.com/users（用户资源端点）、https://api.example.com/orders/123（ID 为 123 的订单资源端点）。

**请求方法（Method）**
定义对资源的操作类型，不同 API 协议对应不同方法：

- REST API：使用 HTTP 方法（GET 获取、POST 创建、PUT 全量更新、DELETE 删除、PATCH 部分更新）。
- SOAP API：通过 XML 标签定义方法（如<GetUser>、<CreateOrder>）。
- GraphQL：通过查询语句定义操作（如query { user(id: 1) { name } }）。

**参数（Parameters）**
客户端向 API 传递的数据，常见类型：

- 路径参数（Path Parameters）：嵌入 URL 路径中（如/users/{id}中的id）。
- 查询参数（Query Parameters）：跟在 URL“?” 后（如/users?page=1&size=10）。
- 请求体（Request Body）：常用于 POST/PUT 请求，携带复杂数据（如 JSON 格式的用户信息）。
- 请求头（Headers）：传递元信息（如认证令牌、数据格式）。

**响应（Response）**
服务器处理请求后返回的结果，包含：

- 状态码（如 HTTP 状态码 200 成功、404 资源不存在）。
- 响应体（Response Body）：实际数据（如 JSON 格式的用户列表）。
- 响应头（Headers）：元信息（如数据类型、缓存规则）。

**认证与授权（Authentication & Authorization）**
确保 API 调用的合法性：

- 认证：验证调用者身份（如 API Key、Token 令牌、OAuth2.0、用户名密码）。
- 授权：验证调用者是否有权限执行操作（如普通用户不能删除其他用户数据）。

**错误处理**
当请求失败时，返回清晰的错误信息（如错误码、描述），帮助调试（如{"error": "Invalid token", "code": 401}）。

## 四、工作原理

其工作原理可概括为 “请求 - 处理 - 响应” 的闭环，无论哪种类型的 API，均遵循类似的交互逻辑：

**发起请求**：调用方（如应用 A）根据 API 定义的规则，生成包含 “目标资源、操作类型、参数、认证信息” 的请求（如通过 HTTP 协议发送到指定 URL）。

- 例：手机 App 调用天气 API 时，需指定城市 ID（参数）、携带 API Key（认证），通过GET方法请求天气数据。

**接口层接收与验证**：API 接口层（如服务器的 API 网关）接收请求，首先验证合法性（如认证信息是否有效、参数是否符合格式），不合法则直接返回错误（如 401 未授权）。

**业务逻辑处理**：验证通过后，API 将请求转发至对应的业务层（如后端服务），执行具体操作（如查询数据库、调用内部功能）。

- 例：用户 API 接收到GET /users/123请求后，查询数据库中 ID=123 的用户信息。

**生成响应**：业务层处理完成后，将结果按 API 定义的格式（如 JSON）封装为响应，包含状态信息（如成功 / 失败）和数据（如用户详情），通过接口层返回给调用方。

**解析响应**：调用方（应用 A）解析响应数据，根据结果执行后续操作（如显示天气、提示错误）。、

**核心本质**：API 作为中间层，隔离了调用方与被调用方的内部实现（如应用 A 无需知道天气数据来自哪个数据库），仅通过标准化接口完成交互。

## 五、API 设计原则

优质 API 需满足以下核心原则，以提升易用性、可维护性和扩展性：

**一致性**：命名规则、参数格式、响应结构保持统一（如所有资源端点用复数名词/users而非/user）。

**资源导向**（REST API）：以 “资源” 为核心设计端点，而非 “操作”（如/orders而非/getOrders）。

**无状态**：服务器不存储客户端状态，每次请求需包含所有必要信息（便于水平扩展）。

**安全性**：强制认证授权，敏感数据加密传输（HTTPS），防止 SQL 注入、XSS 等攻击。

**可版本化**：支持版本控制（如/v1/users、/v2/users），避免升级 API 时影响旧用户。

**可文档化**：提供清晰的文档（如使用 Swagger/OpenAPI），说明端点、参数、响应、示例。

**容错性**：返回明确的错误信息，支持幂等性（如重复调用 PUT 请求不会产生副作用）。

## 六、REST API 规范（核心原则与设计标准）

REST（Representational State Transfer）是目前最主流的 API 规范，其设计严格遵循以下原则，确保接口的简洁性和可扩展性：

**资源导向**：以 “资源”（如用户、订单、商品）为核心，URI（统一资源标识符）需直接标识资源，而非 “操作”。

- 例：用/users表示用户资源集合，/users/123表示 ID=123 的单个用户（而非/getUser?id=123）。

**HTTP 方法对应操作**：通过 HTTP 方法表达对资源的操作意图，形成 “CRUD-HTTP 方法” 映射：

- GET：查询资源（如GET /users获取所有用户）；
- POST：创建资源（如POST /users新增用户，数据放在请求体）；
- PUT：全量更新资源（如PUT /users/123覆盖 ID=123 的用户信息）；
- PATCH：部分更新资源（如PATCH /users/123仅修改用户手机号）；
- DELETE：删除资源（如DELETE /users/123删除 ID=123 的用户）。

**无状态**：服务器不存储客户端状态，每次请求需包含所有必要信息（如认证令牌），便于服务器水平扩展（多实例共享负载）。

**URI 设计规范**：

- 用复数名词表示资源集合（/users而非/user）；
- 避免动词（如不用/deleteUser，而用DELETE /users/123）；
- 通过子路径表示资源关联（如/users/123/orders表示用户 123 的订单）；
- 支持版本控制（如/v1/users，避免 API 升级影响旧调用方）。

**使用标准 HTTP 状态码**：通过状态码表达请求结果（而非自定义错误码）：

- 200（成功）、201（创建成功）；
- 400（请求参数错误）、401（未认证）、403（无权限）、404（资源不存在）；
- 500（服务器内部错误）。

## 七、交换格式

API 需通过标准化格式传输数据，不同格式适用于不同场景，核心格式如下：

| 格式                               | 特点                                                         | 适用场景                                                     |
| ---------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| JSON（JavaScript Object Notation） | 轻量、易读、结构灵活（键值对 + 数组），解析效率高，支持多语言。 | REST API 主流格式，Web 应用、移动 App（如{"id":1,"name":"Alice"}）。 |
| XML（eXtensible Markup Language）  | 结构化强（标签嵌套）、支持复杂元数据，可自定义标签，但冗余度高。 | SOAP API 默认格式，企业级系统（如银行交易数据：<user><id>1</id></user>）。 |
| Protocol Buffers（Protobuf）       | 二进制格式，体积小、解析快（比 JSON 小 30%-50%），需预定义数据结构（.proto 文件）。 | gRPC API 默认格式，微服务内部高频通信（性能优先场景）。      |
| CSV（Comma-Separated Values）      | 纯文本，用逗号分隔字段，结构简单，适合表格类数据（如报表）。 | 数据导出接口（如导出用户列表：id,name\n1,Alice\n2,Bob）。    |

## 八、身份验证

API 身份验证（Authentication）用于验证调用方的身份（确保 “正确的人访问正确的资源”），而授权（Authorization）用于控制其可访问的资源范围，两者结合保障 API 安全。常见认证方式如下：

**API Key**

- 原理：调用方在请求中携带预设的密钥（如在请求头或查询参数中添加api_key=xxx），服务器验证密钥有效性。
- 优点：简单易实现；缺点：密钥易泄露（明文传输风险），无过期机制。
- 适用场景：内部系统调用、对安全性要求不高的公开 API（如天气查询）。

**Token 认证（如 JWT）**

- 原理：调用方登录后，服务器生成包含用户信息的加密令牌（Token），后续请求在头中携带Authorization: Bearer <token>，服务器解密验证。
- 优点：无状态（服务器无需存储令牌）、可设置过期时间、支持携带用户信息；缺点：令牌泄露即被盗用（需短期过期）。
- 适用场景：前后端分离项目、移动 App（如用户登录后调用个人中心 API）。

**OAuth 2.0**

- 原理：第三方应用通过授权服务器获取 “访问令牌”（Access Token），而非直接使用用户账号密码，支持 “授权范围” 控制（如仅允许获取用户昵称，不允许修改信息）。
- 优点：安全（用户无需向第三方暴露密码）、细粒度授权；缺点：流程复杂。
- 适用场景：第三方登录（如 “用微信登录 App”）、跨平台授权（如小程序调用微信支付 API）。

**Basic Auth**

- 原理：调用方在请求头中携带 “用户名：密码” 的 Base64 编码（Authorization: Basic <编码后字符串>），服务器解码验证。
- 优点：简单；缺点：Base64 编码可逆（本质明文），需配合 HTTPS 使用。
- 适用场景：内部测试接口、简单的后台管理 API。

**OAuth 2.0 + OpenID Connect（OIDC）**

- 原理：在 OAuth 2.0 基础上增加身份验证层，返回包含用户身份信息的 ID Token，同时支持 Access Token 授权。
- 适用场景：企业级单点登录（SSO），如多系统共用一套身份体系。

## 九、概述

API 的核心价值在于通过标准化接口实现软件间的高效协作：不同类型的 API（REST、SOAP  等）遵循各自的规范，但均需通过特定格式（JSON、XML 等）传输数据，而身份验证机制则确保 API 仅被授权方使用。其中，REST API  因灵活性和易用性成为主流，其规范（资源导向、HTTP 方法映射等）是 API 设计的核心参考。