# roninforge-hono：解决LLM生成Hono v4代码的59种常见错误

> 专为Cursor设计的Hono v4插件，通过BAD/CORRECT代码对比纠正59种LLM在生成Hono代码时的常见回归错误，涵盖v3到v4的API变更、Express泄漏、TypeScript类型推断陷阱等。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-10T07:44:43.000Z
- 最近活动: 2026-06-10T07:57:28.831Z
- 热度: 163.8
- 关键词: Hono, TypeScript, Cursor, LLM, API变更, 代码质量, Cloudflare Workers, RPC, 类型安全, Web框架
- 页面链接: https://www.zingnex.cn/forum/thread/roninforge-hono-llmhono-v459
- Canonical: https://www.zingnex.cn/forum/thread/roninforge-hono-llmhono-v459
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：RoninForge
- 来源平台：github
- 原始标题：roninforge-hono
- 原始链接：https://github.com/RoninForge/roninforge-hono
- 来源发布时间/更新时间：2026-06-10T07:44:43Z

# roninforge-hono：解决LLM生成Hono v4代码的59种常见错误\n\n## 原作者与来源\n\n- **原作者/维护者：** RoninForge\n- **来源平台：** GitHub\n- **原始标题：** roninforge-hono\n- **原始链接：** https://github.com/RoninForge/roninforge-hono\n- **发布时间：** 2026年6月10日\n- **许可证：** MIT\n\n## 项目背景与动机\n\nHono是一个轻量级的TypeScript边缘Web框架，专为现代JavaScript运行时（如Cloudflare Workers、Deno、Bun、Node.js）设计。随着v4版本的发布，Hono引入了大量API变更和改进，但这也带来了一个严重问题：大型语言模型（LLM）的训练数据主要基于v3时代的代码，导致它们在生成Hono代码时频繁出错。\n\nHono的维护者甚至在GitHub上专门创建了Issue #3906（"llm.txt file"）和Issue #4812（"Official AI Agent Skill for Hono"），明确指出**"LLMs basically have no knowledge of how the latest Hono works"**。\n\nroninforge-hono正是为解决这一问题而生的Cursor插件，它通过提供59个BAD/CORRECT代码对比对，帮助LLM理解Hono v4的正确用法。\n\n## 核心问题：v3到v4的API变更\n\nHono v4于2024年2月发布，带来了大量破坏性变更。许多在v3中常用的API在v4中被移除或迁移，但LLM由于缺乏更新的训练数据，仍然生成过时的代码。\n\n### 已移除的v3 API\n\n以下是LLM最常生成但已在v4中移除的API：\n\n| v3 API | v4替代方案 | 说明 |\n|--------|-----------|------|\n| `c.jsonT()` | `c.json()` | v4起`c.json()`始终返回类型 |\n| `c.stream()` / `c.streamText()` | `hono/streaming` | 流式处理移至独立模块 |\n| `c.env()` | `c.env`属性 | 运行时检测使用`getRuntimeKey()` |\n| `c.req.cookie()` | `getCookie(c)` | 从`hono/cookie`导入 |\n| `app.showRoutes()` | `hono/dev` | 开发工具移至独立模块 |\n| `app.fire()` | `fire(app)` | 从`hono/service-worker`导入 |\n| `hono/nextjs` | `hono/vercel` | Next.js支持改为Vercel适配器 |\n| `hono/middleware` | 子路径导入 | 中间件需单独导入 |\n| `addEventListener('fetch')` | `export default { fetch: app.fetch }` | Service Worker语法变更 |\n| Deno URL导入 | `jsr:@hono/hono` | v4.4.0起使用JSR |\n\n### Express/Koa/Fastify代码泄漏\n\n由于LLM的训练数据中Express代码远多于Hono，它们经常将Express模式错误地应用到Hono中。这是最大的一类错误：\n\n**路由处理差异**\n\n```typescript\n// BAD: Express风格\napp.use((req, res, next) => {\n  res.json({ message: 'Hello' });\n});\n\n// CORRECT: Hono风格\napp.use(async (c, next) => {\n  return c.json({ message: 'Hello' });\n});\n```\n\n**关键区别：**\n- Hono使用`(c, next)`而非`(req, res, next)`\n- 必须`return` `c.json()`的结果，否则抛出"Context is not finalized"错误\n- 没有`res`对象，所有响应通过`c`（Context）完成\n\n**错误处理差异**\n\n```typescript\n// BAD: Express错误中间件\napp.use((err, req, res, next) => {\n  res.status(500).json({ error: err.message });\n});\n\n// CORRECT: Hono错误处理\napp.onError((err, c) => {\n  return c.json({ error: err.message }, 500);\n});\n```\n\n**中间件使用差异**\n\n```typescript\n// BAD: Express body parser\nimport express from 'express';\napp.use(express.json());\n\n// CORRECT: Hono原生解析\nconst body = await c.req.json();  // 按需解析，无需中间件\n```\n\n**CORS处理差异**\n\n```typescript\n// BAD: npm cors包\nimport cors from 'cors';\napp.use(cors());\n\n// CORRECT: Hono内置CORS\nimport { cors } from 'hono/cors';\napp.use(cors());\n```\n\n## TypeScript与RPC类型推断陷阱\n\nHono的一个核心优势是其类型安全的RPC系统，但LLM经常破坏这种类型安全。\n\n### 泛型参数缺失\n\n```typescript\n// BAD: 无泛型参数\nconst app = new Hono();\n// c.env类型为{}，无法访问环境变量\n\n// CORRECT: 显式定义Bindings和Variables\ntype Bindings = {\n  DATABASE_URL: string;\n};\n\ntype Variables = {\n  userId: string;\n};\n\nconst app = new Hono<{ Bindings: Bindings; Variables: Variables }>();\n```\n\n### 链式路由定义\n\n```typescript\n// BAD: 语句式路由定义（丢失RPC类型）\napp.get('/users', (c) => { ... });\napp.post('/users', (c) => { ... });\n\n// CORRECT: 链式定义保持RPC类型\nconst app = new Hono()\n  .get('/users', (c) => { ... })\n  .post('/users', (c) => { ... });\n```\n\n**关键原则：** 每个`.get()`、`.post()`等调用必须直接链式连接，中间不能有其他语句。\n\n### 子应用路由\n\n```typescript\n// BAD: 语句式子应用路由\nconst api = new Hono();\napi.get('/users', ...);\napp.route('/api', api);\n\n// CORRECT: 链式子应用路由\nconst api = new Hono().get('/users', ...);\nconst app = new Hono().route('/api', api);\n```\n\n### 验证器位置\n\n```typescript\n// BAD: 验证器作为中间件\napp.use('/users', zValidator('json', schema));\napp.post('/users', (c) => { ... });\n// TypeScript错误: 'json' not assignable to 'never'\n\n// CORRECT: 验证器作为路由参数\napp.post('/users', zValidator('json', schema), (c) => {\n  const data = c.req.valid('json');  // 正确推断类型\n  ...\n});\n```\n\n### 客户端类型导入陷阱\n\n```typescript\n// BAD: 从服务端导入应用类型（RPC包膨胀陷阱）\nimport { app } from './server';  // 拖入drizzle-orm、fs等依赖\nconst client = hc<typeof app>('/');\n\n// CORRECT: 仅导入类型\nimport type { AppType } from './server';\nconst client = hc<AppType>('/');\n```\n\n**这是RPC bundle-bloat的头号陷阱**，会导致客户端 bundle 包含服务端依赖。\n\n## Cloudflare Workers特有问题\n\nHono在Cloudflare Workers上非常流行，但LLM经常生成不适用的Node.js代码。\n\n### 环境变量访问\n\n```typescript\n// BAD: Node.js风格\nconst dbUrl = process.env.DATABASE_URL;\n// Workers中undefined\n\n// CORRECT: Workers风格\nconst dbUrl = c.env.DATABASE_URL;\n// 需要类型化的Bindings\n```\n\n### 静态资源服务\n\n```typescript\n// BAD: 已弃用的serveStatic\nimport { serveStatic } from 'hono/cloudflare-workers';\n\n// CORRECT: Workers Static Assets绑定\n// wrangler.toml配置\n[assets]\ndirectory = \"./public\"\n```\n\n### D1数据库操作\n\n```typescript\n// BAD: 未等待数据库操作\nconst result = c.env.DB.prepare('INSERT ...').run();\n// 操作可能在Worker终止时取消\n\n// CORRECT: 始终await\nconst result = await c.env.DB.prepare('INSERT ...').run();\n```\n\n### 执行上下文\n\n```typescript\n// BAD: 真值检查\nif (c.executionCtx) {\n  c.executionCtx.waitUntil(promise);\n}\n// 在Bun和Next.js App Router上会抛出错误\n\n// CORRECT: 直接使用\nc.executionCtx.waitUntil(promise);\n```\n\n## 安全与生产环境陷阱\n\n### CVE-2025-59139防护\n\n```typescript\n// BAD: 无body限制\napp.post('/upload', (c) => { ... });\n\n// CORRECT: 限制请求体大小\napp.post('/upload', bodyLimit({ maxSize: 10 * 1024 * 1024 }), (c) => { ... });\n\n// 同时确保hono版本 >= 4.9.7\n```\n\n**重要：** 必须将Hono版本固定到`^4.12.19`（>= 4.9.7），以修复CVE-2025-59139安全漏洞。\n\n### CORS安全配置\n\n```typescript\n// BAD: 危险的CORS配置\napp.use(cors({\n  origin: '*',\n  credentials: true\n}));\n// 浏览器会静默拒绝，AJAX请求失败\n\n// CORRECT: 明确的origin或省略credentials\napp.use(cors({\n  origin: ['https://example.com'],\n  credentials: true\n}));\n// 或\napp.use(cors({ origin: '*' }));  // 无credentials\n```\n\n### Cookie安全\n\n```typescript\n// BAD: 不安全的Cookie设置\nsetCookie(c, 'session', token);\n\n// CORRECT: 安全的Cookie设置\nsetCookie(c, 'session', token, {\n  httpOnly: true,\n  secure: true,\n  sameSite: 'Strict',\n  path: '/'\n});\n\n// 注意: sameSite: 'None'必须配合secure: true\n```\n\n### 响应流式处理\n\n```typescript\n// BAD: 内存中构建大JSON\nconst data = await fetchLargeData();\nreturn c.json(data);\n// Workers 128MB内存限制\n\n// CORRECT: 流式响应\nimport { streamText } from 'hono/streaming';\nreturn streamText(c, async (stream) => {\n  for await (const chunk of fetchLargeData()) {\n    await stream.write(chunk);\n  }\n});\n```\n\n## 路由与结构问题\n\n### 子应用notFound处理\n\n```typescript\n// BAD: 子应用中的notFound\nconst api = new Hono();\napi.notFound((c) => c.json({ error: 'Not found' }, 404));\n// 永远不会触发，只有顶层应用的notFound生效\n\n// CORRECT: 在顶层定义\nconst app = new Hono();\napp.route('/api', api);\napp.notFound((c) => c.json({ error: 'Not found' }, 404));\n```\n\n### 尾部斜杠处理\n\n```typescript\n// 默认行为：/users 和 /users/ 是不同的路由\n// 需要显式处理或配置路由选项\n```\n\n### 中间件重复执行\n\n```typescript\n// BAD: 中间件重叠\napp.use('/api', middleware);\napp.route('/api', subApp);  // subApp也有middleware\n// middleware执行两次\n\n// CORRECT: 避免重叠或使用条件判断\n```\n\n### next()多次调用\n\n```typescript\n// BAD: 多次await next()\nawait next();\nawait next();\n// 下游中间件执行两次\n\n// CORRECT: 只调用一次\nawait next();\n```\n\n## 运行时特定问题\n\n### Node.js服务器\n\n```typescript\n// BAD: 错误的serve用法\nimport { serve } from '@hono/node-server';\nserve(app);\n\n// CORRECT: 使用fetch处理器\nserve({ fetch: app.fetch });\n```\n\n### Cloudflare Workers导出\n\n```typescript\n// BAD: 默认导出app\nexport default app;\n\n// CORRECT: 导出fetch处理器\nexport default { fetch: app.fetch };\n```\n\n### Bun服务器\n\n```typescript\n// BAD: 直接传递app\nBun.serve({ fetch: app });\n\n// CORRECT: 使用fetch方法\nBun.serve({ fetch: app.fetch });\n```\n\n## 插件优势与社区规则对比\n\nroninforge-hono与现有的社区Hono规则（如cursor.directory和awesome-cursorrules）相比，解决了三个关键问题：\n\n### 1. 覆盖v3到v4的API变更\n\n现有规则未覆盖v4中移除的API，导致LLM继续生成`c.jsonT`、`c.stream`、`c.env()`等过时代码。roninforge-hono明确标记这些API为BAD并提供CORRECT替代。\n\n### 2. 解决Express泄漏问题\n\n现有规则未处理Express代码模式泄漏，如`(req, res, next)`签名、`supertest`测试、`cors` npm包等。roninforge-hono专门识别并纠正这些模式。\n\n### 3. 提供BAD/CORRECT对比\n\n不同于仅列出最佳实践，roninforge-hono为每个问题提供具体的BAD和CORRECT代码示例，使LLM能够学习具体的转换模式。\n\n## 使用建议\n\n### 项目初始化\n\n在使用Cursor生成Hono项目时，建议：\n\n1. **安装roninforge-hono插件**，将其添加到Cursor的`.cursorrules`文件\n2. **固定依赖版本**，确保使用`hono ^4.12.19`和`@hono/node-server ^2.0.3`\n3. **启用TypeScript严格模式**，捕获类型推断错误\n4. **配置Zod**，使用`zod ^4.x`配合`@hono/zod-validator`\n\n### 代码审查清单\n\n在审查LLM生成的Hono代码时，检查以下要点：\n\n- [ ] 所有`c.json()`调用都有`return`\n- [ ] 没有`req`/`res`参数，使用`c`（Context）\n- [ ] 路由定义是链式而非语句式\n- [ ] 验证器作为路由参数而非中间件\n- [ ] 环境变量通过`c.env`访问，而非`process.env`\n- [ ] Cookie设置了`httpOnly`、`secure`、`sameSite`\n- [ ] POST/PUT路由有`bodyLimit`保护\n- [ ] 没有导入`fs`/`path`等Node.js模块（Workers环境）\n- [ ] 客户端仅导入类型，不导入服务端应用实例\n\n## 总结\n\nroninforge-hono是一个精心设计的Cursor插件，通过59个BAD/CORRECT代码对比，系统性地解决了LLM在生成Hono v4代码时的常见错误。它涵盖了v3到v4的API变更、Express代码泄漏、TypeScript类型推断陷阱、Cloudflare Workers特有问题、安全漏洞和生产环境最佳实践。\n\n对于使用Cursor和LLM辅助开发Hono应用的开发者来说，这个插件是确保代码质量的重要工具。它不仅纠正错误，更重要的是帮助LLM学习Hono v4的正确模式，从而在未来生成更高质量的代码。\n\n随着Hono生态系统的不断发展，类似roninforge-hono这样的工具将成为AI辅助开发的标准配置，帮助开发者充分利用LLM的能力，同时避免常见的陷阱和错误。