naisi_route_compile

遍历并规范化路由配置，按 HTTP 方法分组并用 URL 的 10 字符指纹作为路由键。

路由键为独立实现的 10 位小写 Base36 摘要，不调用字符串指纹或 UA 摘要函数。 URL 指纹使用许可项目私有盐和当前构建的内部指纹材料，不使用服务器设备机器指纹、 Customer ID、Build ID 或 License ID。不同设备要得到相同结果，必须使用相同路由输入、 default_return、项目私有盐、内部指纹材料和算法版本。

注意：10 字符路由指纹不是无碰撞的全局唯一 ID。编译结果用于缓存或持久化时，项目 私有盐或内部指纹材料变化会使旧路由键失效，应重新编译并原子替换缓存。本函数在 访问令牌建立前运行，但仍要求有效的启动许可能力。

函数签名

function naisi_route_compile(array $route_list, string $default_return): array

调用前提

应用入口先调用 naisi_is_ext_license_valid 并确认返回 true。认证 Agent 发布的许可与 heartbeat 快照，并建立或复用本请求的 BASIC 证明；不会读取许可文件或检查当前 Host。

授权类别：STARTUP_LICENSE；执行模式：BASIC。许可不代替登录、租户或权限上下文；身份与数据要求见本页参数及用途说明。

参数

$route_list

• 类型：array
• 必填：是
• 默认值：无
• 方向：输入参数。

项目路由配置列表。空数组是有效输入并返回空编译结果；非空时，输入层级、路由顺序、URL、请求方法、控制器、函数、return、middleware 和 expand 等字段都会参与规范化结果，无效结构会导致编译失败。

$default_return

• 类型：string
• 必填：是
• 默认值：无
• 方向：输入参数。

路由未单独声明 return 时写入结果的默认返回标识；空字符串允许，路由列表为空时不会被使用。

返回值

类型：array

成功时返回按 HTTP 方法分组的路由数组，每个方法组以 URL 的 10 字符指纹为键，路由项包含 url_regexp、controller、function、return、middleware 和 expand；未授权、输入无效或处理失败时返回空数组。

调用示例

当前请求须满足上方调用前提；请检查实际返回值和引用输出，随机结果及数据包内容以运行环境为准。

$route_list = [
    '/api' => [
        '_expand' => ['middleware' => 'auth', 'version' => 'v1'],
        '/users' => ['request' => ['get' => '/User@index', 'post' => '/User@create'], 'return' => 'json'],
        '/users/$userId' => ['request' => ['get' => '/User@detail'], 'return' => 'json']
    ],
    '/health' => ['request' => ['get' => '/Health@index'], 'return' => 'json', 'middleware' => '']
];
$default_return = 'index';

$result = naisi_route_compile($route_list, $default_return);
var_export($result);

版本信息

• 自版本：1.0.6
• 实现模块：routing
• 授权类别：STARTUP_LICENSE / BASIC
• 失败回退：[]
• 文档同步：2026-10-18