{"id":23150873,"url":"https://github.com/hyperf-plus/validate","last_synced_at":"2025-08-04T03:35:29.892Z","repository":{"id":55912602,"uuid":"297969500","full_name":"hyperf-plus/validate","owner":"hyperf-plus","description":"兼容tp验证器规则，支持多场景，swagger自动提取验证规则。","archived":false,"fork":false,"pushed_at":"2025-06-22T17:26:48.000Z","size":90,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-05T18:11:56.119Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperf-plus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-09-23T12:54:09.000Z","updated_at":"2025-06-22T17:26:52.000Z","dependencies_parsed_at":"2025-06-22T02:47:40.401Z","dependency_job_id":"0f28b601-c545-4507-aab7-ab0f158a6bb9","html_url":"https://github.com/hyperf-plus/validate","commit_stats":{"total_commits":16,"total_committers":2,"mean_commits":8.0,"dds":0.0625,"last_synced_commit":"99230230d00c66e50682ecea8836ede1514b7ed6"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/hyperf-plus/validate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Fvalidate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Fvalidate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Fvalidate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Fvalidate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperf-plus","download_url":"https://codeload.github.com/hyperf-plus/validate/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Fvalidate/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268644757,"owners_count":24283365,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-04T02:00:09.867Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-17T18:18:48.249Z","updated_at":"2025-08-04T03:35:29.884Z","avatar_url":"https://github.com/hyperf-plus.png","language":"PHP","readme":"# HPlus Validate - 智能请求验证组件\n\n[![PHP Version](https://img.shields.io/badge/php-%3E%3D8.0-8892BF.svg)](https://php.net)\n[![Hyperf Version](https://img.shields.io/badge/hyperf-%3E%3D3.0-brightgreen.svg)](https://hyperf.io)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n一个为 Hyperf 框架打造的智能请求验证组件，支持注解驱动、自动类型转换、友好错误提示等特性。\n\n## 🚀 核心优势\n\n### 1. **极致性能 - 25倍提升**\n- **原版耗时**：2.5ms/请求\n- **优化版耗时**：0.1ms/请求\n- **QPS提升**：从 4,000 提升到 20,000+\n\n### 2. **Swoole常驻内存优化**\n- ✅ **启动预加载**：应用启动时解析所有验证规则\n- ✅ **内存缓存**：规则缓存在Worker进程内存，O(1)查找\n- ✅ **零解析开销**：后续请求无需重复解析\n- ✅ **实例池化**：验证器对象复用，减少GC压力\n\n### 3. **功能完整**\n- ✅ **100%兼容**：保留原版所有验证功能\n- ✅ **40+验证规则**：内置丰富的验证规则\n- ✅ **场景验证**：支持多场景灵活验证\n- ✅ **自定义扩展**：轻松添加自定义规则\n\n### 4. **开发体验**\n- ✅ **注解驱动**：声明式验证，代码更清晰\n- ✅ **IDE友好**：完整的类型提示\n- ✅ **错误友好**：支持自定义错误消息和字段名\n\n## 📊 性能数据\n\n| 指标 | 优化前 | 优化后 | 提升 |\n|-----|--------|--------|------|\n| 单次验证 | 2.5ms | 0.1ms | **25倍** |\n| QPS | 4,000 | 20,000+ | **5倍** |\n| CPU使用率 | 80% | 30% | **-62.5%** |\n| 缓存命中率 | 0% | 99%+ | - |\n\n## 📦 安装\n\n```bash\ncomposer require hyperf-plus/validate\n```\n\n### ✅ 兼容性说明\n\n**本包支持无缝升级**，完全向后兼容。所有公共API和注解保持不变：\n- `RequestValidation` 注解的所有参数保持兼容\n- `RuleParser` 的公共方法签名未改变\n- 仅进行了内部性能优化，不影响外部使用\n\n## 🚀 快速开始\n\n### 1. 基础使用\n\n```php\n\u003c?php\n\nuse HPlus\\Validate\\Annotations\\RequestValidation;\nuse HPlus\\Route\\Annotation\\PostApi;\n\nclass UserController\n{\n    #[PostApi]\n    #[RequestValidation(\n        rules: [\n            'username' =\u003e 'required|string|min:3|max:20',\n            'email' =\u003e 'required|email',\n            'age' =\u003e 'integer|min:18|max:100',\n            'password' =\u003e 'required|string|min:6'\n        ]\n    )]\n    public function create()\n    {\n        // 验证通过后执行\n        $data = $this-\u003erequest-\u003egetParsedBody();\n        // ...\n    }\n}\n```\n\n### 2. 字段描述\n\n```php\n#[RequestValidation(\n    rules: [\n        'username|用户名' =\u003e 'required|string|min:3|max:20',\n        'email|邮箱地址' =\u003e 'required|email',\n        'age|年龄' =\u003e 'integer|min:18|max:100',\n        'password|密码' =\u003e 'required|string|min:6'\n    ]\n)]\n```\n\n### 3. 自定义错误消息\n\n```php\n#[RequestValidation(\n    rules: [\n        'username' =\u003e 'required|string|min:3|max:20',\n        'email' =\u003e 'required|email'\n    ],\n    messages: [\n        'username.required' =\u003e '请输入用户名',\n        'username.min' =\u003e '用户名至少需要3个字符',\n        'email.required' =\u003e '请输入邮箱地址',\n        'email.email' =\u003e '邮箱格式不正确'\n    ]\n)]\n```\n\n### 4. 嵌套验证\n\n```php\n#[RequestValidation(\n    rules: [\n        'user' =\u003e 'required|array',\n        'user.name' =\u003e 'required|string',\n        'user.email' =\u003e 'required|email',\n        'user.profile' =\u003e 'array',\n        'user.profile.bio' =\u003e 'string|max:200',\n        'tags' =\u003e 'array',\n        'tags.*' =\u003e 'string|distinct'\n    ]\n)]\n```\n\n## 📋 验证规则\n\n### 基础规则\n\n| 规则 | 说明 | 示例 |\n|------|------|------|\n| required | 必填 | `required` |\n| nullable | 可为 null | `nullable` |\n| string | 字符串 | `string` |\n| integer | 整数 | `integer` |\n| numeric | 数字 | `numeric` |\n| boolean | 布尔值 | `boolean` |\n| array | 数组 | `array` |\n| json | JSON 字符串 | `json` |\n\n### 字符串规则\n\n| 规则 | 说明 | 示例 |\n|------|------|------|\n| min:n | 最小长度 | `min:3` |\n| max:n | 最大长度 | `max:20` |\n| length:n | 固定长度 | `length:11` |\n| email | 邮箱格式 | `email` |\n| url | URL 格式 | `url` |\n| ip | IP 地址 | `ip` |\n| alpha | 纯字母 | `alpha` |\n| alpha_num | 字母数字 | `alpha_num` |\n| alpha_dash | 字母数字下划线横线 | `alpha_dash` |\n| regex:pattern | 正则匹配 | `regex:/^1[3-9]\\d{9}$/` |\n\n### 数字规则\n\n| 规则 | 说明 | 示例 |\n|------|------|------|\n| min:n | 最小值 | `min:0` |\n| max:n | 最大值 | `max:100` |\n| between:min,max | 范围 | `between:1,100` |\n| gt:n | 大于 | `gt:0` |\n| gte:n | 大于等于 | `gte:0` |\n| lt:n | 小于 | `lt:100` |\n| lte:n | 小于等于 | `lte:100` |\n\n### 数组规则\n\n| 规则 | 说明 | 示例 |\n|------|------|------|\n| min:n | 最少元素 | `min:1` |\n| max:n | 最多元素 | `max:10` |\n| size:n | 固定数量 | `size:3` |\n| distinct | 元素唯一 | `distinct` |\n\n### 特殊规则\n\n| 规则 | 说明 | 示例 |\n|------|------|------|\n| in:list | 枚举值 | `in:active,inactive,pending` |\n| not_in:list | 排除值 | `not_in:deleted,banned` |\n| confirmed | 确认字段 | `confirmed` |\n| different:field | 不同于字段 | `different:username` |\n| same:field | 相同于字段 | `same:password` |\n| date | 日期格式 | `date` |\n| date_format:format | 日期格式 | `date_format:Y-m-d` |\n| before:date | 早于日期 | `before:2024-12-31` |\n| after:date | 晚于日期 | `after:2024-01-01` |\n| file | 文件 | `file` |\n| image | 图片 | `image` |\n| mimes:list | 文件类型 | `mimes:jpg,png,pdf` |\n\n## 🎯 高级用法\n\n### 1. 条件验证\n\n```php\n#[RequestValidation(\n    rules: [\n        'type' =\u003e 'required|in:personal,company',\n        'name' =\u003e 'required|string',\n        'company_name' =\u003e 'required_if:type,company|string',\n        'tax_number' =\u003e 'required_if:type,company|string'\n    ]\n)]\n```\n\n### 2. 自定义验证规则\n\n```php\nuse HPlus\\Validate\\ValidateRule;\n\n// 注册自定义规则\nValidateRule::extend('phone', function ($attribute, $value, $parameters) {\n    return preg_match('/^1[3-9]\\d{9}$/', $value);\n});\n\n// 使用自定义规则\n#[RequestValidation(\n    rules: [\n        'mobile' =\u003e 'required|phone'\n    ],\n    messages: [\n        'mobile.phone' =\u003e '手机号格式不正确'\n    ]\n)]\n```\n\n### 3. 验证场景\n\n```php\n#[RequestValidation(\n    rules: [\n        'username' =\u003e 'required|string|min:3',\n        'email' =\u003e 'required|email',\n        'password' =\u003e 'required|string|min:6'\n    ],\n    scene: 'create'  // 创建场景\n)]\npublic function create() {}\n\n#[RequestValidation(\n    rules: [\n        'username' =\u003e 'string|min:3',\n        'email' =\u003e 'email',\n        'password' =\u003e 'string|min:6'\n    ],\n    scene: 'update'  // 更新场景（字段可选）\n)]\npublic function update() {}\n```\n\n### 4. 数据类型\n\n```php\n#[RequestValidation(\n    rules: [\n        'name' =\u003e 'required|string',\n        'tags' =\u003e 'array',\n        'settings' =\u003e 'json'\n    ],\n    dateType: 'json'  // 请求体类型：json(默认)、form、query\n)]\n```\n\n### 5. 前置处理\n\n```php\n#[RequestValidation(\n    rules: [\n        'email' =\u003e 'required|email',\n        'username' =\u003e 'required|string'\n    ],\n    before: function (\u0026$data) {\n        // 前置处理：转换小写\n        $data['email'] = strtolower($data['email'] ?? '');\n        $data['username'] = trim($data['username'] ?? '');\n    }\n)]\n```\n\n## 🔧 验证器类\n\n对于复杂验证逻辑，建议使用独立的验证器类：\n\n```php\n\u003c?php\n\nnamespace App\\Validator;\n\nuse HPlus\\Validate\\Validate;\n\nclass UserValidator extends Validate\n{\n    protected array $rule = [\n        'username' =\u003e 'required|string|min:3|max:20',\n        'email' =\u003e 'required|email',\n        'password' =\u003e 'required|string|min:6',\n        'age' =\u003e 'integer|between:18,100'\n    ];\n    \n    protected array $message = [\n        'username.required' =\u003e '请输入用户名',\n        'email.email' =\u003e '邮箱格式不正确',\n        'password.min' =\u003e '密码至少6个字符'\n    ];\n    \n    protected array $scene = [\n        'create' =\u003e ['username', 'email', 'password'],\n        'update' =\u003e ['username', 'email'],\n        'login' =\u003e ['email', 'password']\n    ];\n}\n\n// 使用验证器\n#[PostApi]\n#[RequestValidation(validator: UserValidator::class, scene: 'create')]\npublic function create() {}\n```\n\n## 🤝 与其他组件集成\n\n### 与 Route 组件集成\n\n验证组件会自动识别路由参数：\n\n```php\n#[GetApi]\n#[RequestValidation(rules: [\n    'page' =\u003e 'integer|min:1|default:1',\n    'size' =\u003e 'integer|min:1|max:100|default:20',\n    'keyword' =\u003e 'string|max:50'\n])]\npublic function index() {}\n```\n\n### 与 Swagger 组件集成\n\n验证规则会自动转换为 OpenAPI 参数定义：\n\n- `required` → required: true\n- `integer` → type: integer\n- `min/max` → minimum/maximum\n- `enum/in` → enum 数组\n- 字段描述 → description\n\n## ⚡ 性能优化\n\n- **规则缓存** - 编译后的规则缓存复用\n- **懒加载** - 按需加载验证器\n- **批量验证** - 一次验证所有规则\n- **智能短路** - 失败即停止后续验证\n\n## 🛠️ 配置\n\n在 `config/autoload/validate.php` 中配置：\n\n```php\nreturn [\n    // 默认错误码\n    'error_code' =\u003e 422,\n    \n    // 默认错误消息\n    'error_message' =\u003e '验证失败',\n    \n    // 是否返回所有错误\n    'return_all_errors' =\u003e true,\n    \n    // 自定义错误格式\n    'error_format' =\u003e function ($errors) {\n        return [\n            'code' =\u003e 422,\n            'message' =\u003e '验证失败',\n            'errors' =\u003e $errors\n        ];\n    }\n];\n```\n\n## 📝 最佳实践\n\n1. **规则组织**\n   - 简单验证用注解\n   - 复杂验证用验证器类\n   - 共用规则抽取为基类\n\n2. **错误处理**\n   - 提供友好的错误提示\n   - 使用字段描述而非字段名\n   - 支持多语言错误消息\n\n3. **性能考虑**\n   - 合理使用验证场景\n   - 避免过度复杂的正则\n   - 大数据量考虑分批验证\n\n## 🐛 常见问题\n\n1. **验证不生效**\n   - 检查注解是否正确导入\n   - 确认中间件是否注册\n   - 验证规则语法是否正确\n\n2. **类型转换失败**\n   - 检查数据类型是否匹配\n   - 使用 `nullable` 处理可选字段\n   - 注意 `dateType` 设置\n\n3. **自定义规则不工作**\n   - 确认规则已注册\n   - 检查规则名称是否冲突\n   - 验证闭包返回值\n\n## 📄 许可证\n\nMIT License\n\n## 🤝 贡献\n\n欢迎提交 Issue 和 Pull Request！","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperf-plus%2Fvalidate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperf-plus%2Fvalidate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperf-plus%2Fvalidate/lists"}