路由系统

Viswoole 路由系统是框架的核心组件之一，负责将 HTTP 请求映射到对应的处理器（控制器方法或闭包）。路由系统支持配置文件注册与注解声明两种方式，并提供路由分组、中间件、动态参数、API 文档自动生成等能力。

架构概览

text
HTTP 请求
    │
    ▼
┌─────────────────────────────────────┐
│  1. 路径规范化（大小写 / 扩展名处理）   │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│  2. 静态路由表查找                    │
└─────────────────┬───────────────────┘
                  │ 未命中
                  ▼
┌─────────────────────────────────────┐
│  3. 动态路由正则匹配（按段数筛选）       │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│  4. 校验 Method / Domain / Suffix    │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│  5. 合并动态参数                      │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│  6. 执行中间件链 → 调用处理器          │
└─────────────────────────────────────┘

两种注册方式

方式适用场景定义位置
配置文件路由集中管理、快速原型config/route/route.php
注解路由控制器绑定、自动发现控制器类/方法的 PHP 8 注解

两种方式可以混合使用，最终合并为统一的路由表。

核心特性

  • 多协议支持：GET / POST / PUT / DELETE / PATCH / OPTIONS / HEAD
  • 路由分组：公共前缀、中间件批量挂载
  • 动态参数：必选 /user/{id} 与可选 /user/{id?} 参数
  • 域名路由：按域名隔离路由规则
  • 伪静态后缀：可配置 URL 后缀白名单（如 .html）
  • 路由缓存：生产环境缓存编译后的路由表，提升匹配性能
  • API 文档自动生成：基于注解解析，输出接口文档

快速开始

配置文件方式

php
// config/route/route.php
use Viswoole\Router\Facade\Router;

// 注册 GET 路由
Router::get('/hello', function () {
    return 'Hello, Viswoole!';
});

// 注册控制器路由
Router::get('/user/info', [UserController::class, 'info']);

注解方式

php
#[Controller(prefix: '/api/v1')]
class UserController
{
    #[RouteMapping(paths: ['/info'], method: ['GET'], title: '用户信息')]
    public function info(): array
    {
        return ['id' => 1, 'name' => 'Viswoole'];
    }
}

访问 GET /api/v1/info 即可调用 info 方法。

文档导航

文档说明
配置文件路由在 route.php 中手动注册路由的完整指南
注解路由通过 PHP 8 注解声明路由的用法详解
路由分组分组前缀、中间件、域名绑定的使用方式
API 文档生成自动生成 API 接口文档的配置与定制