Attribute 验证规则

EasySwoole HTTP Annotation 4.x 当前提供 61 个内置 Validator。它们都放在：

EasySwoole\HttpAnnotation\Validator

验证规则写在 Param 的 validate 数组中。一个参数可以组合多条规则，框架按顺序执行，遇到第一条失败规则时抛出 ParamValidateFail。

从一个完整例子开始

新建 App/HttpController/ValidationDemo.php，避免覆盖其他章节的控制器：

<?php

namespace App\HttpController;

use EasySwoole\HttpAnnotation\AnnotationController;
use EasySwoole\HttpAnnotation\Attributes\Api;
use EasySwoole\HttpAnnotation\Attributes\ApiGroup;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Enum\ContentType;
use EasySwoole\HttpAnnotation\Enum\HttpMethod;
use EasySwoole\HttpAnnotation\Enum\ParamFrom;
use EasySwoole\HttpAnnotation\Enum\ParamType;
use EasySwoole\HttpAnnotation\Exception\ParamValidateFail;
use EasySwoole\HttpAnnotation\Validator\BetweenMbLen;
use EasySwoole\HttpAnnotation\Validator\IsEmail;
use EasySwoole\HttpAnnotation\Validator\Min;
use EasySwoole\HttpAnnotation\Validator\NotEmpty;
use EasySwoole\HttpAnnotation\Validator\Required;

#[ApiGroup(groupName: 'ValidationDemo')]
class ValidationDemo extends AnnotationController
{
    #[Api(
        allowMethod: HttpMethod::POST,
        acceptContentType: ContentType::JSON,
        requestParam: [
            new Param(
                name: 'name',
                from: ParamFrom::JSON,
                validate: [
                    new Required(),
                    new NotEmpty(),
                    new BetweenMbLen(2, 20),
                ]
            ),
            new Param(
                name: 'email',
                from: ParamFrom::JSON,
                validate: [new Required(), new IsEmail()]
            ),
            new Param(
                name: 'age',
                from: ParamFrom::JSON,
                type: ParamType::INT,
                validate: [new Required(), new Min(18)]
            ),
        ]
    )]
    public function create(string $name, string $email, int $age): void
    {
        $this->writeJson(201, compact('name', 'email', 'age'));
    }

    protected function onException(\Throwable $throwable): void
    {
        if ($throwable instanceof ParamValidateFail) {
            $this->writeJson(422, null, $throwable->getMessage());
            return;
        }

        throw $throwable;
    }
}

在 App/HttpController/Router.php 中注册：

$routeCollector->post('/validation-demo', '/ValidationDemo/create');

验证成功：

curl -i -X POST http://127.0.0.1:9501/validation-demo \
  -H 'Content-Type: application/json' \
  -d '{"name":"张三","email":"zhangsan@example.com","age":20}'

验证失败：

curl -i -X POST http://127.0.0.1:9501/validation-demo \
  -H 'Content-Type: application/json' \
  -d '{"name":"张","email":"wrong","age":16}'

由于规则按声明顺序执行，第二次请求首先报告 name 长度错误；修正后才会继续遇到邮箱或年龄错误。

必填与可选规则

Required 和 NotEmpty 的区别

new Param('nickname', validate: [new Required()]);

客户端传入 nickname= 时，参数存在，所以 Required 可以通过。如果字段还不能是空字符串，需要组合：

new Param('nickname', validate: [
    new Required(),
    new NotEmpty(),
]);

可选字段的正确写法

new Param(
    name: 'age',
    from: ParamFrom::JSON,
    type: null,
    validate: [
        new Optional(),
        new Integer(),
        new Min(18),
    ]
)

type: null 保留未传入时的 null，使 Optional 可以准确跳过后续规则。Optional*、IgnoreValidatorWhenEmpty 不能与 Required*、NotEmpty 用在同一个 Param 中；当前版本会把这种配置直接判为冲突。

条件必填示例

new Param(name: 'type', from: ParamFrom::JSON),
new Param(
    name: 'companyName',
    from: ParamFrom::JSON,
    validate: [
        new RequiredIf('type', 'company'),
        new MaxMbLength(100),
    ]
)

当 type=company 时必须传 companyName。

数字与金额规则

不要只依赖 ParamType::INT 判断输入是否合法，因为类型转换发生在验证之前，字符串 abc 转成整数后会变成 0。需要验证原始格式时使用 type: null：

new Param(
    name: 'quantity',
    from: ParamFrom::JSON,
    type: null,
    validate: [new Required(), new Integer(), new Min(1)]
)

金额建议作为字符串验证，进入金额计算时再转换成最小货币单位，避免浮点误差：

new Param('amount', from: ParamFrom::JSON, type: null, validate: [
    new Required(),
    new Money(2),
]);

字符串与格式规则

URL 示例：

new Param('callbackUrl', from: ParamFrom::JSON, validate: [
    new Required(),
    new IsUrl(['https'], '回调地址必须使用 HTTPS'),
]);

格式验证只说明字符串长得像合法 URL。若服务器随后访问这个地址，还必须增加域名/IP 允许列表以防 SSRF。

长度规则

中文名称应使用 Mb 系列：

new Param('name', from: ParamFrom::JSON, validate: [
    new Required(),
    new BetweenMbLen(2, 20),
]);

Length 使用字节数，一个 UTF-8 中文通常占多个字节；MbLength 才更接近用户理解的字符数量。

固定值、枚举与去重规则

原生枚举示例：

enum Status: string
{
    case Draft = 'draft';
    case Published = 'published';
}

new Param(
    name: 'status',
    from: ParamFrom::JSON,
    type: null,
    validate: [new Enum(Status::class, strict: true)]
)

JSON 数组去重时必须使用 type: null，否则默认字符串转换会破坏数组：

new Param('ids', from: ParamFrom::JSON, type: null, validate: [
    new Required(),
    new DistinctInArray(strict: true),
]);

字段比较规则

确认密码示例：

new Param('password', from: ParamFrom::JSON, type: null, validate: [
    new Required(),
    new MinLength(8),
]),
new Param('passwordConfirmation', from: ParamFrom::JSON, type: null, validate: [
    new Required(),
    new EqualWithColumn('password', strict: true),
])

关联字段必须也定义为 Param。比较使用的是双方解析及类型转换之后的值，严格比较时尤其要注意两边的 type 是否一致。

日期与时间规则

日期区间示例：

new Param('startDate', from: ParamFrom::JSON, validate: [
    new Required(),
    new DateFormat('Y-m-d'),
]),
new Param('endDate', from: ParamFrom::JSON, validate: [
    new Required(),
    new DateFormat('Y-m-d'),
    new DateAfterColumn('startDate'),
])

日期和时间戳规则使用服务器时区。生产项目应统一配置时区，并在 API 文档中说明时间格式和时区。

文件规则

IsFile 用于上传文件：

new Param(
    name: 'avatar',
    from: ParamFrom::FILE,
    type: ParamType::FILE,
    validate: [
        new Required(),
        new IsFile(
            maxSize: 2 * 1024 * 1024,
            allowExt: ['jpg', 'png'],
            errorMsg: '头像必须是 2MB 以内的 JPG 或 PNG 文件'
        ),
    ]
)

maxSize 单位是字节，allowExt 使用小写扩展名。它根据上传对象和客户端文件名扩展名验证，不检查真实 MIME 或文件内容。图片上传仍应使用 finfo 检查 MIME，必要时重新解码生成。

ParamFrom::FILE 必须是唯一参数来源，不能与 GET、POST 等来源组合。

自定义错误信息

所有内置规则最后一个构造参数都是 errorMsg：

new Min(
    min: 18,
    errorMsg: '{#validateParam} 不能小于 {#min}'
)

常用占位符：

• {#validateParam}：当前参数名。
• {#min}、{#max}：数值边界。
• {#minLen}、{#maxLen}：长度边界。
• {#compare} 或 {#paramName}：比较目标。
• DateFormat 使用 {#format}。

不同规则支持的占位符取决于规则本身的属性。简单项目也可以直接写固定中文文案。

自定义验证函数 Func

内置规则无法表达业务规则时，可以使用 Func。由于 PHP Attribute 参数必须是常量表达式，Attribute 中不要直接写闭包，应传静态方法：

新建 App/Validator/TicketValidator.php：

<?php

namespace App\Validator;

use EasySwoole\HttpAnnotation\Validator\Bean\ValidateRequest;

class TicketValidator
{
    public static function check(ValidateRequest $context): bool
    {
        $value = $context->validateParam->parsedValue();

        return is_string($value)
            && str_starts_with($value, 'ticket-');
    }
}

控制器中使用：

use App\Validator\TicketValidator;
use EasySwoole\HttpAnnotation\Validator\Func;

new Param(
    name: 'ticket',
    from: ParamFrom::JSON,
    validate: [
        new Required(),
        new Func(
            func: [TicketValidator::class, 'check'],
            errorMsg: 'ticket 格式不正确'
        ),
    ]
)

也可以让验证器实现 ValidateFuncInterface，再将对象传给 Func。仅在普通 PHP 代码动态创建规则时才适合使用闭包。

常用组合

用户名：

new Param('username', from: ParamFrom::JSON, validate: [
    new Required(),
    new NotEmpty(),
    new AlphaNum(),
    new BetweenLen(4, 20),
]);

分页页码：

new Param('page', from: ParamFrom::GET, type: null, value: 1, validate: [
    new Integer(),
    new Min(1),
]);

可选邮箱：

new Param('email', from: ParamFrom::JSON, type: null, validate: [
    new Optional(),
    new IsEmail(),
]);

价格：

new Param('price', from: ParamFrom::JSON, type: null, validate: [
    new Required(),
    new Money(2),
]);

常见错误

• 忘记导入 Validator 类，PHP 会在当前控制器命名空间中寻找同名类。
• 只写 ParamType::INT，却没有使用 Integer 验证原始输入。
• 中文长度使用 Length，导致一个汉字被计算为多个字节。
• Optional 与 Required、NotEmpty 同时使用，产生互斥配置。
• JSON 数组没有设置 type: null，被默认 STRING 转换破坏。
• 字段比较规则引用了未定义的参数。
• 文件扩展名验证通过后就直接信任文件内容。
• 把数据库唯一性、库存等业务规则全部写成参数 Validator；这类规则仍应由 Service 和数据库约束完成。

下一章：生成接口文档。