一个为 Hyperf 框架打造的智能请求验证组件,支持注解驱动、自动类型转换、友好错误提示等特性。
- 原版耗时:2.5ms/请求
- 优化版耗时:0.1ms/请求
- QPS提升:从 4,000 提升到 20,000+
- ✅ 启动预加载:应用启动时解析所有验证规则
- ✅ 内存缓存:规则缓存在Worker进程内存,O(1)查找
- ✅ 零解析开销:后续请求无需重复解析
- ✅ 实例池化:验证器对象复用,减少GC压力
- ✅ 100%兼容:保留原版所有验证功能
- ✅ 40+验证规则:内置丰富的验证规则
- ✅ 场景验证:支持多场景灵活验证
- ✅ 自定义扩展:轻松添加自定义规则
- ✅ 注解驱动:声明式验证,代码更清晰
- ✅ IDE友好:完整的类型提示
- ✅ 错误友好:支持自定义错误消息和字段名
指标 | 优化前 | 优化后 | 提升 |
---|---|---|---|
单次验证 | 2.5ms | 0.1ms | 25倍 |
QPS | 4,000 | 20,000+ | 5倍 |
CPU使用率 | 80% | 30% | -62.5% |
缓存命中率 | 0% | 99%+ | - |
composer require hyperf-plus/validate
本包支持无缝升级,完全向后兼容。所有公共API和注解保持不变:
RequestValidation
注解的所有参数保持兼容RuleParser
的公共方法签名未改变- 仅进行了内部性能优化,不影响外部使用
<?php
use HPlus\Validate\Annotations\RequestValidation;
use HPlus\Route\Annotation\PostApi;
class UserController
{
#[PostApi]
#[RequestValidation(
rules: [
'username' => 'required|string|min:3|max:20',
'email' => 'required|email',
'age' => 'integer|min:18|max:100',
'password' => 'required|string|min:6'
]
)]
public function create()
{
// 验证通过后执行
$data = $this->request->getParsedBody();
// ...
}
}
#[RequestValidation(
rules: [
'username|用户名' => 'required|string|min:3|max:20',
'email|邮箱地址' => 'required|email',
'age|年龄' => 'integer|min:18|max:100',
'password|密码' => 'required|string|min:6'
]
)]
#[RequestValidation(
rules: [
'username' => 'required|string|min:3|max:20',
'email' => 'required|email'
],
messages: [
'username.required' => '请输入用户名',
'username.min' => '用户名至少需要3个字符',
'email.required' => '请输入邮箱地址',
'email.email' => '邮箱格式不正确'
]
)]
#[RequestValidation(
rules: [
'user' => 'required|array',
'user.name' => 'required|string',
'user.email' => 'required|email',
'user.profile' => 'array',
'user.profile.bio' => 'string|max:200',
'tags' => 'array',
'tags.*' => 'string|distinct'
]
)]
规则 | 说明 | 示例 |
---|---|---|
required | 必填 | required |
nullable | 可为 null | nullable |
string | 字符串 | string |
integer | 整数 | integer |
numeric | 数字 | numeric |
boolean | 布尔值 | boolean |
array | 数组 | array |
json | JSON 字符串 | json |
规则 | 说明 | 示例 |
---|---|---|
min:n | 最小长度 | min:3 |
max:n | 最大长度 | max:20 |
length:n | 固定长度 | length:11 |
邮箱格式 | email |
|
url | URL 格式 | url |
ip | IP 地址 | ip |
alpha | 纯字母 | alpha |
alpha_num | 字母数字 | alpha_num |
alpha_dash | 字母数字下划线横线 | alpha_dash |
regex:pattern | 正则匹配 | regex:/^1[3-9]\d{9}$/ |
规则 | 说明 | 示例 |
---|---|---|
min:n | 最小值 | min:0 |
max:n | 最大值 | max:100 |
between:min,max | 范围 | between:1,100 |
gt:n | 大于 | gt:0 |
gte:n | 大于等于 | gte:0 |
lt:n | 小于 | lt:100 |
lte:n | 小于等于 | lte:100 |
规则 | 说明 | 示例 |
---|---|---|
min:n | 最少元素 | min:1 |
max:n | 最多元素 | max:10 |
size:n | 固定数量 | size:3 |
distinct | 元素唯一 | distinct |
规则 | 说明 | 示例 |
---|---|---|
in:list | 枚举值 | in:active,inactive,pending |
not_in:list | 排除值 | not_in:deleted,banned |
confirmed | 确认字段 | confirmed |
different:field | 不同于字段 | different:username |
same:field | 相同于字段 | same:password |
date | 日期格式 | date |
date_format:format | 日期格式 | date_format:Y-m-d |
before:date | 早于日期 | before:2024-12-31 |
after:date | 晚于日期 | after:2024-01-01 |
file | 文件 | file |
image | 图片 | image |
mimes:list | 文件类型 | mimes:jpg,png,pdf |
#[RequestValidation(
rules: [
'type' => 'required|in:personal,company',
'name' => 'required|string',
'company_name' => 'required_if:type,company|string',
'tax_number' => 'required_if:type,company|string'
]
)]
use HPlus\Validate\ValidateRule;
// 注册自定义规则
ValidateRule::extend('phone', function ($attribute, $value, $parameters) {
return preg_match('/^1[3-9]\d{9}$/', $value);
});
// 使用自定义规则
#[RequestValidation(
rules: [
'mobile' => 'required|phone'
],
messages: [
'mobile.phone' => '手机号格式不正确'
]
)]
#[RequestValidation(
rules: [
'username' => 'required|string|min:3',
'email' => 'required|email',
'password' => 'required|string|min:6'
],
scene: 'create' // 创建场景
)]
public function create() {}
#[RequestValidation(
rules: [
'username' => 'string|min:3',
'email' => 'email',
'password' => 'string|min:6'
],
scene: 'update' // 更新场景(字段可选)
)]
public function update() {}
#[RequestValidation(
rules: [
'name' => 'required|string',
'tags' => 'array',
'settings' => 'json'
],
dateType: 'json' // 请求体类型:json(默认)、form、query
)]
#[RequestValidation(
rules: [
'email' => 'required|email',
'username' => 'required|string'
],
before: function (&$data) {
// 前置处理:转换小写
$data['email'] = strtolower($data['email'] ?? '');
$data['username'] = trim($data['username'] ?? '');
}
)]
对于复杂验证逻辑,建议使用独立的验证器类:
<?php
namespace App\Validator;
use HPlus\Validate\Validate;
class UserValidator extends Validate
{
protected array $rule = [
'username' => 'required|string|min:3|max:20',
'email' => 'required|email',
'password' => 'required|string|min:6',
'age' => 'integer|between:18,100'
];
protected array $message = [
'username.required' => '请输入用户名',
'email.email' => '邮箱格式不正确',
'password.min' => '密码至少6个字符'
];
protected array $scene = [
'create' => ['username', 'email', 'password'],
'update' => ['username', 'email'],
'login' => ['email', 'password']
];
}
// 使用验证器
#[PostApi]
#[RequestValidation(validator: UserValidator::class, scene: 'create')]
public function create() {}
验证组件会自动识别路由参数:
#[GetApi]
#[RequestValidation(rules: [
'page' => 'integer|min:1|default:1',
'size' => 'integer|min:1|max:100|default:20',
'keyword' => 'string|max:50'
])]
public function index() {}
验证规则会自动转换为 OpenAPI 参数定义:
required
→ required: trueinteger
→ type: integermin/max
→ minimum/maximumenum/in
→ enum 数组- 字段描述 → description
- 规则缓存 - 编译后的规则缓存复用
- 懒加载 - 按需加载验证器
- 批量验证 - 一次验证所有规则
- 智能短路 - 失败即停止后续验证
在 config/autoload/validate.php
中配置:
return [
// 默认错误码
'error_code' => 422,
// 默认错误消息
'error_message' => '验证失败',
// 是否返回所有错误
'return_all_errors' => true,
// 自定义错误格式
'error_format' => function ($errors) {
return [
'code' => 422,
'message' => '验证失败',
'errors' => $errors
];
}
];
-
规则组织
- 简单验证用注解
- 复杂验证用验证器类
- 共用规则抽取为基类
-
错误处理
- 提供友好的错误提示
- 使用字段描述而非字段名
- 支持多语言错误消息
-
性能考虑
- 合理使用验证场景
- 避免过度复杂的正则
- 大数据量考虑分批验证
-
验证不生效
- 检查注解是否正确导入
- 确认中间件是否注册
- 验证规则语法是否正确
-
类型转换失败
- 检查数据类型是否匹配
- 使用
nullable
处理可选字段 - 注意
dateType
设置
-
自定义规则不工作
- 确认规则已注册
- 检查规则名称是否冲突
- 验证闭包返回值
MIT License
欢迎提交 Issue 和 Pull Request!