http_router快速入门教程:5分钟从0到1构建Restful路由表(附完整示例)
http_router快速入门教程:5分钟从0到1构建Restful路由表(附完整示例)
http_router 是一个面向仓颉语言的轻量级 Restful 路由解析库,提供路由注册与路由匹配两大核心能力。它基于基数树(Radix Tree)结构,把 URL 路径高效映射到对应处理函数,并支持 /hello/:name 这类动态路径的参数提取。本文带你从 0 到 1 走一遍:5 分钟内注册第一张 Restful 路由表并完成一次完整的路由匹配,帮助仓颉新手快速上手 http_router 路由入门。
一、项目速览:http_router 能做什么?
http_router 解耦出 Restful 路径解析部分代码,为仓颉项目提供标准化的路由注册、路由匹配能力。核心 API 一览:
| 组件 | 说明 | 所在位置 |
|---|---|---|
Node<T> |
路由节点,路由表的核心 | src/node.cj |
addHandler |
注册一条路由 | src/node.cj |
getHandler |
匹配路由,返回处理函数 | src/node.cj |
RouterValueSetter |
提取路径参数值的回调 | src/types.cj |
dump |
打印路由树结构,便于调试 | src/util.cj |
其中泛型 T 是路由处理器类型,你可以自定义处理函数类型,让同一张路由表适配不同业务。
二、环境准备:一分钟获取项目
http_router 需要仓颉编译器(cjc 1.1.0 及以上,版本配置见 cjpm.toml)。克隆源码即可开始:
git clone https://gitcode.com/Cangjie-SIG/http_router
项目使用 cjpm 进行包管理,依赖与版本信息都在 cjpm.toml 中(当前版本 0.1.1,兼容仓颉 1.0.0,版本演进记录见 CHANGELOG)。
三、第一步:创建路由节点,注册路由
创建一个根节点 Node<DefaultHandler>,然后用 addHandler 注册三条 Restful 路径:
let root = Node<DefaultHandler>()
root.addHandler("/", index)
root.addHandler("/hello/:name", hello)
root.addHandler("/file/upload/image", upload)
dump(root)
/:根路径/hello/:name:参数路由,:name是动态参数/file/upload/image:多级静态路径
dump 会把内部路由树打印出来,非常适合新手观察结构 ✅。路由注册的完整实现在 src/node.cj。
四、第二步:匹配路由,提取参数
收到请求路径后,调用 getHandler 完成路由匹配:
let (helloHandler, _) = root.getHandler("/hello/changeden", valueSetter)
helloHandler?()
getHandler 返回两个值:匹配到的处理器、以及一个建议追加尾部 / 的布尔标记。对于路径参数,传入 RouterValueSetter 回调即可自动取出 :name 的值:
{
key, value => println("key: ${key} , value: ${value}")
}
匹配 /hello/changeden 时会得到 name: changeden,可直接交给业务逻辑使用,无需自己写字符串解析。
五、第三步:多张路由表组织 GET/POST(完整示例)
真实的 Restful 服务需要按请求方法区分路由。用 HashMap 为每种方法维护一张路由表即可:
let rootMap = HashMap<HttpMethod, Node<DefaultHandler>>()
registerHandler(rootMap, HttpMethod.GET, "/", index)
registerHandler(rootMap, HttpMethod.POST, "/hello/:name", hello)
getHandler(rootMap, HttpMethod.POST, "/hello/changeden")?()
核心思路很简单:rootMap 中没有该方法的路由表时,先 new 一个 Node 再注册。完整的可运行示例在 src/main.cj,其中 HttpMethod 枚举(GET/POST/PUT)的定义见 src/main.cj,可直接复制复用。
六、参数路由与 Catch-All 通配符:记住 3 条规则
- 参数路由
:param:参数名不能为空,且每个路径段只允许一个通配符,实现见 src/node.cj - Catch-All 通配符
*:只能放在路径末尾,例如/files/*filepath,用于匹配剩余整段路径 - 冲突自动检测:新路径与已有通配符冲突、或同一路径重复注册时,http_router 会在注册阶段就
panic并给出明确原因,把问题挡在上线前 🛡️
七、常见问题速答
Q1:路由没匹配到会怎样?
getHandler 返回 None,业务侧做空值判断即可,不会崩溃。
Q2:getHandler 返回的 Bool 有什么用?
它是尾部斜杠建议信号。例如注册了 /file/ 而请求是 /file 时,路由表会建议重定向到带尾部 / 的路径,提升 Restful 规范一致性。
Q3:源码文件都是什么分工?
路由树插入与匹配逻辑在 src/node.cj;NodeType 节点类型枚举和 RouterValueSetter 类型定义在 src/types.cj;dump 调试工具与 countParams 参数计数在 src/util.cj;len / panic 等基础工具函数在 src/like_golang.cj。完整 API 文档参考 README.md。
至此,你已经掌握了 http_router 的快速入门路径:注册路由 → 匹配路由 → 提取参数 → 多方法路由表组织。把上面的示例跑通,就拥有了一个可复用的 Restful 路由基础。