hono-api-scaffolder

Hono API 脚手架

为现有的 Cloudflare Workers 项目添加结构化 API 路由。此技能会在项目框架就绪后（通过 cloudflare-worker-builder 或 vite-flare-starter）运行，并生成路由文件、中间件和端点文档。

工作流

步骤 1：收集端点

确定 API 需要哪些内容。可以询问用户，也可以根据项目描述推断。按资源对端点分组：

Users:    GET /api/users, GET /api/users/:id, POST /api/users, PUT /api/users/:id, DELETE /api/users/:id
Posts:    GET /api/posts, GET /api/posts/:id, POST /api/posts, PUT /api/posts/:id
Auth:     POST /api/auth/login, POST /api/auth/logout, GET /api/auth/me

步骤 2：创建路由文件

每个资源组创建一个文件。使用 assets/route-template.ts 中的模板：

// src/routes/users.ts
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'
import type { Env } from '../types'

const app = new Hono<{ Bindings: Env }>()

// GET /api/users
app.get('/', async (c) => {
  const db = c.env.DB
  const { results } = await db.prepare('SELECT * FROM users').all()
  return c.json({ users: results })
})

// GET /api/users/:id
app.get('/:id', async (c) => {
  const id = c.req.param('id')
  const user = await db.prepare('SELECT * FROM users WHERE id = ?').bind(id).first()
  if (!user) return c.json({ error: 'Not found' }, 404)
  return c.json({ user })
})

// POST /api/users
const createUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
})

app.post('/', zValidator('json', createUserSchema), async (c) => {
  const body = c.req.valid('json')
  // ... insert logic
  return c.json({ user }, 201)
})

export default app

步骤 3：添加中间件

根据项目需求，从 assets/middleware-template.ts 添加中间件：

身份验证中间件 — 保护需要身份验证的路由：

import { createMiddleware } from 'hono/factory'
import type { Env } from '../types'

export const requireAuth = createMiddleware<{ Bindings: Env }>(async (c, next) => {
  const token = c.req.header('Authorization')?.replace('Bearer ', '')
  if (!token) return c.json({ error: 'Unauthorized' }, 401)
  // Validate token...
  await next()
})

CORS — 使用 Hono 内置功能：

import { cors } from 'hono/cors'
app.use('/api/*', cors({ origin: ['https://example.com'] }))

步骤 4：接入路由

在主入口点挂载所有路由组：

// src/index.ts
import { Hono } from 'hono'
import type { Env } from './types'
import users from './routes/users'
import posts from './routes/posts'
import auth from './routes/auth'
import { errorHandler } from './middleware/error-handler'

const app = new Hono<{ Bindings: Env }>()

// Global error handler
app.onError(errorHandler)

// Mount routes
app.route('/api/users', users)
app.route('/api/posts', posts)
app.route('/api/auth', auth)

// Health check
app.get('/api/health', (c) => c.json({ status: 'ok' }))

export default app

步骤 5：创建类型

// src/types.ts
export interface Env {
  DB: D1Database
  KV: KVNamespace      // if needed
  R2: R2Bucket         // if needed
  API_SECRET: string   // secrets
}

步骤 6：生成 API_ENDPOINTS.md

记录所有端点。格式请参见 references/endpoint-docs-template.md：

## POST /api/users
Create a new user.
- **Auth**: Required (Bearer token)
- **Body**: `{ name: string, email: string }`
- **Response 201**: `{ user: User }`
- **Response 400**: `{ error: string, details: ZodError }`

关键模式

Zod 验证

始终使用 @hono/zod-validator 验证请求正文：

import { zValidator } from '@hono/zod-validator'
app.post('/', zValidator('json', schema), async (c) => {
  const body = c.req.valid('json')  // fully typed
})

安装：pnpm add @hono/zod-validator zod

错误处理

使用 assets/error-handler.ts 中的标准错误处理程序：

export const errorHandler = (err: Error, c: Context) => {
  console.error(err)
  return c.json({ error: err.message }, 500)
}

API 路由必须返回 JSON 错误，而不是重定向。 fetch() 会静默跟随重定向，之后客户端会尝试将 HTML 解析为 JSON。

RPC 类型安全

要在 Worker 和客户端之间实现端到端类型安全：

// Worker: export the app type
export type AppType = typeof app

// Client: use hc (Hono Client)
import { hc } from 'hono/client'
import type { AppType } from '../worker/src/index'

const client = hc<AppType>('https://api.example.com')
const res = await client.api.users.$get()  // fully typed

路由组与单文件

项目规模	结构
< 10 个端点	使用包含所有路由的单个 index.ts
10-30 个端点	按资源拆分路由文件（routes/users.ts）
30+ 个端点	路由文件 + 共享中间件 + 类型化上下文

参考文件

适用场景	阅读
Hono 模式、中间件、RPC	references/hono-patterns.md
API_ENDPOINTS.md 格式	references/endpoint-docs-template.md

资源

文件	用途
assets/route-template.ts	包含 CRUD 和 Zod 的路由文件模板
assets/middleware-template.ts	身份验证中间件模板
assets/error-handler.ts	标准 JSON 错误处理程序