# roninforge-hono
[](https://opensource.org/licenses/MIT)
Hono v4 (TypeScript 边缘 Web 框架) + TypeScript 的 Cursor 插件。固定依赖为 `hono ^4.12.19`、`@hono/zod-validator ^0.8.0`、`@hono/zod-openapi ^1.4.0` (需 `zod ^4.x` 作为对等依赖)、`@hono/node-server ^2.0.3` (Node 20+)。教授那些基于 2024 年前数据训练的 LLM 所不了解的 v4 API (`c.json()` 始终类型化，验证器抛出 `HTTPException`，`getCookie`/`setCookie` 来自 `hono/cookie`，`c.env` 作为属性，`streamText` 来自 `hono/streaming`，`showRoutes` 来自 `hono/dev`，`getRuntimeKey` 来自 `hono/adapter`，`fire(app)` 来自 `hono/service-worker`，Workers 静态资源绑定取代已弃用的 `serveStatic`，用于 Deno 的 JSR `@hono/hono`)。通过 BAD / CORRECT TypeScript 对，捕获 50 多个 LLM 回退问题。
**不存在 Hono v5。** 最新稳定版是 `v4.12.19`。生成的代码中出现的任何 "v5" 都是幻觉。
## 问题所在
Hono 的维护者自己提交了 Issue #3906 ("llm.txt file") 和 Issue #4812 ("Official AI Agent Skill for Hono")，明确指出 **"LLM 基本不了解最新 Hono 的工作原理。"** 2025 年前的训练数据是 v3 时代的。LLM 会产生：
### v3 -> v4 移除的 API
- **`c.jsonT()`** 而不是 `c.json()`（自 v4.0.0 起始终类型化）
- **`c.stream()` / `c.streamText()`** 作为 Context 方法（在 v4 中移至 `hono/streaming`）
- **`c.env()`** 函数形式（现在是属性；运行时检测通过 `hono/adapter` 中的 `getRuntimeKey()`）
- **`c.req.cookie()`**（已移除；使用 `hono/cookie` 中的 `getCookie(c)`）
- **`app.showRoutes()`、`app.routerName`**（移至 `hono/dev`）
- **`addEventListener('fetch')` + `app.handleEvent()`**（Service Worker 语法；使用 `export default { fetch: app.fetch }`）
- **`app.head(...)`** 路由（v4 中 HEAD 从 GET 自动派生）
- **`hono/nextjs`** 导入（使用 `hono/vercel`）
- **`hono/middleware`** 整体导入（使用每个中间件的子路径）
- **`c.req.headers()` / `c.req.body()` / `c.req.signal()`** 访问器方法（使用 `c.req.raw.*`）
- **`FC`** 带有隐式 children（使用 `PropsWithChildren
`）
- **`app.fire()`**（v4.8.0 弃用；使用 `hono/service-worker` 中的 `fire(app)`）
- **`import { Hono } from 'https://deno.land/x/hono/mod.ts'`** 在 Deno 上（自 v4.4.0 起已过时；使用 `jsr:@hono/hono`）
### Express / Koa / Fastify 泄漏（最大的一类）
- **缺少 `return`** 在 `c.json()` 上（解析为 undefined；v4 抛出 "Context is not finalized"）
- **`res.json()` / `res.send()`** 而不是 `c.json()`（Hono 中没有 `res`）
- **`(req, res, next)`** 中间件签名（使用 `(c, next)`）
- **`(err, req, res, next)`** 错误中间件（使用 `app.onError` + `HTTPException`）
- **`app.use(express.json())`** body 解析器（Hono 按需通过 `c.req.json()` 解析）
- **`import cors from 'cors'`** 从 npm（使用 `hono/cors`）
- **`supertest`** 用于测试（使用 `app.request()` / `testClient(app)`）
- **`c.req.body`** 作为已解析的（它是 `ReadableStream`）
- **`c.req.parseBody()`** 用于 JSON（仅适用于 form / multipart）
- **`c.req.text()` 然后 `c.req.json()`**（body 被消费两次）
- **`c.userId = ...`** 内联赋值（使用带类型化 Variables 的 `c.set('userId', ...)`）
### TypeScript / RPC 推断错误
- **`new Hono()`** 没有 `Bindings` / `Variables` 泛型（`c.env` 是 `{}`）
- **路由定义为语句**（`app.get(...)` 然后 `app.post(...)`） - 丢弃 RPC 类型
- **子应用 `app.route()` 调用作为语句** - 同样规则
- **Rails 风格控制器** 传递 `Context`（丢失路径参数推断，根据 Hono 最佳实践）
- **`app.use('/path', zValidator(...))`** 而不是作为路由参数（TS 错误：`'json' not assignable to 'never'`）
- **`c.notFound()`** 在 RPC 消费的路由中（无法在客户端类型化）
- **`new Response(JSON.stringify(...))`** 在 RPC 路由中（客户端看到 `unknown`）
- **`hc('/')`** 相对 URL（在 `$url()` 时抛出错误）
- **将服务器应用的值导入** 到客户端 bundle 中（拖入 `drizzle-orm`、`fs`、原生依赖 - **头号 RPC bundle 膨胀陷阱**）
- **中间件没有 `createMiddleware`**（Variables 类型不传播）
### Cloudflare Workers 陷阱
- **`process.env.X`** 在 Workers 代码中（undefined；使用带类型化 `Bindings` 的 `c.env.X`）
- **`fs` / `path`** 导入在 Workers 中（没有文件系统）
- **`compatibility_flags: ["node_compat"]`** 旧标志（使用 `nodejs_compat`）
- **已弃用的 `serveStatic` 来自 `hono/cloudflare-workers`**（自 v4.3.0 起；使用资源绑定）
- **缺少 `c.executionCtx.waitUntil()`** 用于 fire-and-forget
- **真实值检查 `if (c.executionCtx)`**（getter 在 Bun 和 Next.js App Router 上抛出错误）
- **未等待的 D1 `.run()` / `.first()` / `.all()`**（当 worker 终止时插入被取消）
- **WebSocket 升级没有 Durable Object** 转发（状态消失）
### 安全 / 生产缺口
- **没有 `secureHeaders()`** 中间件
- **没有 `csrf()`** 在 cookie 认证的变更上
- **`cors({ origin: '*', credentials: true })`**（浏览器静默丢弃；AJAX 失败）
- **缺少 `bodyLimit()`** 在 POST / PUT 路由上 **并且固定 `hono >= 4.9.7` 用于 CVE-2025-59139**
- **Cookies 没有 `httpOnly` / `secure` / `sameSite` / `path`**
- **`sameSite: 'None'` 没有 `secure: true`**（静默丢弃）
- **Body 日志中间件** 没有脱敏（密码/令牌/PII 泄漏）
- **没有 `etag()` / `cache()`** 在静态 GET 上
- **硬编码的 JWT 密钥** 字符串（通过 bundle 泄漏）
- **在内存中构建大型 JSON** 而不是使用 `streamText`（Workers 128MB 上限）
### 路由 / 结构性错误
- **子应用 `notFound`** 处理器（死代码；只有顶层触发）
- **尾部斜杠不一致**（`/users` vs `/users/` 默认是不同路由）
- **`await next()`** 多于一次（下游工作加倍）
- **`app.use(prefix, mw)` + `app.route(prefix, subApp)` 重叠**（中间件触发两次）
- **`app.basePath('/api')`** 作为语句（前缀从类型中丢弃）
### 运行时静默错误
- **`serve(app)`** 在 `@hono/node-server` 上（使用 `serve({ fetch: app.fetch })`）
- **`export default app`** 在 Workers 上（使用 `export default { fetch: app.fetch }`）
- **`Bun.serve({ fetch: app })`**（使用 `app.fetch`）
### 较小的实际问题
- **`c.req.query()`** 无参数时期望单个值
- **`c.req.param('id')`** 在全局中间件中（当路径中没有 `:id` 时是 undefined）
- **手动编写的 OpenAPI** 没有使用 `@hono/zod-openapi`
- **`cors()`** 安装在路由之后（永远不匹配）
## 安装
将规则、技能和智能体复制到你项目的 Cursor 配置中。先备份你现有的文件；`cp -r` 会覆盖同名规则。
```
git clone https://github.com/RoninForge/roninforge-hono.git
# 使用 -n 以避免覆盖同名的自定义规则。
cp -rn roninforge-hono/rules/* your-project/.cursor/rules/
cp -rn roninforge-hono/skills/* your-project/.cursor/skills/
cp -rn roninforge-hono/agents/* your-project/.cursor/agents/
```
或者将整个仓库作为 git 子模块放在 `your-project/.cursor/plugins/` 下。请参考 [Cursor 插件文档](https://docs.cursor.com/plugins) 了解适用于你 Cursor 版本的当前全局安装路径。
## 包含内容
### 规则（10 个文件）
| 规则 | 作用域 (globs) | 功能描述 |
|---|---|---|
| `hono-anti-patterns` | `**/*.ts,**/*.js,**/*.tsx,**/*.jsx,wrangler.{toml,jsonc,json}` | 59 个 LLM 回退问题，配有 BAD / CORRECT 对，按类别 A-H 组织（Express 泄漏、v3 时代 API、TypeScript / RPC、CF Workers、安全、路由、运行时、较小问题） |
| `hono-core` | `**/*.ts,**/*.tsx,**/*.js,**/*.jsx` (alwaysApply) | 应用初始化，带类型化 Bindings + Variables、Context API、请求访问器、中间件签名、内置中间件列表、cookie 助手、运行时检测 |
| `hono-routing-and-rpc` | `src/**/*.ts,src/routes/**/*,src/api/**/*,src/server/**/*,src/client/**/*,routes/**/*` | 链式路由、子应用组合、basePath 不可变性、双重执行重叠修复、子应用 notFound 死代码、`hc` 设置、`import type` 规则、类型化基础 URL、`$path()`、TanStack Query / SWR 集成、factory.createHandlers、30+ 路由的 RPC 缓解 |
| `hono-validators` | `src/**/*.ts,routes/**/*.ts,api/**/*.ts,handlers/**/*.ts` | `@hono/zod-validator` 放置、`c.req.valid()` 访问器、验证失败抛出异常、`@hono/zod-openapi` (zod ^4 对等依赖陷阱)、`@hono/standard-validator`、`@hono/valibot-validator`、内置 `hono/validator`、决策树 |
| `hono-cloudflare-workers` | `src/**/*.ts,worker/**/*.ts,workers/**/*.ts,wrangler.{toml,jsonc,json},**/cloudflare-env.d.ts,**/worker-configuration.d.ts` | `wrangler.jsonc` 规范形状、兼容性标志规则、`wrangler types`、类型化 Bindings、`c.env` vs `process.env`、`c.executionCtx.waitUntil` + 可移植性、静态资源绑定、D1 等待、Drizzle + D1 技术栈、Hyperdrive + Prisma 适配器陷阱、Durable Objects 用于 WebSockets、`hono/cache` 自定义域规则、ES Module Worker 导出 |
| `hono-security` | `src/**/*.ts,src/**/*.tsx,src/middleware/**/*.ts,src/auth/**/*.ts,src/index.ts,src/app.ts` | `secureHeaders()`、`csrf()`、CORS 允许列表、`bodyLimit()` + CVE-2025-59139 最低固定版本 4.9.7、cookie 默认值、来自 c.env 的 JWT 密钥、无 PII 泄漏的日志记录、`etag()` + `cache()`、IP 限制、超时、请求 ID、认证库选择（Lucia 已弃用；推荐 Better Auth / Clerk）、`@sentry/hono` 优先于 `@hono/sentry` |
| `hono-error-handling` | `src/**/*.ts,routes/**/*.ts,api/**/*.ts,middleware/**/*.ts,src/index.ts,src/app.ts` | `HTTPException` 规范抛出、`app.onError` 全局处理器、`app.notFound` 仅顶层、通过判别联合的类型化 RPC 错误、验证器抛出异常、通过 `@sentry/hono` 的 Sentry、带 pino 脱敏的结构化日志记录、错误响应形状约定 |
| `hono-jsx` | `**/*.tsx,**/*.jsx,**/jsx-runtime.ts,src/components/**/*,src/views/**/*,src/islands/**/*,app/islands/**/*` | `hono/jsx` 服务端、tsconfig 设置、`FC` 不包括 children、`jsxRenderer` 中间件用于布局、带 Suspense 的 `hono/jsx/streaming`、`hono/jsx/dom` 客户端组件、HonoX islands、htmx 集成、JSX SSR 安全最低固定版本 4.12.18 |
| `hono-testing` | `**/*.test.ts,**/*.test.tsx,**/*.spec.ts,**/*.spec.tsx,vitest.config.{ts,js},**/test/**/*.ts,**/tests/**/*.ts,**/__tests__/**/*.ts` | `app.request()` 通用模式、`testClient(app)` 类型化 RPC 测试、Vitest + `@cloudflare/vitest-pool-workers` 用于真实运行时 D1、`applyD1Migrations` fixture、Bun + `bun:test`、快照测试、中间件/验证器/waitUntil 测试、永不使用 `supertest` |
| `hono-deployment` | `wrangler.{toml,jsonc,json},deno.json,deno.jsonc,package.json,Dockerfile,fly.toml,vercel.json,netlify.toml,**/serverless.yml,**/template.yaml` | Cloudflare Workers (wrangler.jsonc + 兼容性标志)、Bun.serve、Deno + JSR、@hono/node-server v2 (Node 20+)、AWS Lambda + Lambda@Edge、Vercel Edge、Netlify、构建管道、最低固定版本、常见部署错误 |
### 技能（5 个命令）
| 技能 | 命令 | 功能描述 |
|---|---|---|
| 新路由 | `/hono-new-route` | 使用 `zValidator` 作为路由参数、`c.req.valid()` 类型化访问、`c.json({ ... } as const, status)` 用于类型化 RPC 响应、`Bindings` + `Variables` 泛型，搭建链式子应用骨架。子应用导出为 `typeof users`，通过链式 `.route()` 连接到父应用。拒绝 Rails 风格控制器、在 RPC 路由中使用 `c.notFound()`、原始 `new Response()`。 |
| RPC 设置 | `/hono-rpc-setup` | 使用 `import type`（承载规则）搭建 `hc` 客户端骨架、绝对基础 URL、类型化共享 `api` 模块、通过 `InferRequestType` / `InferResponseType` 的 TanStack Query / SWR 集成、`parseResponse` 实用程序、`$path()` 方法、30+ 路由的 IDE 减速缓解。 |
| Workers 设置 | `/hono-cloudflare-workers-setup` | 搭建全新的 Hono + Workers 项目骨架，使用 `wrangler.jsonc` (非 `.toml`)、`nodejs_compat`、由 `wrangler types` 生成的类型化 `Bindings`、D1 + Drizzle 中间件模式、`secureHeaders` + `cors` + `csrf` + `bodyLimit` 技术栈、用于 `@cloudflare/vitest-pool-workers` 的 Vitest 配置。 |
| 迁移到 v4 | `/hono-migrate-to-v4` | 分阶段 v3 -> v4 迁移：提升固定版本（CVE-2025-59139 最低版本）、替换 `c.jsonT` / `c.stream` / `c.env()` / `c.req.cookie` / `app.showRoutes` / `app.handleEvent`、丢弃 `hono/middleware` 整体导入、Deno 切换到 JSR、`@hono/node-server` v2 + Node 20+、为验证器抛出异常注册 `app.onError`。 |
| 验证 | `/hono-validate` | 运行 `validate-plugin.sh` + `tsc --noEmit` + 测试 + grep 审计，以查找类型检查器无法捕获的语法反模式（`c.jsonT`、`c.req.cookie`、`process.env`、`node_compat`、来自 `hono/cloudflare-workers` 的 `serveStatic`、硬编码 JWT 密钥、`sameSite:'None'` 无 `secure`、缺少 `bodyLimit`、在 `hc` 客户端上的值导入）。 |
### 智能体（1 个子智能体）
| 智能体 | 功能描述 |
|---|---|
| `hono-reviewer` | 按严重性审查 Hono v4 + TypeScript 代码。严重：`hono < 4.9.7`（CVE）、v5 引用（幻觉）、`cors` 通配符 + 凭据、`sameSite:'None'` 无 `secure`、硬编码 JWT 密钥、Workers 中的 `process.env`、缺少 `bodyLimit`、cookie 认证无 `csrf`、已弃用的 `serveStatic`、JSX SSR 在 `< 4.12.18` 上。错误：`c.json` 缺少 return、Express 中间件形状、所有 v3 时代移除的 API、未链式路由/子应用、Rails 控制器、`zValidator` 放置、RPC 中的 `c.notFound`/原始 Response、相对 URL `hc()`、值导入服务器应用、未等待的 D1、运行时导出形状。警告：cookie 默认值、`secureHeaders`、body 日志记录无脱敏、`app.onError`、子应用 `notFound`、`c.executionCtx` 真实值检查、无 Bindings 泛型、`cors` 在路由之后、中间件重叠、`basePath` 语句、尾部斜杠、`hono/middleware` 整体导入、新项目使用 `wrangler.toml`、Lucia、`@hono/sentry`。瑕疵：缺少 `satisfies ExportedHandler`、手动编写的 OpenAPI、缺少 `observability.enabled`。 |
## 测试夹具
`tests/fixtures/correct-sample/` 是一个精简的 Hono 4.12.19 + Cloudflare Workers + D1 + Drizzle + Zod 项目，展示了黄金标准形状：链式路由、类型化 RPC、`zValidator` 作为路由参数、`c.json({ ... } as const, status)` 类型化响应、`secureHeaders` + `cors` + `csrf` + `bodyLimit` 技术栈、`app.onError` + `app.notFound` 在顶层、`export default { fetch: app.fetch } satisfies ExportedHandler`。
`tests/fixtures/anti-pattern-sample/` 是其反面。每个文件都违反了一个编号的反模式。`package.json` 故意固定 `hono ^3.12.0` + `cors ^2.8.5` + `supertest ^6.3.0` + `@hono/sentry ^1.0.0` + `lucia ^3.2.0` - v3 时代是大多数 2025 年前模型的 LLM 训练数据基线，加上 LLM 仍然推荐的已弃用伴侣。跟踪的违规包括：`c.json` 缺少 return (#1)、`(req, res)` Express 处理器形状 (#2)、`(req, res, next)` 中间件 (#3)、`(err, req, res, next)` (#4)、npm cors (#6)、supertest (#12)、`c.jsonT` (#13)、`addEventListener('fetch') + app.handleEvent` (#15)、`c.req.cookie` (#16)、`c.env()` 函数调用 (#17)、`hono/middleware` 整体导入 (#20)、`app.head()` (#23)、无 Bindings/Variables (#24)、RPC 路由中的 `c.notFound` (#29)、Workers 中的 `process.env` (#34)、`node_compat` 标志 (#36)、来自 `hono/cloudflare-workers` 的 `serveStatic` (#37)、未等待的 D1 (#40)、cors `*` + 凭据 (#43)、无 `httpOnly/secure/sameSite/path` 的 cookie (#45)、`sameSite:'None'` 无 `secure:true` (#46)、硬编码 JWT 密钥 (#48)、子应用 `notFound` (#50)、`basePath` 作为语句 (#53)、Workers 上的 `export default app` (#55)、已弃用的 `@hono/sentry` + `lucia` 引用。
## 版本控制
规则针对 `hono ^4.12.19`，适用于 Node 20+（当在 Node 上时）、最新 Bun、最新 Deno、Wrangler ^4.0.0。大多数模式可回溯至 Hono 4.0.0（2024 年 2 月），具体差异已内联说明。最低固定版本：
- **`hono >= 4.9.7`** 强制要求 - CVE-2025-59139 / GHSA-92vj-g62v-jqhh `bodyLimit` 绕过修复
- **`hono >= 4.12.18`** 如果渲染 JSX SSR 则强制要求 - 标签名、属性名、CSS 注入加固
- **`@hono/node-server >= 2.0.0`** 需要 Node 20+
- **`@hono/zod-openapi >= 1.0.0`** 需要 `zod ^4.0.0`（对等依赖仅为 `^4.0.0`，非 `^3.x`）
- **`compatibility_date >= "2024-09-23"`** 要求 `nodejs_compat` 意味着 `nodejs_compat_v2`
规则引用了版本（`c.json()` 自 v4.0.0 起始终类型化、`c.text()` 自 v4.3.0 起类型化、Deno 使用 JSR 自 v4.4.0 起、`secureHeaders Permissions-Policy` 自 v4.6.0 起、标准 Schema 验证器自 v4.7.0 起、`fire(app)` 自 v4.8.0 起、JSR `parseResponse` 自 v4.9.0 起、`hc` 的类型化基础 URL 自 v4.11.0 起、`$path()` 方法自 v4.12.0 起），在采用前请对照你已安装版本的更新日志进行验证。
## 许可证
MIT - 详见 [LICENSE](LICENSE)
## 链接
- [Hono 官方文档](https://hono.dev)
- [Hono GitHub](https://github.com/honojs/hono)
- [Hono 迁移指南 (v3 -> v4)](https://github.com/honojs/hono/blob/main/docs/MIGRATION.md)
- [Hono 最佳实践](https://hono.dev/docs/guides/best-practices)
- [Hono RPC](https://hono.dev/docs/guides/rpc)
- [Cloudflare Workers Hono 框架指南](https://developers.cloudflare.com/workers/framework-guides/web-apps/more-web-frameworks/hono/)
- [Cursor 插件文档](https://docs.cursor.com/plugins)
- [RoninForge](https://roninforge.org)