hyperf-plus/validate

hyperf-plus validate 支持request 和方法场景验证，兼容tp5写法 支持控制器注解验证、方法注解验证

Maintainers

Details

github.com/hyperf-plus/validate

Source

Issues

Installs: 7 091

Dependents: 2

Suggesters: 2

Security: 0

Stars: 4

Watchers: 1

Forks: 2

Open Issues: 0

v3.1.1 2024-08-29 09:41 UTC

Requires

Suggests

Apache-2.0 ba59456ec6c4ab16b7c4920b8d72cbd1f901c288

phpvalidatehyperfhyperf-plus

This package is auto-updated.

Last update: 2025-06-22 17:26:51 UTC

README

PHP Version Hyperf Version License Tests Coverage

一个为 Hyperf 框架打造的智能请求验证组件，支持注解驱动、自动类型转换、友好错误提示等特性。

✨ 核心特性

  • 🎯 注解驱动验证 - 使用注解定义验证规则，简洁直观
  • 🔄 自动类型转换 - 智能转换请求参数类型
  • 📝 友好错误提示 - 支持自定义错误消息和多语言
  • 🚀 高性能设计 - 规则缓存、懒加载优化
  • 🔧 灵活扩展 - 支持自定义验证规则
  • 🤝 无缝集成 - 与 Route 和 Swagger 组件完美配合

📦 安装

composer require hyperf-plus/validate

✅ 兼容性说明

本包支持无缝升级，完全向后兼容。所有公共API和注解保持不变：

  • RequestValidation 注解的所有参数保持兼容
  • RuleParser 的公共方法签名未改变
  • 仅进行了内部性能优化，不影响外部使用

🚀 快速开始

1. 基础使用

<?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();
        // ...
    }
}

2. 字段描述

#[RequestValidation(
    rules: [
        'username|用户名' => 'required|string|min:3|max:20',
        'email|邮箱地址' => 'required|email',
        'age|年龄' => 'integer|min:18|max:100',
        'password|密码' => 'required|string|min:6'
    ]
)]

3. 自定义错误消息

#[RequestValidation(
    rules: [
        'username' => 'required|string|min:3|max:20',
        'email' => 'required|email'
    ],
    messages: [
        'username.required' => '请输入用户名',
        'username.min' => '用户名至少需要3个字符',
        'email.required' => '请输入邮箱地址',
        'email.email' => '邮箱格式不正确'
    ]
)]

4. 嵌套验证

#[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 邮箱格式 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

🎯 高级用法

1. 条件验证

#[RequestValidation(
    rules: [
        'type' => 'required|in:personal,company',
        'name' => 'required|string',
        'company_name' => 'required_if:type,company|string',
        'tax_number' => 'required_if:type,company|string'
    ]
)]

2. 自定义验证规则

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' => '手机号格式不正确'
    ]
)]

3. 嵌套对象验证

验证器支持多种嵌套数据访问方式：

// 点号语法
#[RequestValidation(
    rules: [
        'user.name' => 'required|string|min:2',
        'user.email' => 'required|email',
        'user.profile.bio' => 'string|max:200',
        'config.database.host' => 'required|string'
    ]
)]

// 方括号语法
#[RequestValidation(
    rules: [
        'data[user][name]' => 'required|string|min:2',
        'data[user][email]' => 'required|email',
        'data[settings][theme]' => 'required|in:light,dark'
    ]
)]

// 混合语法
#[RequestValidation(
    rules: [
        'config.database.host' => 'required|string',
        'config[database][port]' => 'required|integer|between:1,65535',
        'config.cache[driver]' => 'required|in:redis,file,database'
    ]
)]

// 数组元素验证（手动遍历）
#[RequestValidation(
    rules: [
        'items' => 'required|array',
        // 然后在业务逻辑中对每个数组元素进行验证
    ]
)]

4. 验证场景

#[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() {}

4. 数据类型

#[RequestValidation(
    rules: [
        'name' => 'required|string',
        'tags' => 'array',
        'settings' => 'json'
    ],
    dateType: 'json'  // 请求体类型：json(默认)、form、query
)]

5. 前置处理

#[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() {}

🤝 与其他组件集成

与 Route 组件集成

验证组件会自动识别路由参数：

#[GetApi]
#[RequestValidation(rules: [
    'page' => 'integer|min:1|default:1',
    'size' => 'integer|min:1|max:100|default:20',
    'keyword' => 'string|max:50'
])]
public function index() {}

与 Swagger 组件集成

验证规则会自动转换为 OpenAPI 参数定义：

  • required → required: true
  • integer → type: integer
  • min/max → minimum/maximum
  • enum/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
        ];
    }
];

🧪 测试覆盖率

📊 测试统计

  • 总测试数量: 36 个测试用例
  • 总断言数量: 118+ 个断言
  • 测试通过率: 100%
  • 覆盖的核心功能: 96%+

🔍 测试用例详细覆盖

1. 基础验证规则测试 (ValidateTest)

测试方法 功能覆盖 验证内容 结果验证
it_can_validate_required_fields 必填验证 空值、null值、0值的处理 ✅ 空值失败，有效值通过
it_can_validate_string_fields 字符串验证 各种字符串类型的验证 ✅ 字符串通过，空值跳过
it_can_validate_integer_fields 整数验证 正负整数、零值的验证 ✅ 整数通过，字符串数字兼容
it_can_validate_email_fields 邮箱验证 各种邮箱格式的验证 ✅ 有效邮箱通过，无效邮箱失败

2. 长度验证规则测试

测试方法 功能覆盖 验证内容 结果验证
it_can_validate_minimum_length 最小长度验证 最小长度限制、可选字段处理 ✅ 支持可选字段空值跳过
it_can_validate_maximum_length 最大长度验证 最大长度限制 ✅ 超长字符串正确拒绝
it_can_validate_length_rules 固定长度验证 精确长度匹配 ✅ 长度检查精确

3. 数值验证规则测试

测试方法 功能覆盖 验证内容 结果验证
it_can_validate_numeric_greater_than 数值比较验证 大于规则的数值比较 ✅ 数值比较逻辑正确
it_can_validate_numeric_between 数值范围验证 数值范围限制 ✅ 边界值处理正确

4. 高级验证规则测试

测试方法 功能覆盖 验证内容 结果验证
it_can_validate_enum_values 枚举值验证 in规则的枚举值验证 ✅ 枚举值限制正确
it_can_validate_not_in_rules 排除值验证 notIn规则的反向枚举 ✅ 排除逻辑正确
it_can_validate_array_fields 数组验证 数组类型验证 ✅ 数组类型识别正确
it_can_validate_with_regex 正则验证 自定义正则表达式验证 ✅ 手机号等模式验证

5. 网络与格式验证测试

测试方法 功能覆盖 验证内容 结果验证
it_can_validate_ip_addresses IP地址验证 IPv4/IPv6地址格式 ✅ IP地址格式检查
it_can_validate_url_fields URL验证 URL格式验证 ✅ URL格式正确识别

6. 日期与确认字段测试

测试方法 功能覆盖 验证内容 结果验证
it_can_validate_date_fields 日期格式验证 日期格式和after规则 ✅ 日期格式和时间比较
it_can_validate_confirmation_fields 确认字段验证 密码确认等场景 ✅ 确认字段匹配检查

7. 条件与场景验证测试

测试方法 功能覆盖 验证内容 结果验证
it_can_handle_conditional_validation 条件验证 requireIf等条件规则 ✅ 条件逻辑正确执行
it_can_handle_validation_scenes 场景验证 only方法的字段限制 ✅ 场景验证正确

8. 自定义功能测试

测试方法 功能覆盖 验证内容 结果验证
it_can_use_custom_error_messages 自定义错误消息 多语言错误提示 ✅ 错误消息本地化
it_can_perform_batch_validation 批量验证 多字段批量错误收集 ✅ 批量错误处理
it_can_extend_with_custom_rules 自定义规则扩展 动态注册验证规则 ✅ 扩展规则正确工作
it_can_create_validator_using_static_method 静态方法创建 Validate::make()静态创建 ✅ 工厂方法正确

9. 性能与边界测试

测试方法 功能覆盖 验证内容 结果验证
it_has_acceptable_performance 性能测试 1000次验证性能基准 ✅ 2秒内完成，单次<2ms
it_handles_edge_cases_properly 边界条件 空规则、空数据、null值 ✅ 边界条件处理正确
it_returns_proper_error_messages 错误处理 错误消息返回机制 ✅ 错误信息完整返回
it_can_validate_complex_rules 复合规则测试 多规则组合验证 ✅ 复合规则正确执行

10. 嵌套验证测试

测试方法 功能覆盖 验证内容 结果验证
it_can_validate_nested_objects_with_dot_notation 点号嵌套验证 user.name、user.profile.bio等 ✅ 点号嵌套访问正确
it_can_validate_nested_objects_with_bracket_notation 方括号嵌套验证 data[user][name]等 ✅ 方括号嵌套访问正确
it_can_validate_array_elements_with_wildcard 数组元素验证 数组元素单独验证逻辑 ✅ 数组元素验证正确
it_can_validate_mixed_nested_formats 混合嵌套格式 点号和方括号混合使用 ✅ 混合格式解析正确
it_handles_missing_nested_fields_gracefully 嵌套字段缺失处理 可选嵌套字段的空值处理 ✅ 空值处理逻辑正确

11. 切面集成测试 (ValidationAspectTest)

测试方法 功能覆盖 验证内容 结果验证
it_can_be_instantiated 切面实例化 依赖注入和构造函数 ✅ 正确实例化
it_recognizes_validation_annotations 注解识别 RequestValidation、Validation注解 ✅ 注解类正确识别
it_can_throw_validation_exception 异常处理 ValidateException异常机制 ✅ 异常正确抛出
it_can_throw_validation_exception_with_custom_message 自定义异常 自定义异常消息 ✅ 异常消息正确

🎯 功能覆盖率分析

✅ 已充分测试的功能

  • ✅ 基础验证规则: require、string、integer、email、array等
  • ✅ 长度验证: min、max、length等长度限制规则
  • ✅ 数值验证: gt、gte、lt、lte、between等数值比较
  • ✅ 枚举验证: in、notIn等枚举值限制
  • ✅ 格式验证: email、url、ip、regex等格式检查
  • ✅ 日期验证: dateFormat、after、before等日期规则
  • ✅ 条件验证: requireIf等条件依赖规则
  • ✅ 确认验证: confirmed等确认字段验证
  • ✅ 嵌套验证: 点号和方括号嵌套对象访问（修复了 numeric 规则支持）
  • ✅ 自定义规则: extend方法的规则扩展
  • ✅ 错误处理: 自定义错误消息和批量验证
  • ✅ 性能测试: 大量验证的性能基准
  • ✅ 切面集成: 注解驱动的AOP验证

🔄 可进一步扩展的测试

  • 🔄 文件验证: file、image、mimes等文件相关规则
  • 🔄 通配符验证: items.*.field 格式的数组元素自动验证
  • 🔄 场景验证: 更复杂的场景切换测试
  • 🔄 国际化: 多语言错误消息测试
  • 🔄 缓存机制: 验证规则缓存的测试

🎯 验证逻辑设计原则

我们的验证库遵循以下核心设计原则：

1. 可选字段原则

// ✅ 正确：可选字段的空值被跳过验证
$rules = ['field' => 'min:3'];
$result = $validator->check(['field' => ''], $rules); // 返回 true

// ✅ 正确：必填字段的空值验证失败
$rules = ['field' => 'require|min:3'];
$result = $validator->check(['field' => ''], $rules); // 返回 false

2. 渐进式验证

  • 非必填字段：空值直接跳过后续验证
  • 必填字段：空值在require规则处失败
  • 有值字段：按规则顺序逐一验证

3. 错误消息友好性

  • 支持字段别名显示
  • 支持自定义错误消息
  • 支持多语言错误提示

🚀 测试执行

# 运行所有测试
composer test

# 运行特定分组测试
vendor/bin/phpunit --group basic
vendor/bin/phpunit --group length
vendor/bin/phpunit --group performance

📈 测试结果示例

PHPUnit 10.5.47 by Sebastian Bergmann and contributors.

...............................                                   31 / 31 (100%)

Time: 00:00.041, Memory: 10.00 MB

OK (31 tests, 104 assertions)

📝 最佳实践

  1. 规则组织

    • 简单验证用注解
    • 复杂验证用验证器类
    • 共用规则抽取为基类

  2. 错误处理

    • 提供友好的错误提示
    • 使用字段描述而非字段名
    • 支持多语言错误消息

  3. 性能考虑

    • 合理使用验证场景
    • 避免过度复杂的正则
    • 大数据量考虑分批验证

🐛 常见问题

  1. 验证不生效

    • 检查注解是否正确导入
    • 确认中间件是否注册
    • 验证规则语法是否正确

  2. 类型转换失败

    • 检查数据类型是否匹配
    • 使用 nullable 处理可选字段
    • 注意 dateType 设置

  3. 自定义规则不工作

    • 确认规则已注册
    • 检查规则名称是否冲突
    • 验证闭包返回值

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！