项目做到中期,控制器方法开始长这个样子:
public function save()
{
$data = $this->request->post();
$validate = new ArticleValidate();
if (!$validate->scene('save')->batch(true)->check($data)) {
return json(['code' => 422, 'msg' => $validate->getError()]);
}
// 下面才是业务
}
一两个接口还好,一个项目几十个接口都抄一遍 new / scene / check / json,除了啰嗦,还容易出现错误码格式不统一、某个接口忘了加 batch 之类的问题。
ThinkPHP 8 最低要求 PHP 8.0,这意味着 #[Attribute] 可以放心用——TP8 自己的注解路由就是靠它实现的。这篇的做法是把参数校验整个挪到中间件里,控制器方法上只留一行注解。
先看最终效果
#[Validate(ArticleValidate::class, 'list')]
public function index()
{
// 只写业务
}
请求进来如果校验不通过,中间件直接返回 422,控制器方法根本不会执行。下面开始动手。
目录与文件规划
app/
├── common/
│ └── attribute/
│ └── Validate.php # 注解类
├── middleware/
│ └── ParamValidate.php # 校验中间件
├── validate/
│ └── ArticleValidate.php # 验证器
└── controller/
└── Article.php
app/middleware.php # 注册中间件
第一步:定义注解类
新建 app/common/attribute/Validate.php:
<?php
declare(strict_types=1);
namespace appcommonattribute;
use Attribute;
#[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
final class Validate
{
/**
* @param string $validate 验证器类名
* @param string $scene 验证场景,空字符串表示不切换场景
*/
public function __construct(
public string $validate,
public string $scene = ''
) {
}
}
这里有两个点值得说明:
TARGET_METHOD:注解只能标注在方法上。如果想做成“整个控制器统一校验”,得加上TARGET_CLASS,本文场景用不到。IS_REPEATABLE:允许同一个方法标注多个#[Validate]。比如一个接口既要校验 query 又要校验 body,写两个注解即可,中间件会按顺序逐个执行。不加这个标志,重复标注会直接抛异常。
构造器属性提升(public string $validate)是 PHP 8.0 就有的语法,TP8 的环境完全支持。
第二步:写验证器
验证器依然用 thinkValidate 那一套,规则和场景都定义在这里,中间件和控制器都不用关心细节。
app/validate/ArticleValidate.php:
<?php
declare(strict_types=1);
namespace appvalidate;
use thinkValidate;
class ArticleValidate extends Validate
{
protected $rule = [
'page' => 'integer|between:1,1000',
'page_size' => 'integer|between:1,50',
'keyword' => 'max:32',
'id' => 'require|integer|gt:0',
'title' => 'require|length:2,80',
'content' => 'require|min:10',
'status' => 'require|in:0,1',
];
protected $message = [
'page.integer' => '页码必须是整数',
'page.between' => '页码范围 1-1000',
'page_size.between' => '每页最多取 50 条',
'keyword.max' => '搜索词不能超过 32 个字符',
'id.require' => '缺少文章 ID',
'id.gt' => '文章 ID 不合法',
'title.require' => '标题不能为空',
'title.length' => '标题长度需在 2-80 字之间',
'content.require' => '正文不能为空',
'content.min' => '正文至少 10 个字',
'status.require' => '缺少状态值',
'status.in' => '状态值只能是 0 或 1',
];
protected $scene = [
'list' => ['page', 'page_size', 'keyword'],
'detail' => ['id'],
'save' => ['title', 'content', 'status'],
];
}
注意 page、page_size、keyword 都没有加 require。think-validate 对非 require 字段的处理方式是:数据里不存在这个 key(或值为 null、空字符串)时,直接跳过后面的规则。所以列表接口不传 page 不会报错,只有传了 page=0 才会被 between:1,1000 拦住。这个特性写分页接口时特别省事,不用给每个可选字段补默认值。
第三步:中间件里读注解
核心只有三件事:拿到当前请求实际要执行的「控制器类 + 方法名」,用反射读方法上的 #[Validate],校验不通过就短路返回。
app/middleware/ParamValidate.php:
<?php
declare(strict_types=1);
namespace appmiddleware;
use appcommonattributeValidate as ValidateAttribute;
use Closure;
use thinkApp;
use thinkRequest;
use thinkResponse;
use thinkValidate as ThinkValidate;
class ParamValidate
{
protected App $app;
public function __construct(App $app)
{
$this->app = $app;
}
public function handle(Request $request, Closure $next): Response
{
$target = $this->resolveAction($request);
// 闭包路由、或者方法不存在,直接放行
if ($target === null) {
return $next($request);
}
[$class, $action] = $target;
$reflection = new ReflectionMethod($class, $action);
foreach ($reflection->getAttributes(ValidateAttribute::class) as $attribute) {
/** @var ValidateAttribute $config */
$config = $attribute->newInstance();
/** @var ThinkValidate $validate */
$validate = $this->app->make($config->validate);
if ($config->scene !== '') {
$validate->scene($config->scene);
}
$validate->batch(true);
if (!$validate->check($request->param())) {
return json([
'code' => 422,
'msg' => $this->normalizeError($validate->getError()),
], 422);
}
}
return $next($request);
}
/**
* 拿到当前请求实际要执行的控制器和方法
*/
protected function resolveAction(Request $request): ?array
{
$controller = $request->controller();
$action = $request->action();
if (empty($controller) || empty($action)) {
return null;
}
// controller() 在不同应用模式下返回的可能是短名(Article),
// 也可能是带命名空间的全名(appcontrollerArticle),两种都兼容
if (!class_exists($controller)) {
$controller = $this->app->getNamespace() . 'controller\' . $controller;
}
if (!class_exists($controller) || !method_exists($controller, $action)) {
return null;
}
return [$controller, $action];
}
/**
* batch 模式下 getError() 返回数组,统一压成一条字符串
*/
protected function normalizeError($error): string
{
if (is_array($error)) {
return implode(';', array_values(array_unique($error)));
}
return (string) $error;
}
}
几处实现细节解释一下:
用 $this->app->make() 而不是 new。 这样验证器构造函数里如果声明了依赖(比如注入一个字典服务),容器能自动解析;验证器内部也能直接使用 $this->app。
开启 batch(true)。 目的是把所有错误一次性返回,前端可以同时标红多个字段。配合 normalizeError() 把数组拼成一条,前端拿到的仍然是 msg 字符串,展示层不用额外处理。
校验数据源统一用 $request->param()。 它是路由参数 + GET + POST(含 JSON 请求体)的合集,所以 read() 这种把 ID 写在路由里的接口也能用同一套校验,不需要在中间件里额外区分参数来源。
第四步:注册中间件
单应用项目直接在 app/middleware.php 里加一行:
<?php
return [
// 其他中间件...
appmiddlewareParamValidate::class,
];
多应用项目别塞进全局,放到应用自己的 app/admin/middleware.php,或者挂到路由分组上:
Route::group('api', function () {
Route::get('article', 'Article/index');
Route::get('article/:id', 'Article/read');
Route::post('article', 'Article/save');
})->middleware(appmiddlewareParamValidate::class);
顺序上一定要留意:鉴权中间件必须排在它前面。否则一个没登录的请求会先跑一遍参数校验,返回 422 而不是 401,接口语义就乱了。
第五步:控制器接线
app/controller/Article.php:
<?php
declare(strict_types=1);
namespace appcontroller;
use appcommonattributeValidate;
use appmodelArticle as ArticleModel;
use appvalidateArticleValidate;
use thinkresponseJson;
class Article extends Base
{
#[Validate(ArticleValidate::class, 'list')]
public function index(): Json
{
$page = (int) $this->request->param('page', 1);
$pageSize = (int) $this->request->param('page_size', 10);
$keyword = (string) $this->request->param('keyword', '');
$query = ArticleModel::where('status', 1);
if ($keyword !== '') {
$query->whereLike('title', '%' . $keyword . '%');
}
return json($query->order('id', 'desc')->paginate([
'list_rows' => $pageSize,
'page' => $page,
]));
}
#[Validate(ArticleValidate::class, 'detail')]
public function read(): Json
{
$id = (int) $this->request->param('id');
$article = ArticleModel::find($id);
if (is_null($article)) {
return json(['code' => 404, 'msg' => '文章不存在'], 404);
}
return json($article);
}
#[Validate(ArticleValidate::class, 'save')]
public function save(): Json
{
$data = $this->request->only(['title', 'content', 'status']);
$article = ArticleModel::create($data);
return json(['code' => 0, 'msg' => 'ok', 'data' => ['id' => $article->id]]);
}
}
read() 方法里没写 $id 参数——路由变量早就合并进 param() 了,校验器和控制器从同一个数据源取值,不会出现“中间件校验的是 GET 参数、控制器取的是路由参数”这种对不上的情况。
跑起来看看实际返回
# 正常列表请求
curl "http://127.0.0.1:8000/api/article?page=2&page_size=20"
# 页码越界
curl "http://127.0.0.1:8000/api/article?page=0"
# {"code":422,"msg":"页码范围 1-1000"}
# 同时违反两条规则
curl "http://127.0.0.1:8000/api/article?page=0&page_size=999"
# {"code":422,"msg":"页码范围 1-1000;每页最多取 50 条"}
# 路由参数里的 ID 非数字
curl "http://127.0.0.1:8000/api/article/abc"
# {"code":422,"msg":"文章 ID 不合法"}
上面这些请求都不会到达控制器方法,业务代码完全没有执行,也就不会出现“校验没通过但数据已经写进库”这类事故。
几个容易踩的地方
1. $request->controller() 的返回值不一定带命名空间
单应用和多应用的解析路径不一样,有的场景拿到的是 Article,有的拿到的是 appcontrollerArticle。中间件里的 class_exists() 判断就是给这个兜底的。别直接拿返回值去 new ReflectionMethod(),不然换个应用模式就报“类不存在”。
2. 闭包路由拿不到方法名
Route::get('ping', function () { return 'pong'; }) 这种没有控制器和操作名,controller() 与 action() 都是空字符串,resolveAction() 返回 null,中间件放行。这是预期行为,不要在这里抛异常。
3. batch(true) 下 getError() 返回数组
这是最容易被忽略的一处。不加 normalizeError(),返回给前端的 msg 就是一个 JSON 数组,前端直接渲染会变成 [object Object],排查起来一头雾水。
4. 校验不会帮你过滤字段
$validate->check() 只做判断,不会删除数据里多出来的字段。save() 里该用 $this->request->only([...]) 还是得用。别以为校验通过了就能直接 create($request->post())——那等于给用户开了个批量赋值的后门,攻击者可以顺手把 is_admin 也一起提交上来。
5. 反射有开销,但可以缓存
每个请求会反射一次控制器方法。如果接口 QPS 很高、嫌 new ReflectionMethod() 慢,可以在中间件里加一层静态缓存:
protected static array $cache = [];
$key = $class . '@' . $action;
$configs = self::$cache[$key] ??= array_map(
fn ($attribute) => $attribute->newInstance(),
$reflection->getAttributes(ValidateAttribute::class)
);
注意缓存要存 newInstance() 之后的结果。getAttributes() 返回的是 ReflectionAttribute 对象,本身很轻量,把它缓存起来意义不大,真正需要复用是注解实例化后的配置对象。
顺着这个思路能扩展什么
#[Validate] 这套模式并不只能做校验。同一个中间件稍微改改,就能在注解里带更多信息,比如:
#[Validate(ArticleValidate::class, 'save')]
#[Serialize(name: 'article', only: ['id', 'title', 'created_at'])]
public function save() { ... }
一个注解管入参校验,一个注解管响应字段裁剪,控制器里始终只有两三行业务代码。TP8 的 #[Attribute] 支持命名参数,读起来比一长串链式配置直观得多,也方便 IDE 做跳转和补全。

