路由：静态表 + 动态 pattern + 方法槽

本章导读

17.1 引入

"路由要不要进宿主"是个真问题：进了，灵活的路径需求（正则、前缀、通配）就开始挤压配置系统；不进，每个应用要自己写一遍。XServer 的选择是提供零件、不提供整机：xrtMap（哈希表）管精确匹配，xrtPattern（批量预编译的模式匹配器）管参数化路径——20 行装配代码就能得到一个生产级路由器，而特殊需求（正则路由、版本前缀）随时可以自己长出来。

17.2 双表模式

static void RouteHTTP_Init(void)
{
    G_StaticRouteTableHTTP = xrtMapCreate(sizeof(RouteInfoHTTP));

    /* 静态表：精确 URI（xrtMap 哈希）*/
    AddStaticRouteHTTP("/api/v1/items", XHTTP_METHOD_GET,  Handle_API_List);
    AddStaticRouteHTTP("/api/v1/items", XHTTP_METHOD_POST, Handle_API_Add);

    /* 动态表：{id} 段捕获（注册后统一编译）*/
    AddDynamicRouteHTTP("/api/v1/items/{id}",
        XHTTP_METHOD_GET,                    Handle_API_Item);
    AddDynamicRouteHTTP("/api/v1/items/{id}",
        XHTTP_METHOD_PUT | XHTTP_METHOD_PATCH, Handle_API_Item_Update);
    AddDynamicRouteHTTP("/api/v1/items/{id}",
        XHTTP_METHOD_DELETE,                 Handle_API_Item_Delete);

    /* 段内捕获也支持：/api/v1/file/{name}.txt */
    AddDynamicRouteHTTP("/api/v1/file/{name}.txt",
        XHTTP_METHOD_GET, Handle_API_File);

    /* 动态路由必须在全部注册完成后编译一次 */
    (void)RouteHTTP_Compile();
}

刚才发生了什么：静态表 O(1) 命中；动态表在 RouteHTTP_Compile 里经 xrtPatternCompileMany 批量编译成不可变匹配器——之后的匹配耗时只与路径长度相关，与路由条数无关。处理器签名是 demo 惯例：(XS_HttpReq*, const RouteParamHTTP* arrParam, uint32 iParamCount)，arrParam 携带 {id} 捕获的视图。

17.3 方法槽与 405

• 每个 (URI, 方法) 是一个槽——同 URI 多方法分别注册；URI 与方法都重复时后注册覆盖旧回调并告警
• 方法掩码自由组合：PUT | PATCH 共槽；XHTTP_METHOD_CRUD（五方法）与 XHTTP_METHOD_ANY（含扩展方法）是聚合宏（枚举参考）
• URI 命中但方法不中 → 405 + Allow 头：Allow 由该 URI 的全部已注册方法聚合生成——第 2 章 HEAD /json → 405, Allow: GET 的出处

17.4 匹配顺序与性能

性能数字（routebench 实测，3 轮 × 10000 请求均值）：

平坦的秘诀：静态表哈希 O(1)；动态表批量编译后匹配 O(路径长度)——万级路由只比十级贵 41%，而对照栈在万级普遍退化一个量级。

17.5 契约

• 编译线：动态路由注册完必须 Compile 一次；之后路由表不可变（换代重建是热重载的职责）。
• 顺序线：静态 → 动态 → FALLBACK；同一 URI 静态优先于动态。
• 参数线：arrParam 是请求级视图，回调内用完即弃。

常见错误

编程练习