ThinkPHP8 参数校验实战:用 Attribute 注解 + 中间件替代手写 validate

2026-11-21 0 372

项目做到中期,控制器方法开始长这个样子:

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 做跳转和补全。

ThinkPHP8 参数校验实战:用 Attribute 注解 + 中间件替代手写 validate
收藏 (0) 打赏

感谢您的支持,我会继续努力的!

打开微信/支付宝扫一扫,即可进行扫码打赏哦,分享从这里开始,精彩与您同在
点赞 (0)

版权声明:
本站资源有的来自互联网收集整理,本站纯免费分享提供学习使用,如果侵犯了您的合法权益,请发送邮件1506151422@qq.com联系,将会及时下架删除。
本站资源仅供研究、学习交流之用,免费开源项目不代表完全可商用,若商业用途请先咨询开发企业能否商用,否则产生的一切后果将由下载用户自行承担。
原创板块未经允许不得转载,否则将追究法律责任。

淘吗网 thinkphp ThinkPHP8 参数校验实战:用 Attribute 注解 + 中间件替代手写 validate https://www.taomawang.com/server/thinkphp/3033.html

常见问题

相关文章

猜你喜欢
发表评论
暂无评论
官方客服团队

为您解决烦忧 - 24小时在线 专业服务