2018/10/4：

• 主要更新了中间件的区别那一部分，推荐使用 jwt.auth 中间件，虽然官网用的是 auth:api ，但是 jwt.auth 有着更加丰富的返回信息。

tymon/jwt-auth 扩展是 Laravel 下能够很方便的实现 JWT token 的一个扩展，使用和配置都很简单，但是网上的文档新版本的、旧版本的掺杂在一起，看起来十分混乱，因此我仔细比对源码整理了一个比较完整的安装文档：JWT 完整使用详解 。

看源码的过程中对这个扩展和 Laravel 的一些实现也有了比较深入的理解，记录如下。

参考资料

• Laravel 认证原理及完全自定义认证

Tips：最好打开框架和扩展中的源代码放一边参考，这样更利于理解，每个文件的路径和命名空间基本一致。

一、看守器

1. 契约

看守器 Guard 是一组契约（不懂的话就看成接口吧），定义了一些认证和登录的常用方法。

Illuminate\Contracts\Auth\Guard

这个看守器定契约义了如下方法，而 JWT 的看守器便是实现了这个接口，所以 JWT 的看守器就会具有这些方法，当然 JWT 的看守器还并不止这些方法，这个后面再仔细说。

// 判断当前用户是否登录
public function check();
// 判断当前用户是否是游客（未登录）
public function guest();
// 获取当前认证的用户
public function user();
// 获取当前认证用户的 id，严格来说不一定是 id，应该是上个模型中定义的唯一的字段名
public function id();
// 根据提供的消息认证用户
public function validate(array $credentials = []);
// 设置当前用户
public function setUser(Authenticatable $user);

Illuminate\Contracts\Auth\StatefulGuard

StatefulGuard 接口继承自 Guard 接口，并添加了一些新的有状态的方法。

看到 attempt 方法，可能有人就会觉得 JWT 的看守器似乎好像有理由是由这个继承而来，然后代码告诉我们，并非如此。

// 尝试根据提供的凭证验证用户是否合法
public function attempt(array $credentials = [], $remember = false);
// 一次性登录，不记录session or cookie
public function once(array $credentials = []);
// 登录用户，通常在验证成功后记录 session 和 cookie 
public function login(Authenticatable $user, $remember = false);
// 使用用户 id 登录
public function loginUsingId($id, $remember = false);
// 使用用户 ID 登录，但是不记录 session 和 cookie
public function onceUsingId($id);
// 通过 cookie 中的 remember token 自动登录
public function viaRemember();
// 登出
public function logout();

2. 对契约的实现

有了契约之后就要实现契约了，Laravel 框架自己针对上述契约实现了三个看守器类。

Illuminate\Auth\RequestGuard

实现了 Guard ，这里面的方法非常简单，大概就契约里约定的那么多，而且有一部分复用 GuardHelpers 这个 trait 来实现的。

Illuminate\Auth\SessionGuard

实现了 StatefulGuard，是 Laravel web 认证默认的 guard，定义了完整的 session 方式登录实现。

Illuminate\Auth\TokenGuard

实现了 Guard，适用于无状态 api 认证，通过 token 认证。但这里面实现的方法也挺少的，你可以根据这个实现一个简单的 token 认证。

Tymon\JWTAuth\JWTGuard

然后主角登场了，JWTGuard 实现了 Guard，和上面的三个实现是同级的，你可以理解为，官方的 TokenGuard 功能太简单，这个扩展写了一个比 TokenGuard 功能更加丰富的 Guard。

3. Gurad 的使用

好，我们现在已经知道 Guard 是什么一个东西已经它的实现了，那怎么使用呢？打开下面文件：

/config/auth.php

// 这里是指定默认的看守器
// web 的意思取下面 guards 数组 key 为 web 的那个
// passwords 是重置密码相关，暂时不懂什么意思
'defaults' => [
    'guard' => 'web',
    'passwords' => 'users',
],

// 这里定义可以用的 guard
// driver 指的就是上面的对 Guard 契约的具体实现那个类了
// users 是下面 providers 数组 key 为 users 的那个
'guards' => [
    'web' => [
        'driver' => 'session',    // SessionGuard 实现
        'provider' => 'users',    
    ],

    'api' => [
        'driver' => 'jwt',  // JWTGuard 实现，源码中为 token，我这改成 jwt 了
        'provider' => 'users',
    ],
],

// 这个的作用是指定认证所需的 user 来源的数据表
'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => App\User::class,
    ],

    // 'users' => [
    //     'driver' => 'database',
    //     'table' => 'users',
    // ],
],

通过以上你就知道了：

1. 认证用的那些方法是通过实现了 Guard 契约，契约保证了框架与扩展之间的低耦合性，为什么这样可以低耦合，后面中间件和辅助函数会具体介绍
2. JWT 的 JWTGuard 实现了 Guard 契约
3. 定义的 Guard 如何具体使用

二、中间件

看 JWT 的文档，里面定义的 AuthController 方法使用的是 auth:api 中间件，而 JWT 还提供了 jwt.auth 和 jwt.refresh 中间件，那么这些中间件有什么不同又是如何起作用的呢？

1. 定义

1.1 框架的中间件

app\Http\Kernel.php

这个文件中定义了框架自带的中间件：

protected $routeMiddleware = [
        'auth' => \Illuminate\Auth\Middleware\Authenticate::class,
        'auth.basic' => \Illuminate\Auth\Middleware\AuthenticateWithBasicAuth::class,
        'bindings' => \Illuminate\Routing\Middleware\SubstituteBindings::class,
        'cache.headers' => \Illuminate\Http\Middleware\SetCacheHeaders::class,
        'can' => \Illuminate\Auth\Middleware\Authorize::class,
        'guest' => \App\Http\Middleware\RedirectIfAuthenticated::class,
        'signed' => \Illuminate\Routing\Middleware\ValidateSignature::class,
        'throttle' => \Illuminate\Routing\Middleware\ThrottleRequests::class,
];

auth:api

可以发现 auth:api 使用的就是第一个中间件，而后面 :api 是路由参数，指定了要使用哪个看守器，可以看到下面 api 对应的看守器就是 jwt 的看守器。

并且你可以直接使用 auth ，这样就相当于使用 defaults 中指定的看守器，即 session。

Lumen 默认用的就是 api 那个，所以你直接用 auth 作为 api 路由的中间件完全没问题

Laravel 中指定了两个看守器，而且默认的并不是 api，所以你必须得用 auth:api 作为路由的中间件

功能是检查 token 的有效性，决定是否放行。

/config/auth.php

'defaults' => [
    'guard' => 'web',
    'passwords' => 'users',
],

'guards' => [
    'web' => [
        'driver' => 'session',    // SessionGuard 实现
        'provider' => 'users',    
    ],

    'api' => [
        'driver' => 'jwt',  // JWTGuard 实现，源码中为 token，我这改成 jwt 了
        'provider' => 'users',
    ],
]

1.2 jwt-auth 的中间件

tymon\jwt-auth\src\Providers\AbstractServiceProvider.php

protected $middlewareAliases = [
    'jwt.auth' => Authenticate::class,
    'jwt.check' => Check::class,
    'jwt.refresh' => RefreshToken::class,
    'jwt.renew' => AuthenticateAndRenew::class,
];

这个文件中定义了 jwt-auth 插件的中间件，第一二个功能一样，只是第二个不会主动抛出错误，第三四个功能一样。

jwt.auth

这个和上面的功能完全一致，至于有什么区别后面会具体解释。

jwt.refresh

这个出来检验 token 的有效性并决定如何放行外，还会在返回的 header 头上加入新的 token，达到每次请求都换取新 token 的效果。

2. 使用

使用就不多说了，官方文档介绍的很详细了。

$this->middleware('auth:api', ['except' => ['login']]);

3. 区别

接下来就探讨一下，这三个中间件有什么区别。

3.1 jwt.refresh 和 jwt.auth

这个的区别就是前者会在响应的 header 头中增加刷新的新 token。

3.2 jwt.auth 和 auth:api（auth）

这两个功能完全一致，只是调用链有所差别，而这个差别正好可以体现上面提到的低耦合性。

auth:api（auth）

Illuminate\Auth\Middleware\Authenticate

use Illuminate\Contracts\Auth\Factory as Auth;

public function __construct(Auth $auth)
{
    $this->auth = $auth;
}

public function handle($request, Closure $next, ...$guards)
{
    $this->authenticate($guards);

    return $next($request);
}

protected function authenticate(array $guards)
{
    if (empty($guards)) {
        return $this->auth->authenticate();
    }

    foreach ($guards as $guard) {
        if ($this->auth->guard($guard)->check()) {
            return $this->auth->shouldUse($guard);
        }
    }

    throw new AuthenticationException('Unauthenticated.', $guards);
}

Illuminate\auth\GuardHelpers.php

public function check()
{
    return ! is_null($this->user());
}

public function authenticate()
{
    if (! is_null($user = $this->user())) {
        return $user;
    }

    throw new AuthenticationException;
}

可以看到：

1. 路由参数作为参数传入 handle 方法，然后调用下面的 authenticate 方法；
2. authenticate 根据所给的参数选择进行校验的 guard ，然后通过 guard 进行校验，如果校验不通过则统一抛出 AuthenticationException

jwt.auth

Tymon\JWTAuth\Middleware\Authenticate

public function handle($request, Closure $next)
{
    $this->authenticate($request);

    return $next($request);
}

Tymon\JWTAuth\Middleware\BaseMiddleware

public function authenticate(Request $request)
{
    $this->checkForToken($request);

    try {
        if (! $this->auth->parseToken()->authenticate()) {
            throw new UnauthorizedHttpException('jwt-auth', 'User not found');
        }
    } catch (JWTException $e) {
        throw new UnauthorizedHttpException('jwt-auth', $e->getMessage(), $e, $e->getCode());
    }
}

可以看到：

1. 路由参数作为参数传入 handle 方法，然后调用下面的 authenticate 方法；
2. authenticate 直接用自身逻辑进行校验，然后抛出错处，与前面不同的是，这里抛出的错误种类更加丰富，因此我推荐还是使用这个中间件比较好。、

三、辅助函数和 Facade

1. 辅助函数

辅助函数是 Laravel 提供的一系列函数，可以很方便的做到一些事情，这里要提到的是 auth()

使用这个函数报错的，是因为你用的是 Lumen ，而 Lumen 阉割了这个函数，你可以通过安装扩展补齐。

auth()

auth 函数返回一个 认证 实例。为了方便起见，你可以使用它来替代 Auth Facade：

$user = auth()->user();

如果需要，你可以指定你想要访问的认证实例：

$user = auth('admin')->user();

以上是官方文档对于此辅助函数的解释。

接下来我要一句话解释上面这个辅助函数，你可以仔细品味这句话直到理解为止：

auth() 返回的一个看守器实例，如上面的 SessionGuard 和 JWTGuard ，然后你就可以链式调用对于看守器提供的所有方法，此外这个函数的参数可以指定所要返回的看守器实例，否则返回默认的，例如 auth(‘api’)。

'guards' => [
    'web' => [
        'driver' => 'session',    // SessionGuard 实现
        'provider' => 'users',    
    ],

    'api' => [
        'driver' => 'jwt',  // JWTGuard 实现，源码中为 token，我这改成 jwt 了
        'provider' => 'users',
    ],
]

JWT 下的 auth()

安装 JWT 后，你可以在 auth() 后面调用 factory() 或 payload() 之类的来调用更多定义的方法。（看了源代码没看懂是怎么实现的，可能是 __call 魔术方法），可用的有下面这些：

auth()->factory()

auth()->blacklist()

auth()->manager()

auth()->payload()

使用示例：

$exp = auth()->payload()->get('exp');
$json = auth()->payload()->toJson();
$array = auth()->payload()->jsonSerialize();

更多的方法可以去源代码下看。

2. Facade

config/app.php

'aliases' => [
    ...
    'JWTAuth' => 'Tymon\JWTAuth\Facades\JWTAuth',
    'JWTFactory' => 'Tymon\JWTAuth\Facades\JWTFactory',
],

Facade 可以为你的编程带来一点便利，具体的使用我在 Laravel/Lumen教程4-JWT的基本使用 一文中有详细介绍，这里展示一个小的使用示例：

/**
 * Get the guard to be used during authentication.
 * 这个和方法和辅助函数 auth() 差不多，如果 Lumen 不想用插件补充 auth()，可以这么写
 *
 * @return \Illuminate\Contracts\Auth\Guard
 */
public function guard()
{
    return JWTAuth::guard();
}

此外 Auth:: 这个 Facade 也是返回一个看守器实例，当成辅助函数 auth 使用就好了。

本作品采用《CC 协议》，转载必须注明作者和本文链接