H3 v2 Beta 深度解读基于 Web 标准完全重写的极简 HTTP 框架【免费下载链接】h3⚡️ Minimal H(TTP) framework built for high performance and portability项目地址: https://gitcode.com/GitHub_Trending/h31/h3H3 v2 beta 是 H3当前仓库 package.json 中版本为2.0.1-rc.28的一次里程碑式重构它彻底抛弃了以 Node.js API 为核心、以兼容层适配 Web 标准的旧架构转而完全基于 Request、src/handler.ts、src/middleware.ts 等深入剖析其设计动机、性能成果、类型系统、中间件/插件模型与迁移路径读完你将掌握 H3 v2 的核心 API 与底层实现原理。为什么需要 v2边缘计算时代下的 Web 标准觉醒H3 诞生于 2020 年底边缘 Worker 兴起之时。当时 H3 与 unjs/unenv 搭配让 Nitro 部署可以在 Worker 环境中运行 Node.js 兼容代码。自 v1.8详见 v1.8 发布说明该版本引入了toWebHandler/toPlainHandler适配器与 Web Streams 支持之后H3 对 Web 标准的支持持续增强但本质上仍然是以Node.js API 为第一公民、Web 标准为兼容层——这在 Node.js 主导 JavaScript 服务端运行时生态的年代是合理选择。如今情况已截然不同WinterTC 等组织推动的 Web 标准演进加上 Deno、Bun、以及最新 Node.js 对 Web 标准的原生支持使得服务端开发一等公民就是 Web 标准成为可能。v2 的重写带来的收益包括跨运行时互操作同一套代码在 Node.js、Deno、Bun、Cloudflare Workers 等环境行为一致跨框架兼容H3、Hono、Elysia 等基于 Web 标准的框架可以共享模式与心智模型跨环境代码复用前端与后端共享熟悉且一致的 API充分利用运行时原生原语Request、URL、Headers等无需垫片更轻松的 API 测试handler.fetch()直接构造Request、返回Response测试无需启动真实服务器。srvx弥合 Node.js 与 Web 标准之间最后一道鸿沟v2 重写面临的最大挑战是Node.js 自身没有内置 Web 标准的 HTTP 服务器接口。node:http需要一层适配器将 Node.js 的IncomingMessage桥接为 WebRequest并把 WebResponse通过 Node.jsServerResponse写出。官方为此实现了一个兼容层srvx官方基准数据显示该兼容层可达到原生node:http性能的 96.98%数据源自官方 srvx 基准仓库内可参考 test/bench/bench.ts 的同类测量方法论。Deno、Bun 与边缘 Worker 率先采纳了 Web 标准但由于当时缺乏足够完善的规范各运行时对扩展能力客户端 IP、服务器端口与 TLS 配置、WebSocket 升级等各自为政、接口不一。srvx 正是为此诞生的统一层在 Deno、Bun、Node.js、Service Workers、边缘 Workers 上以完全相同的方式工作同时提供运行时特有的扩展上下文。// 根据各运行时 export conditions 自动选择动态适配器 import { serve } from srvx; serve({ port: 3000, // tls: { cert: server.crt, key: server.key } fetch(req) { // 服务器扩展req.ip、req.waitUntil()、req.runtime?.{bun,deno,node,cloudflare,...} return new Response( Hello there!); }, });从仓库源码可以印证这一设计H3Event通过req.runtime暴露运行时特有上下文见 src/event.ts 的runtimegetter并转发waitUntil()调用package.json 的exports字段为deno、bun、workerd、browser、node、generic分别映射了不同的入口文件见 src/_entries/ 下的deno.ts、bun.ts、cloudflare.ts、service-worker.ts、node.ts、generic.ts这正是按运行时自动选择适配器的落地实现。[!TIP] 有了 srvx 统一运行时差异H3 可以保持精简专注于纯 Web 标准 API——这是 v2 架构的核心分工。H3 v2Tiny Server Composerv2 对 H3 自身的作用域做了大量精简聚焦于核心能力 为性能深度优化比羽毛更轻见下节基准数据 直观的类型化 handler、响应与错误处理 可复用的中间件与插件 高速路由➕ 内置工具函数❤️ 基于 Web 标准的最大化兼容性mount嵌套应用等。v2 的核心 API 变化是路由功能直接集成进 H3 核心。不再需要createApp()createRouter()两件套而是直接import { H3, serve } from h3; const app new H3().get(/, () ⚡️ Tadaa!); serve(app, { port: 3000 });从源码看src/h3.ts 中的H3类继承自H3CoreH3Core负责请求分发主流程fetch()→~request()→handler()→toResponse()而H3在构造时通过createRouter()来自 rou3 路由引擎初始化路由表。源码中还通过原型链动态为GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS、CONNECT、TRACE、QUERY全部十个方法生成app.get()、app.post()等便捷方法。app.all()则注册任意方法均可匹配的路由。性能层面还有一处值得注意的源码细节createDispatcher见 src/h3.ts会预组合中间件链——首次请求或调用use()/mount()后构建一次composeMiddleware结果并缓存后续请求直接复用避免每个请求都重复组合开销路由中间件与 handler 也在注册时通过composeHandler一次性组合。这正是 v2接近零成本性能设计的一部分。更轻以框架自身开销为基准的测量方法v2 采用了全新的基准测试方法不测量网络层而是测量框架本身引入的开销目标是把所有相关指标优化到没有框架时的基线水平。官方发布数据如下测量项H3 v1 H3 v2请求处理Node: 36 µsBun: 27 µsDeno: 7 msNode:7 µs快 5 倍Bun:3 µs快 9 倍Deno:1.2 µs快 156 倍打包体积min: 101 kBmingzip: 39.6 kBmin:9.1 kB减小 91%mingzip:3.6 kB减小 90%fetch 型 handler 可低至 min:5.2 kB/ mingzip:2.1 kB[!TIP] v2 处理请求的性能已与纯fetchhandler new URL(req.url).pathname做路由几乎一致——换句话说使用 H3 的功能几乎零性能成本。[!NOTE] 以上数据源自官方发布说明适用于 Web 标准目标的 H3 核心不含适配器主要用于官方内部优化参考。仓库内对应基准测试位于 test/bench 目录bench.ts、bench.test.ts等其中bench:node与bench:bun脚本见 package.json可用于复现核心开销测量。体积的大幅缩减与 v2 只依赖 rou3 srvx 两个最小依赖见 package.json dependencies以及基于 Web 标准重写密不可分——不再需要庞大的 Node.js 兼容垫片。类型化 Web 标准fetchdts 与 defineHandlerv2 全面采用Request、Response、URL、Headers等 Web 标准 API不再在标准之上发明新的约定。同时官方发起了一个强类型化 Web API 的计划fetchdts并将其集成进 H3把标准与类型便利结合起来。import { defineHandler } from h3; const handler defineHandler(async (event) { // URL 解析 const { pathname, searchParams } event.url; // 访问请求头编辑器里试试自动补全 const accept event.req.headers.get(Accept); // 读取请求体 const bodyStream await event.req.body; const bodyText await event.req.text(); const bodyJSON await event.req.json(); const bodyFormData await event.req.formData(); // 访问运行时特有上下文 const { deno, bun, node } event.req.runtime; // 准备响应h3 智能处理 event.res.headers.set(Content-Type, application/json); return { hello: web }; });defineHandler定义出的 handler 自带.fetch方法源码见 src/handler.ts 的handlerWithFetch它接受字符串、URL或Request作为输入构造H3Event后经toResponse归一化为Response可以直接以函数式 Web handler的身份独立使用const response await handler.fetch(/); // 类型化响应{ hello: string; } const json await response.json();[!TIP] handler 可以脱离 H3 核心独立使用——即使不引入完整框架defineHandler产出的也是一个更小的、可直接调用的 Web handler。从源码角度defineHandler有函数与对象两种重载见 src/handler.ts对象形式还支持middleware数组与fetch属性defineValidatedHandler则在此基础上增加了基于 Standard Schema 的body/headers/query校验实验性 API。H3Eventsrc/event.ts同时暴露event.reqWebRequest、event.url解析后的URL、event.context、event.res惰性创建的响应头容器与event.waitUntil()。值得注意的是 v1 的event.node.{req,res}在 v2 中已标记为废弃改为通过event.runtime.node访问源码注释可佐证。中间件与插件next() 链式模型 definePlugin 扩展v2 引入了类似 Hono 的next()链式中间件模型同时提供了definePlugin这一简单而强大的应用扩展模式。import { H3 } from h3; const app new H3().use(async (event, next) { // ... 响应之前 ... const body await next(); // ... 响应之后 ... event.res.headers.append(x-middleware, works); event.waitUntil(sendMetrics(event)); return body; });import { defineHandler, basicAuth } from h3; export default defineHandler({ middleware: [basicAuth({ password: test })], handler: (event) Hello ${event.context.basicAuth?.username}!, });import { H3, onRequest } from h3; const app new H3().use( onRequest((event) { console.log(Request: [${event.req.method}] ${event.url.pathname}); }), );import { H3, onResponse } from h3; const app new H3().use( onResponse((response, event) { console.log(Response: [${event.req.method}] ${event.url.pathname}, body); }), );import { H3, onError } from h3; const app new H3().use( onError((error, event) { console.error([${event.req.method}] ${event.url.pathname} !! ${error.message}); }), );import { H3, serve, definePlugin } from h3; const logger definePlugin((h3, _options) { if (h3.config.debug) { h3.use((req) { console.log([${req.method}] ${req.url}); }); } }); const app new H3({ debug: true }).register(logger()).all(/**, () Hello!);[!NOTE] 接受next回调是可选的。中间件也可以像 v1 一样不返回响应若未返回响应框架会自动继续调用后续中间件与路由 handler最终没有响应则返回 404。源码层面的实现细节值得展开预组合中间件链src/middleware.ts 的composeMiddleware把中间件数组预组合为单一可调用链ComposedMiddleware逐层分发成本在建链时一次性支付请求期间不再重复计算composeHandler则把中间件 固定 handler组合为一个EventHandler。路由级中间件在注册时即与路由 handler 组合并缓存。next() 幂等callLayer中next闭包保证同一层只触发一次下游且对返回undefined或kNotFound的中间件自动透传继续isUnhandledResponse判断这就是不返回响应就继续语义的实现。中间件匹配器normalizeMiddleware支持route、method、match三种过滤选项见 src/middleware.ts 的createMatcher底层复用与路由相同的 rou3 匹配引擎与normalizeRoute归一化确保路由能命中的请求守卫也一定覆盖且 GET 作用域的中间件同样匹配 HEAD 请求RFC 9110 语义。onRequest/onResponse/onErrorsrc/utils/middleware.ts 中三者都是基于Middleware的便捷封装onError在HTTPError渲染前后介入错误处理onResponse是终结性的副作用钩子异常被吸收并记录不影响已构建的响应见 src/response.ts。definePluginsrc/plugin.ts 中definePlugin返回一个工厂函数调用后得到(h3) void形式的插件可在构造时通过config.plugins数组或运行时通过app.register()注入见 src/h3.ts 构造函数与register方法。上例中app.register(logger())即按debug配置决定是否注册日志中间件。basicAuth 的安全性仓库中的 src/utils/auth.ts 实现了完整的 RFC 7617/9110 兼容认证支持username/password或自定义validate函数、realm配置默认auth、统一随机抖动randomJitter防止时序侧信道、恒定时间比较timingSafeEqual并以401WWW-Authenticate挑战头拒绝非法凭据。从 v1 迁移最小化破坏性变更v2 致力于将破坏性变更降到最低大部分工具函数保持了向后兼容。完整迁移指南见 docs/5.migration/0.index.md要点包括运行时要求v2 仅支持 ESM要求 Node.js 20.11最新 LTS 推荐也可运行于 Bun、Denorequire(h3)在新版 Node.js 中仍可用require(esm)支持。Web 标准访问event.web更名为event.reqWebRequest实例event.node.{req,res}仅在 Node.js 运行时可用且推荐改用event.runtime.node。响应处理始终坚持显式return响应体或throw错误。v1 的send()、sendError()、sendStream()、sendWebResponse()分别迁移为return value、throw createError(error)、return stream、return responsesendNoContent→return noContent()sendIterable→return iterable(...)sendProxy→return proxy(...)sendRedirect→return redirect(location, code)等见 迁移指南 完整清单。应用与路由合并createApp()createRouter()合并为new H3()路由匹配引擎迁移到 rou3个别匹配行为有更直觉的变化。app.use(/path, handler)现在只匹配/path本身匹配子路径需写成app.use(/path/**, handler)。请求体读取readBody(event)仍可用按 content-type 走JSON.parse或URLSearchParams但文本/JSON/表单/流分别可用原生的event.req.text()、event.req.json()、event.req.formData()、event.req.body替代完整迁移指南见 docs/5.migration/0.index.md。统一的 H(TTP) 服务端工具生态v2 发布后H3 及其关联项目迁移至统一的 h3js 组织并启用了新的 h3.dev 域名。在 H3 这一框架伞下官方维护着多个面向通用 JavaScript 服务器的关键组件全部开源、可独立或搭配 H3 使用且支持任意 JavaScript 运行时⚡️h3极简 HTTP 框架即本仓库rou3轻量级 JavaScript 路由器H3 的依赖见 package.jsonsrvx通用 Web 服务器 APIH3 的依赖负责跨运行时适配crossws跨平台 WebSocket 支持H3 的可选 peer dependency见 package.json。通往 v2 稳定版的路由图v2 beta 之后的下一步计划包括收集社区反馈基于反馈定稿 API确保生态兼容并完成 Nitro v3 的升级适配。如果你在实战中遇到问题可优先参考本仓库的 基础指南、工具函数文档 与 示例代码 目录其中 middleware.mjs、router.mjs、handler-fetch.mjs、plugin.mjs 等文件与本文所述 v2 特性一一对应以验证 API 的实际用法。【免费下载链接】h3⚡️ Minimal H(TTP) framework built for high performance and portability项目地址: https://gitcode.com/GitHub_Trending/h31/h3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考