lestrrat-go/jwx 库中 JWT 私有声明处理方式的演进

在 JWT 标准中，除了预定义的注册声明（如 iss、sub、exp 等），开发者还可以添加自定义的私有声明（Private Claims）。这些声明为 JWT 提供了扩展性，允许开发者传递业务相关的额外信息。在 lestrrat-go/jwx 这个 Go 语言 JWT 处理库的 v3 版本中，关于私有声明的处理方式发生了一些重要变化。

接口方法的移除

在 v3 版本之前，jwt.Token 接口提供了一个方便的 PrivateClaims() 方法，开发者可以直接调用此方法来获取所有的私有声明。然而在 v3 版本中，这个方法从接口中被移除了，虽然底层实现仍然存在。

这种设计变更反映了库作者对 API 设计理念的转变。移除 PrivateClaims() 方法的主要考虑是：

1. 避免提供两种访问私有声明的途径（通过 Keys() 和 PrivateClaims()）
2. 鼓励开发者明确知道他们需要哪些私有声明
3. 提高代码的可控性和可维护性

新的解决方案

为了弥补 PrivateClaims() 方法移除带来的不便，库作者引入了更灵活的 TokenFilter 机制。这个新方案提供了更精细的控制能力：

// 创建标准声明过滤器
filter := jwt.StandardClaimsFilter()

// 获取仅包含标准声明的 Token
stdClaimsOnly, _ := filter.Filter(token)

// 获取仅包含私有声明的 Token
privateClaimsOnly, _ := filter.Reject(token)

这种设计有几个显著优势：

1. 更明确的意图表达 - 开发者清楚地知道他们在过滤什么
2. 更灵活的过滤条件 - 可以轻松扩展自定义过滤逻辑
3. 更好的类型安全 - 过滤后的结果仍然是 Token 类型

实际应用示例

在实际开发中，处理私有声明的典型模式如下：

// 创建标准声明过滤器
filter := jwt.StandardClaimsFilter()

// 获取仅包含私有声明的 Token
tokenWithoutStdClaims, _ := filter.Reject(token)

// 将私有声明转换为 map
claims := make(map[string]interface{})
for _, key := range tokenWithoutStdClaims.Keys() {
    var value interface{}
    _ = tokenWithoutStdClaims.Get(key, &value)
    claims[key] = value
}

随着库的进一步发展，未来可能会提供更便捷的 AsMap() 方法，进一步简化这一过程。

设计理念的演进

这一变更反映了现代 API 设计的一些最佳实践：

1. 显式优于隐式 - 鼓励开发者明确知道他们在处理什么数据
2. 单一职责原则 - 每个方法/函数只做一件事
3. 可组合性 - 通过小型、专注的工具组合出复杂行为

对于从旧版本迁移的开发者，虽然需要调整代码，但新的设计提供了更好的长期可维护性和灵活性。理解这些变化背后的设计理念，有助于开发者更好地利用这个强大的 JWT 处理库。