4. JWT Payload 详解：注册声明、公共声明与私有声明

JWT 的 Payload（载荷）是承载实际数据的核心部分，它是一个 JSON 对象，包含一组声明（Claims）。声明是关于实体（通常是用户）和附加数据的陈述。根据 JWT 标准（RFC 7519），声明分为三类：注册声明、公共声明和私有声明。理解这三类声明的用途、规范与安全约束，是设计健壮 JWT 接口契约的基础。

4.1 注册声明（Registered Claims）

注册声明是一组预定义的、非强制但推荐使用的声明，旨在提供互操作性。它们由 IANA JSON Web Token Claims 注册表维护。以下是七个最核心的注册声明：

注册声明验证流程图

4.2 公共声明（Public Claims）

公共声明是由使用者自行定义的声明，但为了避免与注册声明或其他公共声明冲突，必须遵循以下两种方式之一：

• 方式一：使用 IANA 注册 — 在 IANA JSON Web Token Claims 注册表 中注册你的声明名称，确保全球唯一性。
• 方式二：使用 Collision-Resistant Name（防冲突命名） — 将声明名定义为包含命名空间的 URI 或具有足够复杂度的字符串，例如：https://api.example.com/claims/role 或 com.example.role。

公共声明示例

{
  "iss": "https://auth.example.com",
  "sub": "user_98765",
  "aud": "https://api.example.com",
  "exp": 1735689600,
  "iat": 1735686000,
  // 以下是公共声明（使用防冲突命名）
  "https://api.example.com/claims/role": "admin",
  "com.example.department": "engineering",
  "com.example.permissions": ["read:users", "write:projects"]
}

4.3 私有声明（Private Claims）

私有声明是通信双方（签发者和接收者）之间私下约定的声明，不进行注册，也不使用防冲突命名。它们仅在特定的、受控的上下文中有效。

• 适用场景： 单一应用内部、前后端之间、或两个紧密耦合的微服务之间。
• 风险： 如果服务被外部调用或与其他系统集成，私有声明可能发生命名冲突，导致意外覆盖或解析错误。
• 建议： 除非是绝对受控的内部环境，否则优先使用公共声明（带命名空间）替代私有声明。

私有声明示例

{
  "iss": "auth-service",
  "sub": "user_123",
  "exp": 1735689600,
  // 以下是私有声明（仅内部约定）
  "role": "editor",
  "dept": "marketing",
  "is_temp": false
}

4.4 三类声明对比总结

4.5 Payload 安全设计清单

1. 最小化原则： Payload 只存放必要的数据，避免冗余信息增加 token 体积。
2. 禁止敏感数据： 密码、密钥、完整身份证号、信用卡号等绝对不可放入 Payload。
3. 使用短有效期： exp 建议设置为 15-60 分钟，降低 token 泄露风险。
4. 验证所有注册声明： 服务端必须验证 iss、aud、exp、nbf（如果存在）。
5. 防重放： 关键操作必须使用 jti 并维护已用 ID 列表。
6. 命名规范： 优先使用公共声明命名方式，避免私有声明带来的冲突隐患。