掌握unjs/h3路由系统：从基础路由到动态匹配的完整指南

unjs/h3是一个为高性能和可移植性构建的极简HTTP框架，其路由系统是构建高效Web应用的核心。本文将详细介绍h3路由系统的基础知识、动态路由实现以及最佳实践，帮助开发者快速掌握这一强大功能。

快速了解h3路由系统

h3的路由系统由🌳 Rou3提供支持，这是一个超快速且轻量级的路由匹配引擎。与传统路由系统相比，h3路由具有近乎原生的性能表现，在提供丰富功能的同时几乎没有性能损耗。

基础路由注册方法

h3提供了多种方式来注册路由处理程序，适应不同的使用场景：

使用HTTP方法注册

最常用的方式是直接使用HTTP方法名来注册路由：

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

使用on方法注册

也可以使用on方法显式指定HTTP方法：

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

多方法支持

可以为同一个路由注册多个不同HTTP方法的处理程序：

app
  .get("/hello", () => "GET Hello world!")
  .post("/hello", () => "POST Hello world!")
  .all("/hello", () => "Any other method!");

动态路由参数

h3支持定义动态路由参数，使路由更加灵活：

命名参数

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

// [GET] /hello/Bob => "Hello, Bob!"
app.get("/hello/:name", (event) => {
  return `Hello, ${event.context.params.name}!`;
});

可选参数

使用*定义可选参数：

app.get("/hello/*", (event) => `Hello!`);

通配符路由

当需要匹配多级子路由时，可以使用**前缀：

app.get("/hello/**", (event) => `Hello ${event.context.params._}!`);

此路由将匹配/hello、/hello/world、/hello/123、/hello/world/123等多种路径形式，event.context.params._将存储完整的通配符内容。

路由元数据

在注册路由时，可以定义可选的元数据，这些元数据可从任何中间件访问：

import { H3 } from "h3";

const app = new H3();

app.use((event) => {
  console.log(event.context.matchedRoute?.meta); // { auth: true }
});

app.get("/", (event) => "Hi!", { meta: { auth: true } });

路由匹配优先级

h3路由系统会自动选择最具体的路由进行匹配。例如，/hello/bob会优先匹配/hello/:name，而不是/hello/**通配符路由。

实际应用示例

查看[examples/router.mjs]中的完整示例，了解如何在实际项目中组织和使用h3路由系统。此外，[docs/1.guide/1.basics/2.routing.md]提供了更详细的路由系统文档。

通过掌握h3的路由系统，开发者可以构建出既高效又灵活的Web应用，充分发挥这一极简框架的性能优势。无论是简单的静态路由还是复杂的动态路由需求，h3都能提供直观且高性能的解决方案。