告别“信息孤岛”：Laravel Passport JWT Token 的痛点
想象一下，你正在开发一个多租户 SaaS 平台，或者一个拥有复杂权限体系的应用。用户通过 Laravel Passport 成功认证后，获得了一个 JWT Token。当这个 Token 被发送到 API 端点时，你可能需要知道：
- 这个用户属于哪个租户？
- 他拥有哪些具体的权限？
- 他是否是管理员？
如果这些信息没有包含在 JWT Token 中，那么在每个需要这些信息的 API 请求中，你都不得不：
- 从 Token 中解析出用户 ID。
- 使用用户 ID 去数据库查询用户的详细信息、角色和权限。
- 根据查询结果进行授权判断。
这种模式在请求量大时，会显著增加数据库的压力和 API 的响应时间。更糟糕的是，它使得授权逻辑分散且重复，降低了代码的可维护性。我们真正需要的是一个“自给自足”的 JWT Token，它能携带所有必要的授权上下文，让 API 端点能够快速、高效地做出决策。
引入救星：corbosman/laravel-passport-claims
幸运的是，PHP 社区的强大之处就在于总有优秀的解决方案出现。corbosman/laravel-passport-claims 这个 Composer 包就是专为解决 Laravel Passport JWT Token 信息不足问题而生。它提供了一种优雅的方式，允许你将自定义数据（Claims）注入到 Passport 生成的 JWT Token 中。
这个包的核心思想是利用管道（Pipeline）机制，在 Token 生成的过程中，让你有机会插入自定义逻辑来添加 Claims。这就像 Laravel 的中间件一样，Token 会依次经过你定义的多个处理类，每个类都可以向 Token 添加额外的信息。
快速上手：安装与配置
首先，使用 Composer 安装这个包。它目前支持 Laravel 9 和 10：
composer require corbosman/laravel-passport-claims
安装完成后，你需要发布其配置文件，以便定义你希望添加到 Token 中的 Claims：
php artisan vendor:publish --provider="CorBosman\Passport\ServiceProvider"
这会在 config 目录下生成一个 passport-claims.php 文件。
添加自定义 Claims：让 Token 携带你的数据
现在，是时候创建你的自定义 Claim 类了。这个包提供了一个 Artisan 命令来帮助你快速生成：
php artisan claim:generate Claims/UserRoleClaim
这会在 app/Claims 目录下创建一个 UserRoleClaim.php 文件（如果你没有 Claims 目录，它会自动创建）。打开这个文件，你会看到类似这样的结构：
addClaim('my-custom-key', 'my-custom-value');
return $next($token);
}
}handle 方法接收一个 AccessToken 实例，它继承自 Laravel\Passport\Bridge\AccessToken，因此你可以访问到 Token 的各种信息，比如用户 ID ($token->getUserIdentifier())。这使得你可以根据用户 ID 查询数据库，并将用户的角色、权限等信息添加到 Token 中。
例如，我们来添加用户的邮箱和角色：
getUserIdentifier());
if ($user) {
$token->addClaim('email', $user->email);
$token->addClaim('roles', $user->roles()->pluck('name')->toArray()); // 假设用户有 roles 关联
$token->addClaim('tenant_id', $user->tenant_id); // 如果是多租户应用
}
return $next($token);
}
}添加完 Claim 类后，别忘了在 config/passport-claims.php 文件的 claims 数组中注册它：
[
App\Claims\UserInfoClaim::class,
// 如果有其他 Claims，也在这里添加
]
];现在，每当 Laravel Passport 生成一个新的 JWT Token 时，你的 UserInfoClaim 类就会被执行，并将用户的邮箱、角色和租户 ID 注入到 Token 中。
利用 Claims 进行授权：中间件的魔力
仅仅将 Claims 添加到 Token 中还不够，我们还需要利用它们进行授权。corbosman/laravel-passport-claims 提供了一个方便的路由中间件 claim，让你可以在路由级别检查 Token 中是否存在某个 Claim，甚至检查 Claim 的值是否符合预期。
首先，在 app/Http/Kernel.php 中注册这个中间件：
protected $routeMiddleware = [
'claim' => \CorBosman\Passport\Http\Middleware\CheckForClaim::class,
];然后，你就可以在路由中使用它了：
use Illuminate\Support\Facades\Route;
// 检查 Token 中是否存在 'roles' Claim
Route::middleware(['auth:api', 'claim:roles'])->get('/admin/dashboard', function () {
return '只有拥有角色的用户才能访问管理后台';
});
// 检查 'roles' Claim 中是否包含 'admin'
Route::middleware(['auth:api', 'claim:roles,admin'])->get('/super-admin/settings', function () {
return '只有管理员才能访问此设置';
});
// 检查 'tenant_id' Claim 是否为 1 或 2
Route::middleware(['auth:api', 'claim:tenant_id,1|2'])->get('/tenant-specific-data', function () {
return '只有租户1或租户2的用户才能访问此数据';
});通过这种方式，你的 API 端点可以非常高效地进行授权判断，无需额外的数据库查询，极大地提升了性能和安全性。
格式化器（Formatters）：解决兼容性问题
有时，你可能会遇到 JWT Token 中日期字段格式不兼容的问题（例如，某些库将时间戳存储为浮点数）。corbosman/laravel-passport-claims 也允许你配置自定义的格式化器来修改现有 Claims。
例如，如果你需要将浮点数时间戳转换回整数，可以在 config/passport-claims.php 中添加：
return [
'claims' => [
// ... 你的 Claims 类
],
'formatters' => [
\Lcobucci\JWT\Encoding\UnifyAudience::class,
\Lcobucci\JWT\Encoding\UnixTimestampDates::class, // 将浮点数时间戳转换为整数
]
];这确保了你的 JWT Token 在与其他 JWT 库交互时具有更好的兼容性。
总结与展望：让你的 API 飞起来！
通过 corbosman/laravel-passport-claims，我们成功地解决了 Laravel Passport JWT Token 无法携带自定义授权信息的问题。它的优势显而易见：
- 性能提升： 大幅减少了每次请求所需的数据库查询，降低了服务器负载，提高了 API 响应速度。
- 授权灵活性： 可以将任何自定义数据（角色、权限、租户ID、用户偏好等）嵌入 Token，实现更细粒度的授权控制。
- 代码整洁： 将授权上下文与认证过程解耦，使 API 端点的授权逻辑更加简洁明了。
- 微服务友好： 在微服务架构中，Token 携带的丰富信息可以减少服务间通信，提升整体效率。
现在，你的 Laravel API 不再需要为获取用户权限而反复查询数据库，只需解析 Token 即可快速做出授权决策。这不仅让你的代码更加优雅高效，也为构建高性能、高可用的 API 打下了坚实基础。如果你正在使用 Laravel Passport，并且渴望更强大的 JWT Token 功能，那么 corbosman/laravel-passport-claims 绝对值得你一试！
