鉴权与拦截
鉴权与拦截并不意味着所有网站请求都必须经过同一段代码。更常见、也更容易维护的做法是:为一个业务模块定义公共 Base 控制器,让该模块下的所有控制器继承它。
例如后台管理接口都必须登录,可以建立 Admin\\Base,在它的 onRequest() 中统一鉴权。鉴权失败时先写入 401 响应,再 return false,框架就不会继续执行目标 Action。
本章最终实现三个接口。其中登录接口也继承管理员 Base,但通过 ignoreAction 明确跳过鉴权:
GET /admin/users 管理员用户列表,需要登录
GET /admin/dashboard 管理后台首页,需要登录
POST /admin/login 管理员登录,不需要登录
最终目录结构
需要新建四个控制器文件,并修改路由文件:
项目根目录/
└── App/
└── HttpController/
├── Router.php
└── Admin/
├── Base.php ← 管理员公共控制器
├── Auth.php ← login 免鉴权
├── User.php ← 继承 Base
└── Dashboard.php ← 继承 Base
第一步:定义管理员 Base 控制器
新建 App/HttpController/Admin/Base.php:
<?php
namespace App\HttpController\Admin;
use EasySwoole\Http\AbstractInterface\Controller;
abstract class Base extends Controller
{
/**
* 当前控制器中不需要登录的 Action。
* 默认没有免鉴权 Action,由具体子控制器按需声明。
*
* @var list<string>
*/
protected array $ignoreAction = [];
/**
* 当前请求对应的管理员 ID。
* Controller 对象按请求创建,因此这里可以保存本次请求的数据。
*/
protected ?int $adminId = null;
/**
* final 可以防止子控制器覆盖 onRequest() 后绕过鉴权。
*/
final protected function onRequest(?string $action): ?bool
{
// 登录、验证码等公开 Action 可以在子控制器中加入白名单。
if ($action !== null && in_array($action, $this->ignoreAction, true)) {
return true;
}
$authorization = $this->request()->getHeaderLine('Authorization');
// 入门示例使用固定 Token,生产项目应改为 AuthService 校验。
if (!hash_equals('Bearer demo-admin-token', $authorization)) {
$this->writeJson(401, null, '管理员未登录或登录已过期');
// 返回 false 后,User::index()、Dashboard::index() 等 Action
// 都不会再执行。
return false;
}
// 实际项目中,adminId 应来自 Session、JWT 或 Token 存储。
$this->adminId = 1001;
return true;
}
}
这里有四个关键点:
Base定义为abstract,它只用于继承,本身不是可访问的业务控制器。onRequest()会在目标 Action 之前执行,适合做登录、权限、限流等公共检查。- 失败时既要写出响应,也要
return false。只写 401 但仍返回true,目标 Action 还会继续执行并可能追加响应内容。 ignoreAction使用严格匹配;只有子控制器明确列出的 Action 才能绕过登录检查。
第二步:让管理员控制器继承 Base
新建 App/HttpController/Admin/User.php:
<?php
namespace App\HttpController\Admin;
class User extends Base
{
public function index(): void
{
$this->writeJson(200, [
'operatorId' => $this->adminId,
'users' => [
['id' => 1, 'name' => 'Alice'],
['id' => 2, 'name' => 'Bob'],
],
]);
}
}
新建 App/HttpController/Admin/Dashboard.php:
<?php
namespace App\HttpController\Admin;
class Dashboard extends Base
{
public function index(): void
{
$this->writeJson(200, [
'operatorId' => $this->adminId,
'onlineUsers' => 128,
]);
}
}
两个控制器都没有重复编写 Token 校验,但请求它们时都会先进入 Base::onRequest()。
第三步:为登录 Action 设置免鉴权
登录接口本身用于获取 Token,如果它也要求先携带 Token,就会形成无法登录的死循环。
新建 App/HttpController/Admin/Auth.php:
<?php
namespace App\HttpController\Admin;
class Auth extends Base
{
/**
* 这里只放当前 Auth 控制器中允许匿名访问的方法名。
* 方法名必须与路由 Handler 中的 Action 完全一致。
*
* @var list<string>
*/
protected array $ignoreAction = ['login'];
public function login(): void
{
$username = (string) $this->request()->getRequestParam('username');
$password = (string) $this->request()->getRequestParam('password');
// 仅用于演示流程。生产项目应查询管理员账号,
// 并使用 password_verify() 检查密码哈希。
if ($username !== 'admin' || $password !== 'demo-password') {
$this->writeJson(422, null, '账号或密码错误');
return;
}
$this->writeJson(200, [
'token' => 'demo-admin-token',
], '登录成功');
}
/**
* logout 没有加入 ignoreAction,所以仍然要求登录。
*/
public function logout(): void
{
// 实际项目应在服务端使 Session 或 Token 失效。
$this->writeJson(200, null, '退出成功');
}
}
当请求 /admin/login 时,框架传入的 $action 是 login:
Auth::$ignoreAction 中包含 login
↓
Base::onRequest('login') 返回 true
↓
执行 Auth::login()
当请求 logout 时,logout 不在白名单中,因此仍会继续执行 Token 校验。
第四步:注册路由
编辑 App/HttpController/Router.php,在 initialize() 中注册管理员路由:
<?php
namespace App\HttpController;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use FastRoute\RouteCollector;
class Router extends AbstractRouter
{
public function initialize(RouteCollector $routeCollector): void
{
$routeCollector->addGroup('/admin', function (RouteCollector $route): void {
$route->post('/login', '/Admin/Auth/login');
$route->post('/logout', '/Admin/Auth/logout');
$route->get('/users', '/Admin/User/index');
$route->get('/dashboard', '/Admin/Dashboard/index');
});
}
}
路由和控制器的对应关系:
GET /admin/users
↓ Router.php
/Admin/User/index
↓ 创建 App\HttpController\Admin\User
Base::onRequest()
├── false → 不执行 Action,直接返回鉴权失败响应
└── true → 执行 User::index()
第五步:验证登录与拦截效果
修改代码后 reload:
php easyswoole.php server reload
登录接口没有 Token 也可以访问:
curl -i -X POST http://127.0.0.1:9501/admin/login \
-d 'username=admin&password=demo-password'
预期返回:
{
"code": 200,
"result": {"token": "demo-admin-token"},
"msg": "登录成功"
}
如果访问没有加入 ignoreAction 的退出接口,仍然会被拦截:
curl -i -X POST http://127.0.0.1:9501/admin/logout
预期状态码为 401。
不携带 Token:
curl -i http://127.0.0.1:9501/admin/users
预期状态码为 401,Action 中的用户列表不会返回:
{
"code": 401,
"result": null,
"msg": "管理员未登录或登录已过期"
}
携带正确 Token:
curl -i http://127.0.0.1:9501/admin/users \
-H 'Authorization: Bearer demo-admin-token'
预期状态码为 200,并返回用户列表。另一个继承 Base 的接口也会自动受到保护:
curl -i http://127.0.0.1:9501/admin/dashboard \
-H 'Authorization: Bearer demo-admin-token'
return false 后还会执行什么
Controller 的实际执行顺序是:
onRequest()
├── 返回 false:跳过 Action
└── 返回其他值:继续执行 Action
↓
afterAction() 始终会在 finally 中执行
因此,return false 会阻止业务 Action,但不会阻止 afterAction()。如果 Base 中实现了请求日志或耗时统计,它在鉴权失败时仍然会执行:
protected function afterAction(?string $actionName): void
{
// 无论 onRequest 是否通过,这里都会执行。
// 可用于记录状态码、Action 名称和请求耗时。
}
生产项目不要使用固定 Token
固定 Token 只是为了让示例可以独立运行。实际项目应把解析和校验封装到 Service:
final protected function onRequest(?string $action): ?bool
{
if ($action !== null && in_array($action, $this->ignoreAction, true)) {
return true;
}
$token = $this->request()->getHeaderLine('Authorization');
$admin = AdminAuthService::getInstance()->authenticate($token);
if ($admin === null) {
$this->writeJson(401, null, '请先登录');
return false;
}
if (!$admin->canAccess($action)) {
$this->writeJson(403, null, '没有操作权限');
return false;
}
$this->adminId = $admin->getId();
return true;
}
- 401 表示没有有效身份。
- 403 表示已经识别身份,但没有当前操作权限。
- 当前管理员信息只能保存为本次请求的数据,不要写入静态属性或全局单例的可变属性,否则常驻 Worker 中可能发生请求串数据。
ignoreAction 应该定义在哪里
建议让 Base 提供空数组,然后由具体控制器声明自己的白名单:
// Admin/Base.php
protected array $ignoreAction = [];
// Admin/Auth.php
protected array $ignoreAction = ['login', 'captcha'];
不要直接在 Base 中写一个覆盖所有管理员控制器的巨大列表:
// 不推荐
protected array $ignoreAction = ['login', 'captcha', 'callback', 'index'];
因为白名单只保存 Action 名,不包含控制器名。如果 Base 全局放行 index,那么所有继承它的 index() 都可能绕过鉴权。让白名单跟着具体控制器,可以清楚看出哪个接口被公开。
对于更加严格的项目,也可以用“控制器类名 + Action 名”组成白名单,或创建单独的公开登录控制器。但无论采用哪种方案,都应默认要求鉴权,只显式放行少量入口。
哪些控制器不会被拦截
只有继承 App\\HttpController\\Admin\\Base 的控制器才会执行这里的鉴权。前台公开控制器可直接继承框架的 Controller,不会受到管理员规则影响:
use EasySwoole\Http\AbstractInterface\Controller;
class PublicArticle extends Controller
{
// 公开接口
}
这正是按业务模块建立 Base 控制器的意义:管理员、商户端、开放 API 可以分别拥有自己的公共拦截规则,而不是把全部逻辑堆到一个巨大的全局判断中。
常见错误
- 子控制器仍然直接继承
Controller,所以不会进入管理员 Base。 - 鉴权失败后忘记
return false,Action 继续执行。 - 只
return false却没有写响应,客户端收到空内容。 - 子类覆盖
onRequest()却没有调用父类,导致绕过鉴权;可像示例一样声明为final。 - 把
login错写为路由地址/admin/login;白名单匹配的是 Action 方法名,不是 URL。 - 在 Base 中放行过于常见的
index,意外让多个管理员控制器绕过鉴权。 - 把当前管理员保存在
static属性或常驻单例中,造成不同请求之间串用户。