hono-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hono Architecture Enforcement

Hono 架构强制规范

Overview

概述

Enforces hypercore Hono architecture rules before code changes. Validate that the target is actually a Hono project, then apply strict rules for route composition, handlers, middleware, validation, error handling, platform entrypoints, and typed testing/RPC.

This skill is strict. Follow the rules exactly unless the user explicitly asks to prefer official Hono defaults over hypercore-specific conventions.

OPERATING MODE: This skill is self-contained. Do not block on global skills or external orchestration surfaces. If the user asks for exhaustive verification, keep verifying. Otherwise proceed directly with this skill's own validation flow.

IMPORTANT: Some rules in this skill are stricter than Hono itself. Treat those as hypercore conventions and label them clearly when reporting violations.

在代码变更前强制遵循hypercore Hono架构规则。先验证目标项目确实是Hono项目，再对路由组装、处理函数、中间件、校验、错误处理、平台入口点以及类型化测试/RPC应用严格规则。

本规范要求严格：请严格遵循规则，除非用户明确要求优先使用Hono官方默认规则而非hypercore专属约定。

运行模式：本技能是自包含的，不要受全局技能或外部编排层阻塞。如果用户要求全面校验，就持续校验；否则直接执行本技能自身的校验流程即可。

重要提示：本技能中的部分规则比Hono本身的规则更严格，这些属于hypercore约定，在上报违规项时请明确标注。

Trigger Examples

触发示例

Positive

正向触发

Review this Hono app structure before I add more routes.

Refactor a Hono API so routing, middleware, and validators follow one architecture.

Add a new Hono route and make sure testClient and AppType inference still work.

在我添加更多路由前，评审这个Hono应用的结构

重构一个Hono API，让路由、中间件和校验器遵循统一架构

新增一个Hono路由，确保testClient和AppType类型推导仍然正常工作

Negative

负向触发

Create a generic Express middleware guide.

Review a React SPA that does not use Hono.

```
创建通用的Express中间件指南
```
```
评审一个不使用Hono的React SPA
```

Boundary

边界场景

```
Make a tiny copy-only response text change in a Hono handler.
```
Direct editing can be enough if no architectural boundary is affected.
```
Use official Hono defaults only, not the extra hypercore conventions.
```
This skill still applies, but relax hypercore-only strictness that exceeds the official docs.

对Hono处理函数的响应文本做仅复制的微小修改

如果没有影响架构边界，直接编辑即可。

```
仅使用Hono官方默认规则，不使用额外的hypercore约定
```
本技能仍然适用，但需要放宽超出官方文档的hypercore专属严格要求。

Step 1: Project Validation

步骤1：项目校验

Before doing any work, confirm the target is a Hono project:

bash

rg -n '"hono"|@hono/' package.json
rg -n "from 'hono'|from \"hono\"" src app .
rg -n "new Hono\\(|createFactory\\(|testClient\\(|hc<" src app .

If none of those indicators exist, stop and route back to the normal implementation or review path instead of forcing Hono rules.

在开展任何工作前，先确认目标是Hono项目：

bash

rg -n '"hono"|@hono/' package.json
rg -n "from 'hono'|from \"hono\"" src app .
rg -n "new Hono\\(|createFactory\\(|testClient\\(|hc<" src app .

如果没有找到上述任何标识，停止执行本流程，回归常规的实现或评审路径，不要强制应用Hono规则。

Step 2: Read Architecture Rules

步骤2：阅读架构规则

Read the detailed rules before editing:

```
architecture-rules.md
```
```
rules/conventions.md
```
```
rules/routes.md
```
```
rules/handlers.md
```
```
rules/middleware.md
```
```
rules/validation.md
```
```
rules/errors.md
```
```
rules/testing-rpc.md
```
```
rules/platform.md
```

When the change depends on current framework behavior or you need to justify a rule from the official docs, read:

```
references/official/hono-docs.md
```

编辑前先阅读详细规则：

```
architecture-rules.md
```
```
rules/conventions.md
```
```
rules/routes.md
```
```
rules/handlers.md
```
```
rules/middleware.md
```
```
rules/validation.md
```
```
rules/errors.md
```
```
rules/testing-rpc.md
```
```
rules/platform.md
```

当变更依赖框架当前行为，或者你需要引用官方文档佐证规则时，请阅读：

```
references/official/hono-docs.md
```

Task-to-Rule Routing

任务-规则匹配路径

Use the next file based on the change you are making:

For route composition, mount order, fallback placement, or sub-app structure, read
```
rules/routes.md
```
For handler extraction,
```
createFactory()
```
,
```
createHandlers()
```
, or typed context flow, read
```
rules/handlers.md
```
For shared request boundaries, auth/logging/request-id flow, or
```
c.set()
```
/
```
c.get()
```
usage, read
```
rules/middleware.md
```
For params/query/json/form validation choices, read
```
rules/validation.md
```

For

HTTPException

app.onError()

, or response-shaping problems, read

rules/errors.md

For

testClient()

hc<typeof app>

AppType

, or larger-app inference, read

rules/testing-rpc.md

For adapters, entrypoints, bindings, env/config typing, or
```
basePath()
```
boundaries, read
```
rules/platform.md
```

根据你正在做的变更，参考对应文件：

处理路由组装、挂载顺序、兜底路由放置或子应用结构，阅读
```
rules/routes.md
```
处理函数提取、
```
createFactory()
```
、
```
createHandlers()
```
或类型化上下文流转，阅读
```
rules/handlers.md
```
处理共享请求边界、认证/日志/请求ID流转或
```
c.set()
```
/
```
c.get()
```
使用，阅读
```
rules/middleware.md
```
处理params/query/json/form校验选型，阅读
```
rules/validation.md
```
处理
```
HTTPException
```
、
```
app.onError()
```
或响应格式化问题，阅读
```
rules/errors.md
```

处理

testClient()

、

hc<typeof app>

、

AppType

或大型应用类型推导，阅读

rules/testing-rpc.md

处理适配器、入口点、绑定、环境/配置类型化或
```
basePath()
```
边界，阅读
```
rules/platform.md
```

Official-Defaults Override Mode

官方默认规则覆盖模式

When the user explicitly asks for official Hono defaults instead of hypercore-only conventions:

Start from
```
references/official/hono-docs.md
```
first
Apply official Hono behavior as the default decision surface
Treat stricter hypercore rules as optional overlays and only enforce them when the user did not opt out
In findings and final reports, label which rules are official Hono behavior and which are hypercore-only conventions

当用户明确要求使用Hono官方默认规则而非hypercore专属约定时：

优先参考
```
references/official/hono-docs.md
```
默认采用Hono官方行为作为决策依据
将更严格的hypercore规则视为可选附加规则，仅当用户没有明确选择退出时才强制执行
在校验结果和最终报告中，明确标注哪些规则是Hono官方行为，哪些是hypercore专属约定

Step 3: Pre-Change Validation Checklist

步骤3：变更前校验清单

Validate planned changes against these gates.

对照以下准入条件校验计划中的变更：

Brownfield Adoption Rule

存量项目适配规则

Do not treat every legacy deviation as a project-wide failure.
Safety, typing, and validation issues still block immediately, especially in touched files.
Hypercore-specific structure drift in untouched legacy code can be recorded as migration backlog.
Any file you touch should be brought into compliance unless that would require a materially risky migration.

不要把所有遗留代码的偏差都视为项目级别的故障
安全、类型和校验问题仍然需要立即阻塞，尤其是被修改的文件中的问题
未被修改的遗留代码中存在的hypercore专属结构偏差，可以记录为迁移待办项
你修改的所有文件都需要符合规范，除非需要进行风险极高的迁移才能达标

Gate 1: Composition and Layers

准入1：组装与分层

Check	Rule
Root app mixes transport, business logic, and persistence directly?	BLOCKED. Keep composition in app/route modules and move domain logic down.
Route modules bypass services and talk to DB/SDK directly without a clear reason?	BLOCKED by hypercore convention. Prefer `routes -> services -> repositories/clients` .
Controller-style class or giant controller file introduced for simple handlers?	BLOCKED. Hono best practices prefer smaller apps and route composition over controller-heavy structure.
Large feature area mounted manually without sub-app composition?	WARNING. Prefer `app.route()` / `basePath()` composition.

检查项	规则
根应用直接混合了传输层、业务逻辑和持久层逻辑？	阻塞。将组装逻辑放在app/route模块中，把领域逻辑下沉到下层。
路由模块绕过服务层，无明确理由直接与DB/SDK交互？	按hypercore约定阻塞。推荐使用 `路由 -> 服务 -> 仓库/客户端` 的分层结构。
为简单处理函数引入了控制器风格的类或者巨型控制器文件？	阻塞。Hono最佳实践更推荐小型应用和路由组装，而非重控制器的结构。
大型功能模块手动挂载，没有使用子应用组装？	警告。推荐使用 `app.route()` / `basePath()` 进行组装。

Gate 2: Route Modules

准入2：路由模块

Check	Rule
Route registration scattered across unrelated files?	BLOCKED. Keep one obvious composition path.
Larger route module missing a dedicated folder with local schemas/handlers?	BLOCKED by hypercore convention.
Catch-all or fallback route registered before specific routes?	BLOCKED. Registration order matters in Hono.
Route module cannot be mounted cleanly with `app.route()` or a typed sub-app?	BLOCKED.

检查项	规则
路由注册散落在不相关的文件中？	阻塞。保持唯一清晰的组装路径。
大型路由模块没有独立文件夹存放本地schema/处理函数？	按hypercore约定阻塞。
通配符或兜底路由注册在具体路由之前？	阻塞。Hono中注册顺序会影响路由匹配结果。
路由模块无法通过 `app.route()` 或类型化子应用正常挂载？	阻塞。

Gate 3: Handlers and Context Typing

准入3：处理函数和上下文类型

Check	Rule
Extracted handlers lose route typing or context typing?	BLOCKED. Use inline chaining or `createFactory()` / `factory.createHandlers()` .
Untyped `c.set()` / `c.get()` values used across middleware/handlers?	BLOCKED. Type `Variables` on the app/factory.
Request parsing and domain work mixed into a single long handler?	WARNING. Split validator, service, and response shaping.

检查项	规则
提取的处理函数丢失了路由类型或上下文类型？	阻塞。使用内联链式调用或者 `createFactory()` / `factory.createHandlers()` 。
跨中间件/处理函数使用未类型化的 `c.set()` / `c.get()` 值？	阻塞。在应用/工厂上给 `Variables` 定义类型。
请求解析和领域逻辑混合在同一个长处理函数中？	警告。拆分校验器、服务逻辑和响应格式化逻辑。

Gate 4: Validation

准入4：校验

Check	Rule
Non-trivial request data consumed without validator middleware?	BLOCKED.
Raw `await c.req.json()` or manual parsing repeated inside handlers?	BLOCKED unless the payload is trivial and tightly scoped.
Validation strategy is inconsistent across params/query/json/form in the same feature?	WARNING. Normalize it.
New validation library added without need?	BLOCKED unless explicitly requested. Prefer built-in `validator()` , `@hono/zod-validator` , or `@hono/standard-validator` .

检查项	规则
使用非 trivial 的请求数据前没有经过校验中间件？	阻塞。
处理函数内重复使用原生 `await c.req.json()` 或手动解析逻辑？	阻塞，除非payload非常简单且范围高度收敛。
同一个功能的params/query/json/form校验策略不一致？	警告。请统一校验策略。
无必要地新增校验库？	阻塞，除非用户明确要求。优先使用内置 `validator()` 、 `@hono/zod-validator` 或 `@hono/standard-validator` 。

Gate 5: Middleware

准入5：中间件

Check	Rule
Middleware order assumed incorrectly?	BLOCKED. Registration order matters.
Shared auth/logging/request-id logic duplicated across handlers?	WARNING. Prefer middleware.
Context values survive across requests by assumption?	BLOCKED. Context is request-scoped only.
Runtime-specific concerns leak from middleware into domain layers?	BLOCKED.

检查项	规则
错误判断中间件执行顺序？	阻塞。注册顺序决定执行顺序。
共享的认证/日志/请求ID逻辑在处理函数中重复实现？	警告。优先使用中间件实现。
假设上下文值可以跨请求留存？	阻塞。上下文仅在单个请求范围内有效。
运行时专属逻辑从中间件泄漏到领域层？	阻塞。

Gate 6: Errors and Responses

准入6：错误和响应

Check	Rule
Handler throws raw generic errors for expected HTTP failures everywhere?	WARNING. Prefer `HTTPException` or one centralized translation policy.
`app.onError()` missing in a non-trivial API?	WARNING. Add a central error boundary.
Code relies on `HTTPException.getResponse()` while forgetting existing `Context` headers?	BLOCKED. Preserve context-set headers when rebuilding responses.
Typed RPC client is exported but the app still depends on `c.notFound()` behavior?	BLOCKED. Avoid patterns the Hono RPC docs call out as incompatible.

检查项	规则
处理函数到处抛出原始通用错误来处理预期的HTTP故障？	警告。优先使用 `HTTPException` 或者统一的错误转换策略。
非 trivial 的API中缺少 `app.onError()` ？	警告。添加统一的错误边界。
代码依赖 `HTTPException.getResponse()` ，但忽略了已有的 `Context` 请求头？	阻塞。重新构建响应时要保留上下文设置的请求头。
导出了类型化RPC客户端，但应用仍然依赖 `c.notFound()` 行为？	阻塞。避免使用Hono RPC文档中明确标注为不兼容的模式。

Gate 7: Testing and RPC

准入7：测试和RPC

Check	Rule
`testClient()` or `hc<typeof app>` type inference broken by non-chained route definition?	BLOCKED. Keep route types flowing through the exported app.
App type not exported where typed client/test usage is expected?	BLOCKED. Export `AppType` .
Large app split loses typed inference across sub-apps?	BLOCKED. Follow the larger-app chaining pattern from the Hono RPC docs.

检查项	规则
非链式的路由定义导致 `testClient()` 或 `hc<typeof app>` 类型推导失效？	阻塞。确保路由类型可以通过导出的应用正常流转。
预期会用到类型化客户端/测试的场景下没有导出应用类型？	阻塞。导出 `AppType` 。
大型应用拆分后子应用之间的类型推导失效？	阻塞。遵循Hono RPC文档中的大型应用链式定义模式。

Gate 8: Platform Entry

准入8：平台入口

Check	Rule
Runtime adapter code mixed into route modules?	BLOCKED. Keep adapter/bootstrap code at the edge.
Environment bindings/vars used without a typed `Bindings` /config boundary?	BLOCKED.
Debug helpers like `showRoutes()` enabled outside explicit dev-only setup?	WARNING.

检查项	规则
运行时适配器代码混合在路由模块中？	阻塞。将适配器/启动代码放在最边缘的入口层。
使用环境绑定/变量时没有经过类型化的 `Bindings` /配置边界？	阻塞。
类似 `showRoutes()` 的调试工具在显式的dev-only配置之外启用？	警告。

Step 3.5: Auto-Remediation Policy

步骤3.5：自动修复策略

Auto-fix directly when the issue is local, reversible, and low-risk.

Add missing validator middleware to a touched route
Add typed
```
AppType
```
export
Move route mounting into a single composition file
Convert extracted untyped handlers to
```
createFactory()
```
/
```
factory.createHandlers()
```
Add
```
app.onError()
```
or improve HTTP exception translation
Move runtime adapter imports out of handlers and route modules

Do not auto-apply broad or potentially breaking migrations without explicit justification.

Mass route/module renames
Whole-app layer rewrites
Validation library swaps across the entire repository
RPC shape changes that break existing clients
Runtime adapter swaps

当问题是局部、可回滚且低风险时，可以直接自动修复：

给被修改的路由添加缺失的校验中间件
添加缺失的类型化
```
AppType
```
导出
将路由挂载逻辑迁移到统一的组装文件中
将提取的无类型处理函数转换为
```
createFactory()
```
/
```
factory.createHandlers()
```
实现
添加
```
app.onError()
```
或者优化HTTP异常转换逻辑
将运行时适配器导入从处理函数和路由模块中迁移出去

没有明确依据时，不要自动执行大范围或可能产生破坏性的迁移：

批量路由/模块重命名
全应用层重写
整个仓库的校验库替换
破坏已有客户端的RPC结构变更
运行时适配器替换

Step 4: Implementation

步骤4：实现

When changing Hono code, prefer this order:

Validate current structure and rule breaches.
Fix route composition and typing boundaries first.
Fix validation and middleware ordering.
Fix error handling and response shaping.
Fix testing/RPC inference regressions.
Run verification.

修改Hono代码时，推荐按以下顺序执行：

校验当前结构和规则违规项
优先修复路由组装和类型边界问题
修复校验和中间件顺序问题
修复错误处理和响应格式化问题
修复测试/RPC类型推导回归问题
执行校验

Verification Checklist

校验清单

Hono project detection confirmed
Relevant rule files read
Official override mode applied when the user requested official Hono defaults
Touched files follow kebab-case naming
Route composition is obvious and mountable
Middleware order verified
Validation enforced on non-trivial inputs
Error handling policy is explicit
```
testClient
```
/
```
hc
```
/
```
AppType
```
inference still works when applicable
Runtime adapter code stays at the edge
Final findings distinguish official Hono rules from hypercore-only conventions

已确认检测到Hono项目
已阅读相关规则文件
用户要求使用Hono官方默认规则时已应用官方覆盖模式
被修改的文件遵循短横线命名法
路由组装逻辑清晰且可挂载
已验证中间件顺序
非 trivial 输入已强制校验
错误处理策略明确
适用场景下
```
testClient
```
/
```
hc
```
/
```
AppType
```
类型推导正常工作
运行时适配器代码保留在边缘入口层
最终结果已区分Hono官方规则和hypercore专属约定