Lcobucci/JWT 中 Token\Builder 类的只读性改进分析

在 PHP 生态中，Lcobucci/JWT 是一个广泛使用的 JSON Web Token 实现库。最近开发团队发现其核心组件 Token\Builder 存在一个值得关注的设计问题：虽然类被标记为 readonly，但实际实现并未真正达到只读要求。

问题本质

PHP 的 readonly 修饰符要求类的所有属性必须：

1. 在构造函数中一次性初始化
2. 后续不允许任何修改

当前 Token\Builder 的实现存在以下矛盾：

• 类被标记为 readonly 表明设计意图是不可变
• 但实际通过公共方法允许属性修改，违反了只读原则

技术背景

在 PHP 8.2 引入的 readonly 类特性中，编译器会强制确保：

• 所有属性必须在构造时初始化
• 禁止任何形式的后续修改
• 提供编译期的安全性保证

解决方案

开发团队提出了一个兼顾安全性和向后兼容性的改进方案：

1. 引入静态工厂方法：

   • 新增 public static function new() 作为唯一构造入口
   • 将原构造函数改为 private 访问权限

2. 强化只读性：

   • 确保所有属性在构造阶段完成初始化
   • 通过工厂方法实施必要的参数校验

3. 保持API兼容：

   • 对外接口保持不变
   • 内部实现更符合不可变对象的设计原则

实现意义

这种改进带来了多重好处：

1. 更强的类型安全：

   • 编译器可以验证真正的不可变性
   • 消除运行时的意外修改风险

2. 更清晰的意图表达：

   • 明确传达类的不可变设计
   • 避免误用导致的潜在问题

3. 保持灵活性：

   • 通过工厂方法保留必要的参数校验
   • 不影响现有代码的使用方式

开发者建议

对于使用该库的开发者：

1. 升级注意事项：

   • 此修改属于不兼容变更
   • 需要检查自定义 Builder 扩展的实现

2. 最佳实践：

   • 优先使用提供的工厂方法
   • 避免依赖可能变化的内部实现

3. 设计启示：

   • 在需要不可变对象时，确保实现与声明一致
   • 合理使用工厂方法控制对象创建

这个改进体现了 Lcobucci/JWT 团队对代码质量的持续追求，也为其他 PHP 项目提供了处理类似问题的参考方案。