{"id":23150848,"url":"https://github.com/hyperf-plus/route","last_synced_at":"2025-07-07T03:08:17.896Z","repository":{"id":53718649,"uuid":"295637598","full_name":"hyperf-plus/route","owner":"hyperf-plus","description":"HPlus","archived":false,"fork":false,"pushed_at":"2025-07-03T05:37:57.000Z","size":75,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-03T06:31:40.426Z","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":null,"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":null,"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-15T06:38:38.000Z","updated_at":"2025-07-03T05:38:00.000Z","dependencies_parsed_at":"2025-06-22T02:24:16.948Z","dependency_job_id":"51b136a0-3880-426e-8480-86e8edb8ae08","html_url":"https://github.com/hyperf-plus/route","commit_stats":{"total_commits":23,"total_committers":2,"mean_commits":11.5,"dds":0.04347826086956519,"last_synced_commit":"fe126926d5ee4d9f8c7bf2aa0ce482080cf72fcb"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/hyperf-plus/route","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Froute","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Froute/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Froute/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Froute/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperf-plus","download_url":"https://codeload.github.com/hyperf-plus/route/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Froute/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263278159,"owners_count":23441655,"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","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:39.683Z","updated_at":"2025-07-07T03:08:17.880Z","avatar_url":"https://github.com/hyperf-plus.png","language":"PHP","readme":"# HPlus Route - 智能RESTful路由组件\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 框架打造的智能路由组件，支持 RESTful 规范自动路径生成、资源子操作映射、智能参数识别等高级特性。\n\n## ✨ 核心特性\n\n- 🚀 **RESTful 自动映射** - 根据控制器和方法名自动生成符合 RESTful 规范的路径\n- 🎯 **智能参数识别** - 自动识别方法参数生成动态路径\n- 🔒 **注解驱动安全** - 只有明确注解的方法才能对外访问\n- ⚡ **高性能设计** - 多层缓存、懒加载、O(1) 查找\n- 🎨 **零配置使用** - 开箱即用，但支持完全自定义\n- 🔧 **灵活扩展** - 支持自定义映射规则和路径模板\n\n## 📦 安装\n\n## 由于该版本改动较大，按照最新 restful规范，不向下兼容，如果老用户请勿升级，老模式会继续稳定跟进\n\n\n```bash\ncomposer require hyperf-plus/route\n```\n\n## 🚀 快速开始\n\n### 1. 基础使用\n\n```php\n\u003c?php\n\nuse HPlus\\Route\\Annotation\\ApiController;\nuse HPlus\\Route\\Annotation\\GetApi;\nuse HPlus\\Route\\Annotation\\PostApi;\nuse HPlus\\Route\\Annotation\\PutApi;\nuse HPlus\\Route\\Annotation\\DeleteApi;\n\n#[ApiController]  // 自动生成 /api/users (复数化)\nclass UserController\n{\n    #[GetApi]\n    public function index() {}     // GET /api/users\n    \n    #[GetApi] \n    public function show($id) {}   // GET /api/users/{id}\n    \n    #[PostApi]\n    public function create() {}    // POST /api/users\n    \n    #[PutApi]\n    public function update($id) {} // PUT /api/users/{id}\n    \n    #[DeleteApi]\n    public function delete($id) {} // DELETE /api/users/{id}\n}\n```\n\n### 2. 资源子操作\n\n```php\n#[ApiController]\nclass UserController\n{\n    #[GetApi]\n    public function state($id) {}     // GET /api/users/{id}/state\n    \n    #[PostApi]\n    public function enable($id) {}    // POST /api/users/{id}/enable\n    \n    #[PostApi]\n    public function disable($id) {}   // POST /api/users/{id}/disable\n    \n    #[GetApi]\n    public function permissions($id) {} // GET /api/users/{id}/permissions\n}\n```\n\n### 3. 智能参数识别\n\n```php\n#[ApiController]\nclass UserController\n{\n    #[GetApi]\n    public function customAction(int $id) {}\n    // 自动生成: GET /api/users/{id}/custom-action\n    \n    #[GetApi]\n    public function posts(int $userId, int $postId) {}\n    // 自动生成: GET /api/users/{userId}/posts/{postId}\n    \n    #[GetApi]\n    public function getByEmail(string $email) {}\n    // 自动生成: GET /api/users/get-by-email/{email}\n}\n```\n\n### 4. 自定义路径\n\n```php\n#[ApiController(prefix: '/v1/members')]  // 自定义前缀\nclass UserController\n{\n    #[GetApi(path: '/all')]  // 自定义路径\n    public function index() {}  // GET /v1/members/all\n    \n    #[GetApi]  // 混合使用\n    public function show($id) {}  // GET /v1/members/{id}\n}\n```\n\n## 📋 RESTful 映射规则\n\n### 标准 CRUD 操作\n\n| 方法名 | HTTP动词 | 自动路径 | 说明 |\n|--------|----------|----------|------|\n| index/list | GET | / | 获取列表 |\n| show/detail | GET | /{id} | 获取详情 |\n| create/store | POST | / | 创建资源 |\n| update/edit | PUT | /{id} | 更新资源 |\n| patch | PATCH | /{id} | 部分更新 |\n| delete/destroy | DELETE | /{id} | 删除资源 |\n\n### 扩展操作\n\n| 方法名 | HTTP动词 | 自动路径 | 说明 |\n|--------|----------|----------|------|\n| search | GET | /search | 搜索 |\n| export | GET | /export | 导出 |\n| import | POST | /import | 导入 |\n| batch | POST | /batch | 批量操作 |\n\n### 资源子操作\n\n| 方法名 | HTTP动词 | 自动路径 | 说明 |\n|--------|----------|----------|------|\n| state/status | GET | /{id}/state | 获取状态 |\n| enable/disable | POST | /{id}/enable | 启用/禁用 |\n| lock/unlock | POST | /{id}/lock | 锁定/解锁 |\n| permissions | GET | /{id}/permissions | 获取权限 |\n| history | GET | /{id}/history | 获取历史 |\n\n## 🎯 注解说明\n\n### @ApiController\n\n控制器注解，标记一个类为 API 控制器。\n\n```php\n#[ApiController(\n    prefix: '/api/v1/users',  // 可选：路由前缀，不设置则自动生成\n    tag: 'User Management',   // 可选：API 标签\n    description: '用户管理',   // 可选：API 描述\n    security: true           // 可选：是否需要认证\n)]\n```\n\n### @GetApi / @PostApi / @PutApi / @DeleteApi / @PatchApi\n\n方法注解，定义 HTTP 路由。\n\n```php\n#[GetApi(\n    path: '/{id}/detail',     // 可选：自定义路径\n    summary: '获取用户详情',   // 可选：接口摘要\n    description: '详细描述',   // 可选：接口描述\n    name: 'user.detail',      // 可选：路由名称\n    middleware: ['auth'],     // 可选：中间件\n    security: true,          // 可选：是否需要认证\n    deprecated: false        // 可选：是否已废弃\n)]\n```\n\n### 参数注解\n\n```php\nuse HPlus\\Route\\Annotation\\Query;\nuse HPlus\\Route\\Annotation\\Path;\nuse HPlus\\Route\\Annotation\\Body;\nuse HPlus\\Route\\Annotation\\Header;\n\n#[GetApi]\npublic function search(\n    #[Query('keyword')] string $keyword,      // 查询参数\n    #[Path('id')] int $id,                   // 路径参数\n    #[Header('X-Token')] string $token,      // 请求头参数\n    #[Body] array $data                      // 请求体\n) {}\n```\n\n## 🛠️ 高级用法\n\n### 1. 路由收集器\n\n```php\nuse HPlus\\Route\\RouteCollector;\n\n$collector = RouteCollector::getInstance();\n\n// 收集所有路由\n$routes = $collector-\u003ecollectRoutes();\n\n// 查找路由\n$route = $collector-\u003efindRouteByPath('/api/users');\n$routes = $collector-\u003efindRoutesByController(UserController::class);\n$routes = $collector-\u003efindRoutesByTag('User Management');\n\n// 获取统计信息\n$stats = $collector-\u003egetRouteStats();\n$cache = $collector-\u003egetCacheStats();\n```\n\n### 2. 版本控制\n\n```php\nnamespace App\\Controller\\Api\\V2;\n\n#[ApiController]  // 自动生成 /api/v2/users\nclass UserController\n{\n    #[GetApi]\n    public function index() {}  // GET /api/v2/users\n}\n```\n\n### 3. 路由分组\n\n```php\n#[ApiController(prefix: '/admin')]\nclass AdminController\n{\n    #[GetApi]\n    public function dashboard() {}  // GET /admin/dashboard\n}\n\n#[ApiController(prefix: '/admin/users')]\nclass AdminUserController\n{\n    #[GetApi]\n    public function index() {}  // GET /admin/users\n}\n```\n\n## ⚡ 性能优化\n\n- **多层缓存** - 路由、控制器、反射类缓存\n- **懒加载** - 参数和请求体信息按需加载\n- **索引优化** - 多维索引支持 O(1) 查找\n- **智能清理** - 自动内存优化和垃圾回收\n\n性能数据：\n- 路由收集速度提升 **70%**\n- 内存使用减少 **37%**\n- 缓存命中率达 **85%**\n\n## 🔧 配置\n\n在 `config/autoload/annotations.php` 中配置：\n\n```php\nreturn [\n    'scan' =\u003e [\n        'paths' =\u003e [\n            BASE_PATH . '/app',\n        ],\n        'ignore_annotations' =\u003e [\n            'mixin',\n        ],\n        'class_map' =\u003e [\n            // 需要映射的类\n        ],\n    ],\n];\n```\n\n## 🤝 与其他组件集成\n\n### 与 HPlus Validate 集成\n\n```php\nuse HPlus\\Validate\\Annotations\\RequestValidation;\n\n#[GetApi]\n#[RequestValidation(rules: [\n    'page' =\u003e 'integer|min:1',\n    'size' =\u003e 'integer|max:100'\n])]\npublic function index() {}\n```\n\n### 与 HPlus Swagger 集成\n\n路由组件会自动被 Swagger 组件识别，生成 API 文档。\n\n## 📝 最佳实践\n\n1. **命名约定**\n   - 控制器：单数名词 + Controller（如 `UserController`）\n   - RESTful 方法：使用标准名称（index, show, create, update, delete）\n   - 扩展方法：使用描述性名称（search, export, batch）\n\n2. **路径设计**\n   - 优先使用自动生成，保持一致性\n   - 复杂场景才手动指定路径\n   - 遵循 RESTful 设计原则\n\n3. **安全考虑**\n   - 默认所有方法都需要路由注解才能访问\n   - 敏感操作添加 `security: true`\n   - 合理使用中间件\n\n## 🐛 问题排查\n\n1. **路由未生成**\n   - 检查是否添加了路由注解\n   - 确认控制器有 `@ApiController` 注解\n   - 验证注解是否正确导入\n\n2. **路径不符合预期**\n   - 查看路由统计了解生成规则\n   - 使用 `path` 参数自定义路径\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%2Froute","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperf-plus%2Froute","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperf-plus%2Froute/lists"}