6. 接口-专栏说明

文章目录

前言
[一、API 设计与通信范式](#一、API 设计与通信范式)
- [1. REST 架构风格](#1. REST 架构风格)
- [2. HATEOAS（Hypermedia as the Engine of Application State）](#2. HATEOAS（Hypermedia as the Engine of Application State）)
- [3. OpenAPI Specification（OAS）](#3. OpenAPI Specification（OAS）)
- [4. JSON (JavaScript Object Notation)](#4. JSON (JavaScript Object Notation))
- [5. SOAP (Simple Object Access Protocol)](#5. SOAP (Simple Object Access Protocol))
- [6. gRPC](#6. gRPC)
- [7. GraphQL](#7. GraphQL)
[二、主流 API 协议与框架对比](#二、主流 API 协议与框架对比)
[三、API 认证与授权技术（Authentication & Authorization）](#三、API 认证与授权技术（Authentication & Authorization）)
- [1. Basic Authentication](#1. Basic Authentication)
- [2. Cookie-Based Authentication](#2. Cookie-Based Authentication)
- [3. Token Authentication（自定义 Token）](#3. Token Authentication（自定义 Token）)
- [4. JWT（JSON Web Token）](#4. JWT（JSON Web Token）)
- [5. OAuth 2.0](#5. OAuth 2.0)
- [6. OpenID Connect（OIDC）](#6. OpenID Connect（OIDC）)
- [7. SAML（Security Assertion Markup Language）](#7. SAML（Security Assertion Markup Language）)
四、应用场景
五、延伸方向

前言

API（应用程序接口）‌

了解Open API Specs规范、REST架构、HATEOAS规则、JSON、SOAP、gRPC、GraphQL等基础理论，

掌握JWT、OAuth、Basic Authentication、Token Authentication、Cookie Based Authentication、OpenID、SAML等Authentication认证技术‌。

聚焦于 API（应用程序接口）的设计规范、通信协议与安全认证机制 ，这是现代软件系统（尤其是 Web 服务和微服务架构）的核心组成部分。下面将围绕"接口（APIs）"这一主题，对这些知识点进行结构化梳理，并说明它们在实际开发中的作用与关系。

一、API 设计与通信范式

1. REST 架构风格

是什么？ 一种软件架构风格，用于设计网络应用程序。它基于 HTTP 协议，利用其标准方法（GET, POST, PUT, DELETE 等）来对资源进行操作。
核心思想：以资源为中心，使用标准 HTTP 方法操作资源。
核心原则：
- 资源 (Resources): 将所有事物抽象为资源，每个资源有唯一的标识符（URI）。
- 统一接口 (Uniform Interface): 使用标准的 HTTP 方法操作资源。
- 无状态 (Stateless): 每个请求都包含处理该请求所需的所有信息，服务器不保存客户端的状态。
- 可缓存 (Cacheable): 响应可以被标记为可缓存或不可缓存。
- 分层系统 (Layered System): 客户端通常不知道是否直接连接到最终服务器，中间可能有代理、网关等。
- 按需代码 (Code on Demand - 可选): 服务器可以临时向客户端发送可执行代码（如 JavaScript）。
典型用法：

http 复制代码

GET /users/123      → 获取用户
POST /users         → 创建用户
PUT /users/123      → 全量更新
PATCH /users/123    → 部分更新
DELETE /users/123   → 删除

2. HATEOAS（Hypermedia as the Engine of Application State）

是什么？ REST 的高级实践，强调 超媒体驱动 。REST 架构的一个约束条件。它要求 API 响应中不仅返回数据，还应包含相关的可操作的链接，指导客户端如何进行下一步操作。客户端无需硬编码 URL。
作用： 使客户端能够动态发现和导航 API，减少对硬编码 URL 和操作流程的依赖，提高 API 的灵活性和可演化性。
示例：

json 复制代码

{
  "id": 1,
  "name": "Alice",
  "_links": {
    "self": { "href": "/users/1" },
    "orders": { "href": "/users/1/orders" }
  }
}

优势：提升 API 的可发现性与演化能力。
现实挑战：前端开发复杂度增加，普及度不如基础 REST。

3. OpenAPI Specification（OAS）

是什么？ 一种用于描述 RESTful API 的标准化语言（通常是 YAML 或 JSON 格式）。它定义了 API 的结构，包括端点（路径）、操作方法（GET, POST, PUT, DELETE 等）、输入/输出参数、数据类型、认证方式等。
作用： 标准化描述 RESTful API 的接口契约。提高开发效率（通过代码生成工具）、促进团队协作、方便文档编写与维护、便于测试自动化、支持 API 网关管理等。
格式：YAML 或 JSON（如 openapi: 3.1.0）。
关键能力 ：
- 自动生成交互式文档（Swagger UI）
- 生成客户端 SDK（如 TypeScript、Python）
- 自动化测试与 Mock Server
核心字段 ：paths, components/schemas, security, responses

✅ 实践建议：所有对外暴露的 REST API 都应提供 OpenAPI 文档。

4. JSON (JavaScript Object Notation)

是什么？ 一种轻量级的数据交换格式，易于人阅读和编写，也易于机器解析和生成。它是 REST API 中最常用的数据格式之一。

5. SOAP (Simple Object Access Protocol)

是什么？ 一种基于 XML 的协议，用于在网络上交换结构化信息。它通常运行在 HTTP 或 SMTP 等其他应用协议之上。
特点： 相比 REST 更加严格和复杂，具有内置的错误处理机制、安全性和事务支持（WS-Security, WS-ReliableMessaging 等），但性能开销较大。

6. gRPC

是什么？ Google 开发的高性能、开源的通用 RPC（远程过程调用）框架。它使用 Protocol Buffers (protobuf) 作为接口定义语言（IDL）和底层消息交换格式。
特点： 支持多种编程语言，提供高效的序列化（相比 JSON/XML），支持流式调用（客户端流、服务端流、双向流），默认使用 HTTP/2 协议。

7. GraphQL

是什么？ Facebook 开发的一种用于 API 的查询语言和运行时环境。客户端可以精确地指定需要哪些数据，服务端根据查询返回相应的数据结构。
特点： 解决了 REST 中常见的"过度获取"或"获取不足"的问题，允许在一个请求中获取多个资源，强类型 Schema，实时数据推送（Subscriptions）。

二、主流 API 协议与框架对比

技术	类型	数据格式	传输协议	特点
REST	架构风格	JSON/XML	HTTP/1.1	简单、广泛支持、适合 Web
SOAP	协议	XML	HTTP/SMTP	严格规范、WS-Security、企业级（银行、政府）
gRPC	RPC 框架	Protocol Buffers	HTTP/2	高性能、双向流、强类型、适合内部微服务
GraphQL	查询语言	JSON	HTTP	客户端按需取数、减少请求次数、单一端点

📌 选型建议：

对外开放 Web API → REST + JSON + OpenAPI

移动端需要灵活查询 → GraphQL

微服务内部高性能通信 → gRPC

传统企业集成系统 → SOAP

三、API 认证与授权技术（Authentication & Authorization）

⚠️ 区分：

Authentication（认证）：验证"你是谁"

Authorization（授权）：决定"你能做什么"

1. Basic Authentication

是什么？ 一种简单的 HTTP 认证方案。客户端将用户名和密码组合成 "username:password" 字符串，然后对其进行 Base64 编码，并放在 HTTP 请求头的 Authorization 字段中传递凭证（Authorization: Basic <base64-encoded-string>）。
特点： 实现简单，但安全性低（Base64 易解码），必须配合 HTTPS，否则密码明文可解码。适用于简单脚本或内部工具。

是什么？ 利用 HTTP Cookies 进行身份验证。用户登录成功后，服务器创建一个 Session，并将 Session ID 存储在 Cookie 中返回给客户端。浏览器会自动在后续请求中携带这个 Cookie。
- 登录后服务端创建 Session，返回 Set-Cookie: sessionId=xxx
- 浏览器自动携带 Cookie
特点：依赖服务端存储 Session**（如 Redis），天然支持 CSRF 防护（需配合 SameSite + CSRF Token）但也容易受到攻击，常用于传统的 Web 应用。

3. Token Authentication（自定义 Token）

是什么？ 这是一个比较宽泛的概念，指使用 Token 来验证用户身份。JWT 是其中一种实现方式。
一般流程： 用户凭据（如用户名/密码）登录 -> 服务器验证 -> 服务器生成一个 Token 并返回 -> 客户端存储 Token -> 后续请求携带 Token -> 服务器验证 Token。
- 登录成功后返回一个随机字符串（如 UUID）
- 客户端在 Header 中携带：Authorization: Bearer <token>
- 服务端需维护 Token 与用户映射（可存 DB/Redis）
- 支持过期、撤销，但需自行实现
Token 类型： 可以是随机字符串（需要服务器存储映射关系），也可以是 JWT（无状态）。

4. JWT（JSON Web Token）

是什么？ 一种开放标准 (RFC 7519)，定义了一种紧凑且自包含的方式，用于在各方之间以 JSON 对象的形式安全地传输信息。信息可以被验证和信任，因为它是数字签名的。
- 自包含令牌的三段格式：Header.Payload.Signature
- Payload 可含用户 ID、角色、过期时间等
工作原理： 用户登录成功后，服务器生成一个 JWT 并返回给客户端。客户端在后续请求中将 JWT 放入 HTTP Header（通常是 Authorization: Bearer <token>）发送给服务器。服务器验证 JWT 的签名并从中提取用户信息。
优点： 无状态（服务器无需存储 Session，通过签名验证合法性），跨域友好，可携带用户信息。
缺点： Token 泄露风险，无法主动失效（除非过期或引入黑名单机制），Payload 是 Base64 编码，非加密，敏感信息不应放入。
常用于：API 网关、移动端、无状态微服务

5. OAuth 2.0

是什么？ OAuth 是一个开放标准，允许用户提供一个令牌，而不是用户名和密码来访问他们存储在其他服务提供商那里的特定资源。最常见的版本是 OAuth 2.0。
目的： 授权（Authorization），而非认证。它解决的是"第三方应用如何在用户许可下访问用户在某服务上的资源"的问题。
角色： 资源拥有者（Resource Owner，用户）、客户端（Client，第三方应用）、授权服务器（Authorization Server）、资源服务器（Resource Server）。
流程： 四种授权模式（Authorization Code、Implicit、Resource Owner Password Credentials、Client Credentials），其中 Authorization Code 授权码模式最常用且最安全。
是授权框架，不是认证协议！
允许第三方应用在用户授权下访问资源（如"用微信登录"）
常见流程：
- Authorization Code（Web 应用）
- PKCE（SPA/移动 App 安全增强）
- Client Credentials（服务间通信）
不返回用户身份信息 → 需结合 OpenID Connect 进行身份认证

6. OpenID Connect（OIDC）

是什么？ 建立在 OAuth 2.0 之上的身份认证层。它允许客户端验证终端用户的身份，并获取有关终端用户的基本配置文件信息。
目的： 认证 + 授权。它解决了"谁是用户"的问题，并可以获取用户基本信息。
- 与 OAuth 2.0 关系： OAuth 2.0 处理授权，OIDC 在此基础上增加了身份验证功能。OIDC 使用 OAuth 2.0 的流程来传递身份信息（主要通过 ID Token，一种特殊的 JWT）。
- 返回 id_token（JWT），包含用户基本信息
- 实现标准 SSO（单点登录）
主流 Identity Provider：Auth0、Okta、Google、Keycloak

7. SAML（Security Assertion Markup Language）

是什么？ 一个基于 XML 的开放标准，企业级 SSO 协议，用于在不同的安全域之间交换身份验证和授权数据。主要用于企业级单点登录 (SSO) 场景。
特点： 结构复杂，配置繁琐，但在企业环境中非常成熟和强大，支持多种绑定（HTTP Redirect, HTTP POST, Artifact 等）。
- 主要用于 B2B 或企业内网（如员工登录多个系统）
- 流程涉及 IdP（身份提供商）与 SP（服务提供商）
- 与 OIDC 对比：
  - SAML：更重、XML、适合传统企业
  - OIDC：轻量、JSON、适合互联网/Web 应用

四、应用场景

场景	推荐方案
公开 Web API	REST + JSON + OpenAPI + JWT/OAuth2
内部微服务通信	gRPC + mTLS + Service Account Token
移动 App 后端	REST 或 GraphQL + JWT + Refresh Token
企业 SSO 集成	SAML（传统）或 OIDC（现代）
第三方登录	OAuth 2.0 + OpenID Connect

五、延伸方向

API 网关：Kong, Apigee, AWS API Gateway（统一认证、限流、日志）
安全加固：HTTPS、CORS、Rate Limiting、JWT 黑名单、CSRF 防护
自动化：用 OpenAPI 生成 Postman 集合、自动化测试脚本
新兴趋势：AsyncAPI（用于事件驱动 API）、tRPC（TypeScript 全栈 RPC）