H3初识——入门介绍之路由、路由元数据

简介

H3 提供了灵活且高性能的路由系统，支持多种 HTTP 方法、动态参数和中间件组合，适用于现代 Web 服务开发。

基本用法

import { H3, serve } from "h3";

const app = new H3();

// 定义 GET 路由
app.get("/", (context) => {
  return "Hello H3 路由!";
});

// 定义 POST 路由
app.post("/submit", async (context) => {
  const body = await context.req.json();
  return { message: "收到数据", data: body };
});

// 定义 all 路由
app.all("/all", (context) => {
  return "所有方法都可以访问此路由";
});

// 定义 any 路由
app.any("/any", (context) => {
  return "所有方法都可以访问此路由";
});

serve(app, { port: 3000 });

路由参数

H3 支持动态路由参数：

app.get("/user/:id", (context) => {
  const { id } = context.params;
  return `用户ID: ${id}`;
});

H3 支持通配符路由：

app.get("/user/*", (context) => {
  const { path } = context.params;
  return `通配符路径: ${path}`;
});

路由元数据

在 H3 中，可以为路由添加自定义元数据（meta），用于权限控制、文档生成等场景。以下是使用示例：

function withAuth(handler, meta) {
  return (event) => {
    if (meta.requiresAuth) {
      // 获取 cookie 中的 token
      const token = getCookie(event, "token");
      // 这里可以做更复杂的 token 校验，比如 JWT 验证
      if (!token || token !== "123456") {
        event.res.headers.set("Content-Type", "text/plain; charset=utf-8");
        return "未授权，token无效";
      }
    }
    event.res.headers.set("Content-Type", "text/plain; charset=utf-8");
    return handler(event);
  };
}

app.get(
  "/admin",
  withAuth(
    (event) => {
      return "管理员页面";
    },
    { requiresAuth: true, role: "admin", description: "管理员专用页面" }
  )
);

app.get(
  "/public",
  withAuth(
    (event) => {
      return "公开页面";
    },
    { requiresAuth: false, description: "无需登录的页面" }
  )
);

说明

• meta 字段可以自定义任意结构，用于存储与路由相关的附加信息。
• 结合中间件，可以实现权限、日志、自动文档等高级功能。

参考链接

• H3 官方中文文档