unjs/h3 路由系统详解：从基础到动态路由实践

unjs/h3 路由系统详解：从基础到动态路由实践

h3 ⚡️ Minimal H(TTP) framework built for high performance and portability 项目地址: https://gitcode.com/gh_mirrors/h31/h3

什么是 h3 的路由系统

unjs/h3 是一个轻量级的 HTTP 框架，其路由系统是核心功能之一。路由系统负责将客户端请求映射到对应的处理函数上，根据请求的路径和方法进行精确匹配。

路由注册基础

h3 提供了多种方式来注册路由处理函数，开发者可以根据需求选择最适合的方式：

1. 方法快捷方式

最简洁的注册方式，直接使用对应 HTTP 方法的快捷方法：

app.get("/hello", () => "Hello world!");

这种方式会自动处理 GET 请求，其他 HTTP 方法如 POST、PUT、DELETE 等也有对应的方法。

2. 通用 on 方法

提供了更灵活的路由注册方式，可以显式指定 HTTP 方法：

app.on("GET", "/hello", () => "Hello world!");

3. 全方法处理

使用 all 方法可以注册一个处理所有 HTTP 方法的路由：

app.all("/hello", (event) => `处理 ${event.req.method} 请求`);

多路由处理实践

在实际开发中，我们经常需要为同一路径注册多个处理函数：

app
  .get("/api/user", getUserHandler)
  .post("/api/user", createUserHandler)
  .put("/api/user", updateUserHandler)
  .delete("/api/user", deleteUserHandler);

这种链式调用方式让代码更加清晰易读。

动态路由详解

动态路由是 Web 开发中非常实用的功能，h3 提供了强大的动态路由支持：

1. 命名参数

使用 : 前缀定义命名参数：

app.get("/product/:id", (event) => {
  const productId = event.context.params.id;
  // 根据 productId 查询数据库...
});

2. 可选参数

使用 * 定义可选参数：

app.get("/category/*", (event) => {
  // 匹配 /category 和 /category/anything
});

3. 通配路由

使用 ** 可以匹配多级路径：

app.get("/docs/**", (event) => {
  const path = event.context.params._; // 获取完整路径
  // 处理文档请求...
});

这种路由会匹配 /docs、/docs/getting-started、/docs/api/v1 等任意深度的路径。

路由匹配优先级

h3 的路由系统遵循以下匹配规则：

1. 静态路由优先于动态路由
2. 命名参数路由优先于通配路由
3. 更具体的路由优先于更通用的路由

例如：

• /user/profile 优先于 /user/:id
• /user/:id 优先于 /user/*

最佳实践建议

1. 路由组织：将相关路由分组组织，保持代码清晰
2. 参数验证：对动态路由参数进行验证和清理
3. 错误处理：为未匹配路由添加 404 处理
4. 性能考虑：高频访问的路由尽量使用静态路径

// 404 处理示例
app.use((event) => {
  event.res.statusCode = 404;
  return "页面未找到";
});

总结

unjs/h3 的路由系统虽然简洁，但功能强大且灵活。通过合理使用静态路由、动态路由和通配路由，开发者可以构建出结构清晰、易于维护的 Web 应用。掌握这些路由技术，能够帮助你在实际项目中更高效地处理各种 URL 请求场景。

h3 ⚡️ Minimal H(TTP) framework built for high performance and portability 项目地址: https://gitcode.com/gh_mirrors/h31/h3