JWTRefreshTokenBundle 2.0升级指南：新特性、Breaking Changes与迁移步骤

【免费下载链接】JWTRefreshTokenBundleImplements a Refresh Token system over Json Web Tokens in Symfony项目地址: https://gitcode.com/gh_mirrors/jw/JWTRefreshTokenBundle

JWTRefreshTokenBundle 2.0版本带来了多项重要更新，包括性能优化、API标准化和对Symfony新版本的支持。本文将详细介绍升级的核心变化、迁移步骤和最佳实践，帮助开发者快速完成从1.x到2.0的平稳过渡。

📋 最低系统要求

升级前请确保环境满足以下要求：

• PHP：8.2或更高版本（支持8.3/8.4）
• Symfony：6.4或7.2+（兼容8.0）
• 依赖组件：
  • doctrine/persistence ^3.1 || ^4.0
  • lexik/jwt-authentication-bundle ^2.15 || ^3.0

可通过composer.json文件查看完整依赖关系，确保项目框架版本符合要求后再进行升级。

✨ 核心新特性

1. 批量操作支持

新增两个关键接口方法，提升大量令牌处理效率：

• RefreshTokenRepositoryInterface::findInvalidBatch()：批量查询无效令牌
• RefreshTokenManagerInterface::revokeAllInvalidBatch()：批量吊销无效令牌

自定义仓库实现需添加这两个方法，优化定时清理任务性能。

2. 容器ID标准化

所有服务ID统一前缀为gesdinet_jwt_refresh_token，例如：

• 旧ID：gesdinet.jwtrefreshtoken.manager
• 新ID：gesdinet_jwt_refresh_token.manager

在配置文件和依赖注入中需同步更新引用。

3. 类型安全增强

• 所有方法添加参数和返回值类型提示
• 严格验证refresh_token_class配置实现RefreshTokenInterface

⚠️ Breaking Changes

1. 移除的核心类

• 移除Document/AbstractRefreshToken和Entity/AbstractRefreshToken，直接使用同命名空间下的RefreshToken类
• 移除Model\RefreshTokenManager，需直接实现RefreshTokenManagerInterface
• 移除Symfony 5.3及更早版本的认证支持类

2. 配置节点变更

3. 方法行为变更

• RefreshTokenAuthenticator::supports()仅检查请求路径是否匹配check_path配置
• AbstractRefreshToken::setRefreshToken()不再自动生成令牌，需手动传入
• RefreshTokenManagerInterface::create()移除，使用RefreshTokenGeneratorInterface替代

🚀 迁移步骤

1. 更新Composer依赖

composer require gesdinet/jwt-refresh-token-bundle:^2.0

2. 调整配置文件

config/packages/gesdinet_jwt_refresh_token.yaml：

gesdinet_jwt_refresh_token: refresh_token_class: App\Entity\RefreshToken # 必选配置 object_manager: doctrine.orm.entity_manager # 替代原entity_manager # 移除firewall、user_provider等已删除节点

3. 实体类更新

如果使用内置实体/文档类，直接替换父类引用：

// 旧代码 use Gesdinet\JWTRefreshTokenBundle\Entity\AbstractRefreshToken; class RefreshToken extends AbstractRefreshToken {} // 新代码 use Gesdinet\JWTRefreshTokenBundle\Entity\RefreshToken; class RefreshToken extends RefreshToken {} // 直接继承具体实现

4. 令牌生成逻辑迁移

将原Manager::create()替换为生成器：

// 旧代码 $refreshToken = $manager->create(); // 新代码 $refreshToken = new RefreshToken(); $refreshToken->setRefreshToken($generator->generate()); // 注入RefreshTokenGeneratorInterface

5. 清理废弃代码

• 移除对gesdinet.jwtrefreshtoken.object_manager.id参数的引用
• 认证失败处理器需实现新的接口方法
• 登出配置迁移至refresh_jwt认证器的invalidate_token_on_logout选项

🔍 常见问题解决

Q: 升级后出现"Class not found"错误？

A: 检查是否存在以下情况：

• 未更新容器服务ID（使用gesdinet_jwt_refresh_token前缀）
• 自定义实现类未添加新接口方法（如findInvalidBatch()）
• 遗留对已移除类的引用（如AbstractRefreshToken）

Q: 令牌生成失败怎么办？

A: 确保通过生成器接口创建令牌：

use Gesdinet\JWTRefreshTokenBundle\Generator\RefreshTokenGeneratorInterface; class AuthService { public function __construct(private RefreshTokenGeneratorInterface $generator) {} public function createToken() { $token = new RefreshToken(); $token->setRefreshToken($this->generator->generate()); // 设置其他属性... } }

📝 总结

JWTRefreshTokenBundle 2.0通过标准化接口、增强类型安全和添加批量操作，显著提升了在现代Symfony应用中的适用性。虽然迁移需要处理一些Breaking Changes，但遵循本文档的步骤可以最小化升级风险。建议先在测试环境验证，特别注意配置文件更新和自定义实现类的接口兼容性。

完整的变更日志可参考项目根目录下的UPGRADE-2.0.md文件，如有其他问题可查阅源码中的测试用例或提交issue获取支持。

【免费下载链接】JWTRefreshTokenBundleImplements a Refresh Token system over Json Web Tokens in Symfony项目地址: https://gitcode.com/gh_mirrors/jw/JWTRefreshTokenBundle