JSON Web Token (JWT) 在 API 设计中的应用指南

• 文档
• 教程
• 知识库

JSON Web Token（JWT）是一种紧凑、URL 安全的令牌格式，用于在 API 的通信双方之间安全地传递"声明（claims）"。它凭借轻量、无状态、可扩展的特性，成为现代 RESTful API 中认证与授权的主流方案之一。本文以本仓库 API 设计路线图 中关于 JWT 的专题为骨架，深入剖析其结构、签名机制、在 API 设计中的定位、实际使用流程与安全最佳实践，帮助你理解"为什么 JWT 能在无服务器会话存储的情况下完成身份验证与信息交换"，并掌握在 API 网关、微服务、OAuth 2.0 / OIDC 等场景中的落地要点。

JWT 是什么：定义与设计动机

在 API 设计领域，JWT 是一种广受欢迎且安全的信息传递方式。它本质上是一个自包含（self-contained）的令牌：所有需要传递的声明（如用户身份、角色、权限、过期时间）都被编码进令牌本身，而不是保存在服务器端。

JWT 的设计动机可以概括为三点：

• 紧凑（Compact）：JWT 的最终形态是一段较短的字符串，可以轻松放进 HTTP Header（如Authorization: Bearer <token>）、URL 查询参数或 Cookie 中，不会显著增加请求体积；
• URL 安全（URL-safe）：JWT 使用 Base64URL 编码，不会产生+、/、=等在 URL 传输中易出错的字符，可以直接在地址栏、查询参数中安全传递；
• 可验证（Verifiable）：令牌携带数字签名（digital signature），接收方无需访问认证中心即可验证令牌的完整性与真实性，确保 API 端点能够以安全可靠的方式处理请求。

正是这些特性，使 JWT 成为比"服务器端会话 + Session ID"更易水平扩展的认证方案：令牌可以在任意服务实例上被独立校验，服务端无需共享会话存储。

JWT 的结构解剖

一个 JWT 由三部分组成，彼此用.分隔，形如：

<Header>.<Payload>.<Signature>

例如：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Header（头部）

Header 是一个 JSON 对象，通常包含令牌的类型与签名算法，例如：

{ "alg": "HS256", "typ": "JWT" }

• typ：固定为JWT，声明这是一个 JSON Web Token；
• alg：声明签名/加密算法，常见取值包括HS256（HMAC + SHA-256，对称密钥）、RS256（RSA + SHA-256，非对称密钥）、ES256（ECDSA + SHA-256）等。

Payload（负载）

Payload 承载实际要传递的"声明"，可以划分为三类：

• 注册声明（Registered claims）：由规范定义的、具有约定语义的字段，如：
  • sub（Subject）：令牌主体，通常是用户 ID；
  • iss（Issuer）：签发者；
  • aud（Audience）：受众，即令牌面向的 API 服务；
  • exp（Expiration Time）：过期时间（Unix 时间戳）；
  • iat（Issued At）：签发时间；
  • nbf（Not Before）：在此时间之前令牌无效。
• 公共声明（Public claims）：由使用方自定义但建议在 IANA JSON Web Token Claims 注册表中登记以避免冲突的字段；
• 私有声明（Private claims）：通信双方私下约定的自定义字段，如role、tenant_id。

{ "sub": "1234567890", "name": "John Doe", "role": "admin", "iat": 1516239022, "exp": 1616239022 }

注意：Header 与 Payload 仅做 Base64URL 编码，并未加密，任何人解码即可读取内容。因此严禁在 JWT 中存放密码、身份证号等敏感数据，JWT 只适合承载可公开或非敏感的声明信息。

Signature（签名）

签名由发送方使用密钥对"编码后的 Header +.+ 编码后的 Payload"进行签名运算得到，具体流程取决于算法：

• 对称算法（如HS256）：HMACSHA256(base64url(header) + "." + base64url(payload), secret)；
• 非对称算法（如RS256）：使用私钥签名，接收方用公钥验证。

签名的意义在于：任何对 Header 或 Payload 的篡改都会导致验签失败，从而保证令牌在传输过程中的完整性与真实性。

签名算法选型：HS256 与 RS256

算法选择直接决定密钥管理方式与信任模型，是 API 设计中的关键决策：

在微服务或"认证中心统一签发、各 API 服务独立验证"的架构中，RS256是更稳妥的选择——因为任意服务只需持有公钥即可验签，即使某个服务被攻破，也不会泄露签发私钥。相关密钥生成与轮换的实践可参考本仓库的 Key Generation & Rotation 专题。

JWT 在 API 设计中的定位

与基于会话（Session）的认证对比

JWT 属于无状态令牌认证。与其形成对照的是本仓库中同样重点介绍的 Session Based Authentication：

• 会话方案在用户登录后，由服务器创建会话并关联一个 Session ID，客户端以 Cookie 保存，后续请求由服务器校验 Session ID，登出后销毁会话——状态保存在服务器端；
• JWT 方案则把全部状态内聚于令牌本身，服务器无需持久化存储令牌即可完成校验。正如 Token Based Auth 中所强调的：令牌可以由服务器创建和校验而无需持久化存储，这使应用更易于水平扩展——这正是 JWT 在现代 RESTful API 中被广泛采用的核心原因。

会话方案在"可主动撤销、即时登出"方面更有优势；而 JWT 的优势在于无状态、跨服务共享、天然适配分布式与微服务架构。两者并无绝对优劣，应根据"安全优先级"与"扩展性需求"权衡。

在 OAuth 2.0 与 OIDC 中的角色

JWT 在 OAuth 2.0 与 OpenID Connect 生态中扮演核心载体：

• 在 OAuth 2.0 授权框架中，授权服务器颁发的**访问令牌（Access Token）**常以 JWT 形式存在，客户端凭它访问受保护的 API 端点；
• 在 OIDC（OpenID Connect） 中，ID Token 本身就是一个已签名的 JWT，携带关于已认证用户（姓名、邮箱、用户 ID 等）的声明。OIDC 正是"使用 Google / GitHub / Apple 账号登录"流程背后的标准，当你的 API 需要验证"用户是谁"而非仅"有何权限"时，OIDC 是正确选择。

换言之，掌握 JWT 的结构与验签机制，是理解 OAuth 2.0 授权流程、OIDC 身份层乃至现代 API 安全体系的前提。

在 API 中的实际使用流程

一个典型的 JWT 认证流程如下：

1. 认证：客户端向认证端点提交用户名/密码等凭证；
2. 签发：认证服务器验证凭证后，构造 Header 与 Payload，使用密钥签发 JWT 并返回给客户端；
3. 携带：客户端在后续每个 API 请求的Authorization头中携带令牌：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

4. 验证：API 服务解析令牌，使用密钥（对称）或公钥（非对称）验签，并校验exp、aud、iss等声明；验证通过后从 Payload 中提取用户身份与权限，决定是否放行请求；
5. 过期与刷新：令牌过期（exp到达）后，客户端通过刷新令牌（Refresh Token）重新获取新的访问令牌，避免频繁重新登录。

在分布式场景中，这一步通常由API 网关统一完成：网关验签通过后，把用户身份注入下游请求上下文，各业务服务无需重复验签逻辑，从而简化 微服务架构 下的安全实现。

安全最佳实践

结合本仓库 API Security 与 Key Generation & Rotation 两个专题的指导方向，JWT 落地时应遵循以下实践：

• 固定算法、拒绝"算法混淆"攻击：验签时必须显式指定允许的算法（如仅允许RS256），绝不能直接采用令牌 Header 中声明的alg值，否则攻击者可伪造alg: none或切换到弱算法；
• 务必校验关键声明：验签之外，还要校验exp（是否过期）、nbf（是否生效）、aud（是否面向本 API）、iss（是否来自可信签发方）；
• 密钥管理：签名密钥应足够随机且长度达标以抵抗暴力破解；密钥需要定期轮换（按计划或在疑似泄露后），轮换时确保新旧密钥平滑过渡、不造成服务中断，这是 Key Generation & Rotation 强调的核心要点；
• 内容最小化：只放入必要的声明，绝不放入密码、密钥等敏感信息（JWT 可被任何人解码）；
• 传输安全：JWT 应仅在 HTTPS 之上传输，避免令牌在网络中被窃听；若存放在 Cookie 中，应设置HttpOnly、Secure、SameSite等属性；
• 令牌生命周期：访问令牌应设置较短的exp，配合刷新令牌机制控制风险窗口。

学习路径与延伸阅读

JWT 只是 API 认证方法谱系中的一员。在 API 设计路线图 的完整知识体系中，推荐按以下路径继续深入学习：

• Authentication Methods：概览 Basic、API Key、OAuth、JWT 等各类认证方法的适用场景；
• Token Based Auth：理解无状态令牌认证在 RESTful API 中的定位；
• Session Based Authentication：与 JWT 方案对比，掌握各自取舍；
• OAuth 2.0 与 OIDC：理解 JWT 作为访问令牌与 ID Token 的实战场景；
• Key Generation & Rotation：签名密钥的生成、分发与轮换规范；
• API Security：从整体安全视角审视认证、授权与威胁防护。

通过将 JWT 的"结构、签名、验证、密钥管理"四个层次逐一吃透，再结合 OAuth 2.0 / OIDC 的授权与身份流，你便能在实际的 API 设计工作中正确选型与安全落地 JWT，而非仅仅"会用一个库"。

• 文档
• 教程
• 知识库