H3框架v1到v2版本迁移指南：全面拥抱Web标准

H3框架v1到v2版本迁移指南：全面拥抱Web标准

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

前言

H3作为一款轻量级的HTTP框架，在v2版本中进行了重大升级，全面拥抱Web标准API。本文将深入解析迁移过程中的关键变化，帮助开发者顺利完成版本过渡。

环境要求升级

H3 v2版本对运行环境提出了更高要求：

• Node.js版本：最低要求v20.11（推荐使用最新LTS版本）
• 模块系统：全面转向ESM模块系统

虽然CommonJS模块仍可通过Node.js的require(esm)机制兼容使用，但建议开发者逐步迁移到ESM模块系统以获得最佳体验。

Web标准API整合

v2版本的核心变化是全面采用Web标准API：

1. 基础对象：使用标准的URL、Headers、Request和Response对象
2. 运行时适配：
   • Node.js环境下使用兼容层实现
   • 其他运行时直接使用原生Web API

重要变更：

• event.web重命名为event.req
• Node.js特有的event.node.{req,res}仅在Node环境下可用

响应处理机制重构

v2版本对响应处理进行了重大调整，开发者需要特别注意：

响应发送方式

// v1方式
send(event, value)

// v2方式
return value

错误处理

// v1方式
sendError(event, error)

// v2方式
throw createError(error)

常用响应工具函数变更

| v1函数 | v2替代方案 | |--------|------------| | sendNoContent(event) | return noContent(event) | | sendRedirect(event, location, code) | return redirect(event, location, code) | | sendProxy(event, target) | return proxy(event, target) |

路由系统升级

v2版本将路由功能整合到核心中，并引入全新的路由匹配引擎：

主要变更点

1. 路由创建方式：

   // v1方式
   const app = createApp()
   const router = createRouter()
   
   // v2方式
   const app = new H3()
   

2. 路径匹配规则：

   • 精确匹配：app.use("/path", handler)仅匹配/path
   • 通配匹配：需要使用app.use("/path/**", handler)

3. 路径处理：

   • event.path现在包含完整路径（不再省略前缀）
   • 使用withBase(base, handler)处理带前缀的应用

请求体处理优化

v2版本推荐直接使用Web标准的Request API：

| 功能 | Web标准API | 替代的v1工具函数 | |------|-----------|----------------| | 文本内容 | event.req.text() | readRawBody | | JSON数据 | event.req.json() | readBody | | 表单数据 | event.req.formData() | readFormData | | 数据流 | event.req.body | getBodyStream |

安全提示：v2版本不再使用destr进行JSON解析，开发者需要自行处理数据过滤和消毒，防止原型污染攻击。

Cookie和Header处理

v2版本完全采用Web标准的Headers接口：

1. Header值类型：始终为字符串（不再支持数组、数字等类型）
2. Set-Cookie处理：使用headers.getSetCookie()获取Cookie数组
3. 类型安全：Header名称现在有更严格的类型检查

废弃API清单

v2版本淘汰了大量旧API，以下是主要变更分类：

核心功能

• createApp → new H3()
• eventHandler → 直接使用函数或defineHandler

请求处理

• getHeader → event.req.headers.get()
• getHeaders → Object.fromEntries(event.req.headers.entries())

响应处理

• setHeader → event.res.headers.set()
• appendHeader → event.res.headers.append()

类型定义

• App → H3
• H3Headers → 标准Headers
• H3Response → 标准Response

迁移建议

1. 逐步迁移：先处理核心路由和响应逻辑，再逐步替换工具函数
2. 类型检查：利用TypeScript发现兼容性问题
3. 测试覆盖：特别注意路径匹配和响应处理的变化
4. 性能监控：新路由引擎可能带来性能变化

通过遵循本指南，开发者可以顺利完成H3 v1到v2的迁移，享受更标准、更现代的API设计带来的开发体验提升。

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