# `naisi_route_compile`

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

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

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

## 函数签名

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

## 调用前提

应用入口先调用 [naisi_is_ext_license_valid](/web/developers/naisilib/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；未授权、输入无效或处理失败时返回空数组。

## 调用示例

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

```php
$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`