路由配置

路由的全部全局配置集中在 config/router.php，涵盖路径匹配规则、默认请求方法、路由定义文件加载、路由缓存与 API 文档开关。本篇为配置参考，注册路由的具体写法见编程式路由与注解路由。

默认配置

以下是框架自带的 config/router.php 完整内容：

php
<?php
declare(strict_types=1);

return [
  // 是否区分大小写
  'case_sensitive' => false,
  // 伪静态后缀，支持通过数组设置多个
  'suffix' => '*',
  // 域名校验，例如 ['www.baidu.com']
  'domain' => '*',
  // HTTP 请求方法
  'method' => '*',
  // 默认的路由变量正则表达式
  'default_pattern_regex' => '[\w\.]+',
  // 要加载的路由定义文件
  'route_config_files' => [
    BASE_PATH . '/config/route/route.php'
  ],
  // 路由缓存配置
  'cache' => [
    // 是否开启路由缓存
    'enable' => false,
    // 路由缓存存放目录
    'path' => BASE_PATH . '/runtime/route'
  ],
  // 路由文档配置
  'api_doc' => [
    'enable'   => false,
    'returned' => [],
    'header'   => [],
    'query'    => [],
    'body'     => [],
  ],
];

配置键总表

参数类型默认值说明
case_sensitiveboolfalse路径静态段是否区分大小写
suffixstring|array'*'全局伪静态后缀，'*' 表示不限制
domainstring|array'*'全局域名校验，'*' 表示不限制
methodstring|array'*'未显式声明请求方法时的默认方法
default_pattern_regexstring'[\\w\\.]+'动态路由变量未被 patterns 约束时的默认正则
route_config_filesarray['BASE_PATH/config/route/route.php']编程式路由定义文件列表
cache.enableboolfalse是否开启注解路由缓存
cache.pathstringBASE_PATH/runtime/route路由缓存文件存放目录
api_doc.enableboolfalse是否启用 API 文档生成
api_doc.returnedarray[]全局返回值声明（Returned 实例数组）
api_doc.headerarray[]全局请求头参数
api_doc.queryarray[]全局查询参数
api_doc.bodyarray[]全局请求体参数

路径匹配相关

case_sensitive

默认 false：注册路由时静态路径段会被转为小写，匹配时请求路径同样小写后查表，因此 /User/List 与 /user/list 等价。动态变量段（如 {id}）始终保留原始大小写——变量名需要与处理器参数名、patterns 约束键对齐，不会随配置被小写化。

设为 true 后严格按注册路径区分大小写匹配。

suffix（伪静态后缀）

控制 URL 允许携带的后缀。默认 '*' 不限制；设为 ['html', 'shtml'] 时仅允许这些后缀，请求 /news.html 会先剥离后缀再匹配路由 /news，后缀不合法时该候选路径放弃并尝试其他匹配，最终失败则回退兜底路由。

每条路由也可通过 setSuffix() 或注解 suffix 参数覆盖全局配置。

domain（域名绑定）

限制路由生效的域名，默认 '*' 不限制。设为 ['api.example.com'] 后，仅该域名的请求能命中路由。路由级可通过 setDomain() 或注解 domain 参数覆盖。

method（默认请求方法）

未显式声明请求方法的路由（包括注解路由未写 method 参数时）继承此配置。默认 '*' 表示接受任意方法，可改为 'GET' 收紧：

php
// 所有未声明 method 的路由仅接受 GET
'method' => 'GET',

default_pattern_regex

动态变量 {id} 未被 setPatterns() 约束时使用该正则校验变量值，默认 [\w\.]+（允许字母、数字、下划线与点号）。例如收紧为仅允许数字：

php
'default_pattern_regex' => '\d+',

INFO

config/ 下的配置文件支持 php / yml / ini / json 格式，文件名即一级配置键，也支持在 config/lazy/ 中懒加载。详见配置文件。

route_config_files（路由定义文件）

数组中的每个文件都会在路由初始化阶段通过 require_once 加载，文件内使用 Router 门面注册路由。默认只有一个文件，可按模块拆分后追加：

php
'route_config_files' => [
  BASE_PATH . '/config/route/route.php',
  BASE_PATH . '/config/route/admin.php',   // 后台模块路由
],

路由缓存

注解路由需要在启动时扫描 app/Controller 目录并反射解析注解，路由较多时该过程有可感知的开销。开启缓存后，每个控制器的路由组会被序列化写入磁盘，下次启动直接反序列化恢复：

php
'cache' => [
  'enable' => true,
  'path'   => BASE_PATH . '/runtime/route',
],

缓存机制要点：

  • 缓存文件按 服务名分目录 存放（如 runtime/route/http/），文件名为控制器完全限定类名（命名空间分隔符替换为下划线），扩展名 .cache
  • 缓存哈希由 框架版本号 + 控制器文件内容哈希 共同决定：修改控制器代码或升级框架都会使缓存自动失效并重新解析
  • 缓存反序列化仅允许恢复路由结构相关的框架类（带类白名单），防止被篡改的缓存文件触发对象注入

WARNING

缓存哈希已覆盖「控制器文件变更」与「框架升级」两类场景，正常情况下无需手动清理。但若框架内部路由结构跨版本不兼容，或缓存目录被异常写入，可执行清理命令：

bash
php viswoole router:clear-cache          # 清除全部服务的路由缓存
php viswoole router:clear-cache http     # 仅清除指定服务的缓存

INFO

Swoole 服务常驻内存，路由表在进程启动时构建。修改 config/router.php、路由定义文件或控制器注解后，需重启服务生效；详见部署与生产配置。

api_doc（API 文档配置）

api_doc 下的 enable 控制文档生成开关，returned / header / query / body 分别定义全局返回值声明与全局请求参数。各键的格式与参数声明方式详见 API 文档生成。

下一步