如何在 Laravel 中使用单一登录接口支持多个 Guards（认证守卫）

本文介绍在 Lara vel 中通过动态 guard 切换实现统一登录接口的方法，避免冗长的 if-else 或 switch-case，提升代码可维护性与扩展性。

但凡做过 Lara vel 多用户系统（比如管理员、商家、骑手、学生、教师……），就会遇到一个经典问题：不同角色往往对应不同的 Guard 和用户模型。如果每个角色都单独写一个登录接口，不仅代码重复得让人头疼，后续 Token 签发、失败响应、限流这些共性逻辑也得各自维护一遍——想想就累。

那么，有没有一种方式，让所有角色共用同一个登录入口，却又能自动切换到正确的 Guard 和模型？当然有。核心思路就一句话：基于请求参数动态解析 Guard 与模型，实现“单入口、多守卫”登录。

具体怎么做？来拆解几步：

• 约定请求字段：客户端在登录时带上一个 guard 标识，比如 guard=student，也可以从路由前缀或 Header 里取，怎么方便怎么来。
• 预定义 Guard 映射表：在配置或服务类里声明 Guard → Model → Provider 的对应关系，这样后续新增角色时，改映射表就够了，不用动业务代码。
• 复用 Auth::guard($guard)->attempt()：Lara vel 原生支持运行时指定 Guard，不需要手动实例化模型，一行代码搞定认证。
• 统一响应结构：不管哪个 Guard 登录成功，都返回标准化的 JSON（token、user info、expires_in 等），前端对接也省心。

下面是精简、安全、可复用的控制器示例，直接贴出来大家感受一下：

// app/Http/Controllers/Auth/LoginController.php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Validation\ValidationException;

class LoginController extends Controller
{
    // Guard 与模型/Provider 的映射（建议提取至 config/auth.php 或专用服务类）
    protected $guardMapping = [
        'admin'     => ['model' => \App\Models\Admin::class, 'provider' => 'admins'],
        'merchant'  => ['model' => \App\Models\Merchant::class, 'provider' => 'merchants'],
        'rider'     => ['model' => \App\Models\Rider::class, 'provider' => 'riders'],
        'student'   => ['model' => \App\Models\Student::class, 'provider' => 'students'],
        'teacher'   => ['model' => \App\Models\Teacher::class, 'provider' => 'teachers'],
    ];

    public function login(Request $request)
    {
        $request->validate([
            'guard' => ['required', 'string', 'in:'.implode(',', array_keys($this->guardMapping))],
            'email' => 'required|string|email',
            'password' => 'required|string|min:6',
        ]);

        $guard = $request->input('guard');
        $credentials = $request->only('email', 'password');

        // 尝试认证
        if (Auth::guard($guard)->attempt($credentials)) {
            $user = Auth::guard($guard)->user();
            $token = $user->createToken('API Token')->plainTextToken;

            return response()->json([
                'token' => $token,
                'user' => $user->only('id', 'name', 'email'),
                'guard' => $guard,
                'expires_in' => now()->addMinutes(60)->timestamp,
            ]);
        }

        throw ValidationException::withMessages([
            'email' => ['The provided credentials are incorrect.'],
        ]);
    }
}

当然，光有代码还不够，落地时得注意几个关键点：

• ✅ 每个 Guard 务必在 config/auth.php 中正确定义，并关联对应的 provider 和 model，否则 Lara vel 找不到认证源。
• ✅ 所有用户模型需要实现 HasApiTokens trait（用于 createToken()），这是 Sanctum 或 Passport 的基础。
• ⚠️ 登录方法里不要掺杂密码重置、权限校验这类逻辑，保持职责单一，后续才好维护。
• ? 建议配合 throttle:api 中间件防止暴力破解，安全第一。
• ? 如果需求更复杂——比如根据邮箱后缀自动推断 Guard——可以在验证前加一层智能路由逻辑，但要注意可测试性和透明性，别为了炫技把代码搞复杂了。

这个模式最大的好处是什么？彻底消除了 if-elseif-else 的嵌套地狱。后续新增角色（比如 parent、staff），只需要更新 $guardMapping 并在配置里加个新 Guard 就行，零侵入。真正做到了“一次封装，多点复用”——这才是工程实践里该有的样子。