Loco-RS项目中JWT Claims序列化问题的分析与改进

背景介绍

在基于Rust的Web框架Loco-RS中，JWT(JSON Web Token)的实现是认证系统的核心组件之一。JWT标准定义了一种紧凑且自包含的方式，用于在各方之间安全地传输信息作为JSON对象。这些信息可以被验证和信任，因为它们是数字签名的。

问题发现

在Loco-RS的当前实现中，开发者发现JWT的claims(声明)序列化方式存在一个设计问题。当开发者尝试添加自定义claims时，这些claims会被嵌套在一个名为"claims"的字段中，而不是直接与标准claims(如"pid"和"exp")平级。

例如，当开发者想要添加一个包含用户角色的claims时，期望的JWT payload结构应该是：

{
  "pid": "PID",
  "exp": 1736099338,
  "roles": ["admin", "non-admin"]
}

但实际得到的却是：

{
  "pid": "PID",
  "exp": 1736099338,
  "claims": {
    "roles": ["admin", "non-admin"]
  }
}

技术分析

这个问题源于Loco-RS中UserClaims结构体的定义方式：

#[derive(Debug, Serialize, Deserialize)]
pub struct UserClaims {
    pub pid: String,
    exp: u64,
    pub claims: Option<Value>,
}

这里的claims字段被定义为一个可选的serde_json::Value类型，导致在序列化时，所有自定义claims都会被包装在这个字段下。

解决方案探讨

方案一：使用#[serde(flatten)]属性

最初的建议是使用Serde的flatten属性：

#[derive(Debug, Serialize, Deserialize)]
pub struct UserClaims {
    pub pid: String,
    exp: u64,
    #[serde(flatten)]
    pub claims: Option<Value>,
}

这个方案虽然简单，但存在潜在问题：当Value不是对象类型(如整数、字符串等)时，会导致运行时错误。

方案二：使用HashMap替代Value

更健壮的解决方案是使用HashMap<String, Value>：

#[derive(Debug, Serialize, Deserialize)]
pub struct UserClaims {
    pub pid: String,
    exp: u64,
    #[serde(default, flatten)]
    pub claims: HashMap<String,Value>,
}

这个方案的优势在于：

1. 强制要求claims必须是键值对形式，符合JWT规范
2. 使用default属性确保即使没有提供claims也能正常工作
3. 类型安全，避免了非对象类型的Value导致的错误

实现考量

采用第二种方案需要考虑以下因素：

1. 向后兼容性：这是一个破坏性变更，需要更新所有使用此功能的代码
2. 错误处理：需要明确处理claims转换失败的情况
3. 性能影响：HashMap的使用可能会带来轻微的性能开销，但在大多数场景下可以忽略

最佳实践建议

在实际开发中，建议：

1. 为自定义claims定义明确的类型，而不是直接使用Value
2. 在转换时进行严格的类型检查
3. 考虑添加claims验证机制，确保它们符合应用需求

结论

通过将UserClaims结构体中的claims字段改为使用HashMap<String, Value>并结合#[serde(flatten)]属性，可以更优雅地实现JWT claims的序列化，使其符合标准实践并提高类型安全性。这一改进将使Loco-RS的JWT实现更加符合开发者预期，同时保持灵活性和健壮性。