http_router快速入门教程:5分钟从0到1构建Restful路由表(附完整示例)

原创2026-09-23 20:57:521,621 阅读
文章标签:后端路由Web框架

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 路由基础。

登录后查看全文
http_router