Processor

Processor 是 JWT 操作的核心类型，实现了 TokenManager 接口。所有方法并发安全。

通过 jwt.New(cfg) 创建实例。

Create

func (p *Processor) Create(claims CustomClaims) (string, error)

创建新的 JWT 访问令牌。接受任何实现 CustomClaims 接口的类型。

参数

参数	类型	说明
`claims`	`CustomClaims`	令牌声明

返回值

返回	类型	说明
`token`	`string`	签名的 JWT 字符串
`err`	`error`	验证或签名失败时返回错误

错误

错误	触发条件
`ErrProcessorClosed`	Processor 已关闭
`ErrInvalidClaims`	Claims 验证失败
`ErrRateLimitExceeded`	超出限流阈值

示例

// 内置 Claims
claims := &jwt.Claims{UserID: "user123", Username: "alice"}
token, err := processor.Create(claims)

// 自定义 Claims
myClaims := &MyClaims{UserID: "123"}
token, err := processor.Create(myClaims)

Validate

func (p *Processor) Validate(tokenString string) (Claims, bool, error)

验证 JWT 访问令牌，返回解析后的 Claims。

参数

参数	类型	说明
`tokenString`	`string`	JWT 字符串

返回值

返回	类型	说明
`claims`	`Claims`	解析后的声明（值拷贝）
`valid`	`bool`	是否有效
`err`	`error`	验证失败时返回错误

错误

错误	触发条件
`ErrProcessorClosed`	Processor 已关闭
`ErrEmptyToken`	令牌为空
`ErrInvalidToken`	签名无效
`ErrAlgorithmMismatch`	令牌算法与配置不匹配
`ErrExpirationRequired`	启用 `RequireExpiration` 但令牌缺少 `exp` 声明
`ErrTokenExpired`	令牌过期
`ErrTokenNotValidYet`	令牌尚未生效
`ErrTokenInvalidIssuer`	签发者不匹配
`ErrTokenInvalidAudience`	受众不匹配
`ErrTokenRevoked`	令牌已吊销
`ErrInvalidClaims`	Claims 验证失败

示例

claims, valid, err := processor.Validate(tokenString)
if err != nil {
    // 处理错误
    return
}
if valid {
    fmt.Println(claims.UserID)
}

CreateRefresh

func (p *Processor) CreateRefresh(claims CustomClaims) (string, error)

创建刷新令牌，使用 RefreshTokenTTL 而非 AccessTokenTTL。

参数

参数	类型	说明
`claims`	`CustomClaims`	令牌声明

返回值

返回	类型	说明
`token`	`string`	签名的刷新令牌
`err`	`error`	验证或签名失败时返回错误

错误

错误	触发条件
`ErrProcessorClosed`	Processor 已关闭
`ErrInvalidClaims`	Claims 验证失败
`ErrRateLimitExceeded`	超出限流阈值

Refresh

func (p *Processor) Refresh(refreshTokenString string) (string, error)

刷新现有的刷新令牌，返回新的访问令牌。刷新令牌会先经过完整验证（签名、过期、黑名单），通过后签发新的访问令牌；原令牌的 IssuedAt、ExpiresAt、ID 会被重置并重新生成。

令牌类型与轮换

令牌类型校验：token_type=access 的令牌会被拒绝（返回 ErrTokenTypeMismatch），防止用访问令牌换取新令牌；未携带 token_type 的旧令牌出于向后兼容仍被接受。
不会自动吊销原令牌：Refresh 不会吊销传入的刷新令牌，原令牌在过期或被显式 Revoke() 之前始终有效。如需"一次性使用"语义，请在 Refresh 成功后调用 Revoke(refreshTokenString)。

安全说明

刷新时仅验证标准 JWT 字段（exp、nbf、iss、aud、黑名单）和基本结构有效性（UserID 或 Username 必须存在）。深度字段约束（长度限制、注入模式）不会重新检查，因为它们在创建时已验证。

参数

参数	类型	说明
`refreshTokenString`	`string`	刷新令牌

返回值

返回	类型	说明
`token`	`string`	新的访问令牌
`err`	`error`	验证失败时返回错误

错误

错误	触发条件
`ErrProcessorClosed`	Processor 已关闭
`ErrEmptyToken`	令牌为空
`ErrInvalidToken`	签名无效
`ErrAlgorithmMismatch`	令牌算法与配置不匹配
`ErrExpirationRequired`	启用 `RequireExpiration` 但令牌缺少 `exp` 声明
`ErrTokenExpired`	令牌过期
`ErrTokenNotValidYet`	令牌尚未生效
`ErrTokenInvalidIssuer`	签发者不匹配
`ErrTokenInvalidAudience`	受众不匹配
`ErrTokenRevoked`	令牌已吊销
`ErrInvalidClaims`	Claims 验证失败
`ErrTokenTypeMismatch`	用访问令牌（`token_type=access`）尝试刷新
`ErrRateLimitExceeded`	超出限流阈值

ValidateInto

func (p *Processor) ValidateInto(tokenString string, claims CustomClaims) (CustomClaims, bool, error)

验证令牌并填充到自定义 Claims 结构。返回与传入的 claims 相同的指针。

参数

参数	类型	说明
`tokenString`	`string`	JWT 字符串
`claims`	`CustomClaims`	目标 Claims 指针

返回值

返回	类型	说明
`claims`	`CustomClaims`	填充后的 Claims
`valid`	`bool`	是否有效
`err`	`error`	验证失败时返回错误

示例

myClaims := &MyClaims{}
result, valid, err := processor.ValidateInto(tokenString, myClaims)
if valid {
    fmt.Println(result.(*MyClaims).UserID)
}

错误

错误	触发条件
`ErrProcessorClosed`	Processor 已关闭
`ErrEmptyToken`	令牌为空
`ErrInvalidToken`	签名无效
`ErrAlgorithmMismatch`	令牌算法与配置不匹配
`ErrExpirationRequired`	启用 `RequireExpiration` 但令牌缺少 `exp` 声明
`ErrTokenExpired`	令牌过期
`ErrTokenNotValidYet`	令牌尚未生效
`ErrTokenInvalidIssuer`	签发者不匹配
`ErrTokenInvalidAudience`	受众不匹配
`ErrTokenRevoked`	令牌已吊销
`ErrInvalidClaims`	Claims 验证失败

RefreshInto

func (p *Processor) RefreshInto(refreshTokenString string, claims CustomClaims) (string, error)

使用自定义 Claims 刷新令牌。Claims 对象的时序字段（IssuedAt、ExpiresAt、ID）在操作后自动恢复，即使发生错误或 panic 也能保证恢复。

令牌类型校验

token_type=access 的令牌会被拒绝（返回 ErrTokenTypeMismatch），防止用访问令牌换取新令牌；未携带 token_type 的旧令牌出于向后兼容仍被接受。

安全说明

刷新时仅验证标准 JWT 字段（exp、nbf、iss、aud、黑名单）和基本结构有效性。深度字段约束（长度限制、注入模式）不会重新检查，因为它们在创建时已验证。

参数

参数	类型	说明
`refreshTokenString`	`string`	刷新令牌
`claims`	`CustomClaims`	目标 Claims 指针

返回值

返回	类型	说明
`token`	`string`	新的访问令牌
`err`	`error`	验证失败时返回错误

错误

错误	触发条件
`ErrProcessorClosed`	Processor 已关闭
`ErrEmptyToken`	令牌为空
`ErrInvalidToken`	签名无效
`ErrAlgorithmMismatch`	令牌算法与配置不匹配
`ErrExpirationRequired`	启用 `RequireExpiration` 但令牌缺少 `exp` 声明
`ErrTokenExpired`	令牌过期
`ErrTokenNotValidYet`	令牌尚未生效
`ErrTokenInvalidIssuer`	签发者不匹配
`ErrTokenInvalidAudience`	受众不匹配
`ErrTokenRevoked`	令牌已吊销
`ErrInvalidClaims`	Claims 验证失败
`ErrTokenTypeMismatch`	用访问令牌（`token_type=access`）尝试刷新
`ErrRateLimitExceeded`	超出限流阈值

Revoke

func (p *Processor) Revoke(tokenString string) error

通过验证签名并提取令牌 ID（jti）将令牌加入黑名单。仅持有有效签名的令牌可被吊销，防止恶意调用者将任意令牌 ID 加入黑名单。

TTL 行为

令牌的 exp 决定黑名单条目的 TTL
无 exp 的令牌默认 7 天 TTL
TTL 上限 30 天，防止伪造的超长 exp 锁定内存（DoS 防护）
已过期的令牌仍可吊销；条目会由黑名单自动清理

参数

参数	类型	说明
`tokenString`	`string`	要吊销的令牌

返回值

返回	类型	说明
`err`	`error`	吊销失败时返回错误

错误

错误	触发条件
`ErrProcessorClosed`	Processor 已关闭
`ErrEmptyToken`	令牌为空
`ErrBlacklistNotConfigured`	黑名单未配置
`ErrInvalidToken`	签名无效或令牌格式错误
`ErrTokenInvalidIssuer`	签发者不匹配
`ErrTokenInvalidAudience`	受众不匹配
`ErrTokenMissingID`	令牌缺少 `jti` 字段

IsRevoked

func (p *Processor) IsRevoked(tokenString string) (bool, error)

检查令牌是否已被吊销。通过验证签名后查找令牌的 jti 在黑名单中的状态。当黑名单未配置时返回 false 和 nil 错误。

参数

参数	类型	说明
`tokenString`	`string`	JWT 字符串

返回值

返回	类型	说明
`revoked`	`bool`	是否已吊销
`err`	`error`	查询失败时返回错误

错误

错误	触发条件
`ErrProcessorClosed`	Processor 已关闭
`ErrEmptyToken`	令牌为空
`ErrInvalidToken`	签名无效或令牌格式错误
`ErrTokenInvalidIssuer`	签发者不匹配
`ErrTokenInvalidAudience`	受众不匹配
`ErrTokenMissingID`	令牌缺少 `jti` 字段

ParseUnverified

func (p *Processor) ParseUnverified(tokenString string, claims any) error

解析令牌但不验证签名。适用于提取 Claims 信息但不需要信任的场景。

警告

返回的 Claims 未经验证，不可信任。仅用于调试或日志场景。

参数

参数	类型	说明
`tokenString`	`string`	JWT 字符串
`claims`	`any`	目标 Claims 指针

返回值

返回	类型	说明
`err`	`error`	解析失败时返回错误

错误

错误	触发条件
`ErrProcessorClosed`	Processor 已关闭
`ErrEmptyToken`	令牌为空
包装错误	令牌格式错误时返回包装的解析错误（非哨兵错误，无法用 `errors.Is` 匹配）

Close

func (p *Processor) Close() error

释放资源并安全清除密钥。可多次调用，后续调用返回 ErrProcessorClosed。

返回值

返回	类型	说明
`err`	`error`	关闭失败时返回错误

IsClosed

func (p *Processor) IsClosed() bool

检查 Processor 是否已关闭。

返回值

返回	类型	说明
`closed`	`bool`	是否已关闭

Processor ​

Create ​

参数 ​

返回值 ​

错误 ​

示例 ​

Validate ​

参数 ​

返回值 ​

错误 ​

示例 ​

CreateRefresh ​

参数 ​

返回值 ​

错误 ​

Refresh ​

参数 ​

返回值 ​

错误 ​

ValidateInto ​

参数 ​

返回值 ​

示例 ​

错误 ​

RefreshInto ​

参数 ​

返回值 ​

错误 ​

Revoke ​

参数 ​

返回值 ​

错误 ​

IsRevoked ​

参数 ​

返回值 ​

错误 ​

ParseUnverified ​

参数 ​

返回值 ​

错误 ​

Close ​

返回值 ​

IsClosed ​

返回值 ​

Processor

Create

参数

返回值

错误

示例

Validate

参数

返回值

错误

示例

CreateRefresh

参数

返回值

错误

Refresh

参数

返回值

错误

ValidateInto

参数

返回值

示例

错误

RefreshInto

参数

返回值

错误

Revoke

参数

返回值

错误

IsRevoked

参数

返回值

错误

ParseUnverified

参数

返回值

错误

Close

返回值

IsClosed

返回值