Claims

Claims

type Claims struct {
    UserID      string         `json:"user_id,omitempty"`
    Username    string         `json:"username,omitempty"`
    Role        string         `json:"role,omitempty"`
    Permissions []string       `json:"permissions,omitempty"`
    Scopes      []string       `json:"scopes,omitempty"`
    Extra       map[string]any `json:"extra,omitempty"`
    SessionID   string         `json:"session_id,omitempty"`
    ClientID    string         `json:"client_id,omitempty"`
    RegisteredClaims
}

内置 Claims 结构，包含常用业务字段和标准 JWT 字段。

struct

字段

字段	类型	说明
UserID	string	用户 ID
Username	string	用户名
Role	string	角色
Permissions	[]string	权限列表
Scopes	[]string	作用域列表
Extra	map[string]any	自定义扩展字段
SessionID	string	会话 ID
ClientID	string	客户端 ID
RegisteredClaims	RegisteredClaims	标准 JWT 字段

验证规则

Validate() 方法检查 UserID 或 Username 至少有一个非空。

Processor 在令牌创建和验证时会执行额外的深度验证（通过内部 validateClaims 函数）：

规则	限制
字符串字段长度	最大 256 字符
数组字段大小	最大 100 项
Extra 字段数	最大 50 个键
Extra 值类型	仅允许 string、[]string，嵌套 map 和其他类型拒绝
控制字符	除 tab、换行、回车外的控制字符拒绝
注入模式检测	包含 HTML/SQL/路径遍历等危险模式时拒绝

方法

方法	签名	说明
GetRegisteredClaims	func (c *Claims) GetRegisteredClaims() *RegisteredClaims	返回嵌入的标准字段
Validate	func (c *Claims) Validate() error	检查 UserID 或 Username 至少有一个非空

除上表两个业务方法外，Claims 还实现了 json.Marshaler / json.Unmarshaler 等序列化管道方法：MarshalJSON、UnmarshalJSON、AppendJSON（向可复用缓冲区追加编码，供签名管道使用）与 UnmarshalFastJSON（内部快速解码钩子）。它们由库的签名与解析管道自动调用，常规业务代码无需直接调用，细节见源码 claims_json.go。

---

RegisteredClaims

type RegisteredClaims struct {
    Issuer    string        `json:"iss,omitempty"`
    Subject   string        `json:"sub,omitempty"`
    Audience  StringOrSlice `json:"aud,omitempty"`
    ExpiresAt NumericDate   `json:"exp"`
    NotBefore NumericDate   `json:"nbf"`
    IssuedAt  NumericDate   `json:"iat"`
    ID        string        `json:"jti,omitempty"`
    TokenType string        `json:"token_type,omitempty"`
}

标准 JWT 注册声明（RFC 7519）。

struct

字段

字段	类型	JSON Tag	说明
Issuer	string	iss	签发者
Subject	string	sub	主题
Audience	StringOrSlice	aud	受众
ExpiresAt	NumericDate	exp	过期时间
NotBefore	NumericDate	nbf	生效时间
IssuedAt	NumericDate	iat	签发时间
ID	string	jti	令牌 ID
TokenType	string	token_type	令牌类型（access 或 refresh，见 TokenType 常量）