# Hono API 脚手架将结构化 API 路由添加到现有的 Cloudflare Workers 项目。此技能在项目 shell 存在后运行（通过 cloudflare-worker-builder 或 vite-flare-starter）并生成路由文件、中间件和端点文档。 ## 工作流程 ### 第 1 步：收集端点确定 API 需要什么。询问用户或从项目描述中推断。按资源对端点进行分组：用户：GET /api/users、GET /api/users/:id、POST /api/users、PUT /api/users/:id、DELETE /api/users/:id 帖子：GET /api/posts、GET /api/posts/:id、POST /api/posts、PUT /api/posts/:id 身份验证：POST /api/auth/login、POST /api/auth/logout、GET /api/auth/me ### 第 2 步：创建路线文件每个资源组一个文件。使用 [assets/route-template.ts]() 中的模板： // src/routes/users.ts 从 'hono' 导入 { Hono } 从 '@hono/zod-validator' 导入 { zValidator } 从 'zod' 导入 { z } 从 '../types' 导入类型 { Env } const app = new Hono<{ 绑定: Env }>() // 获取/api/用户 app.get('/', 异步 (c) => { const db = c.env.DB const { results } = wait db.prepare('SELECT * FROM users').all() 返回 c.json({ 用户: 结果 }) }) // 获取 /api/users/:id app.get('/:id', async (c) => { const id = c.req.param('id') const user = wait db.prepare('SELECT * FROM users WHERE id = ?').bind(id).first() if (!user) return c.json({ error: '未找到' }, 404) 返回 c.json({ 用户 }) }) // POST /api/用户 const createUserSchema = z.object({ 名称：z.string().min(1), 电子邮件：z.string().email(), }) app.post('/', zValidator('json', createUserSchema), async (c) => { const body = c.req.valid('json') // ... 插入逻辑返回 c.json({ 用户 }, 201) }) 导出默认应用程序 ### 步骤 3：添加中间件根据项目需求，从 [assets/middleware-template.ts]() 添加： **身份验证中间件** — 保护需要身份验证的路由：从'hono/factory'导入{createMiddleware} 从 '../types' 导入类型 { Env } 导出 const requireAuth = createMiddleware<{ 绑定：Env }>(async (c, next) => { const token = c.req.header('授权')?.replace('承载', '') if (!token) return c.json({ error: '未经授权' }, 401) // 验证令牌... 等待下一个() }) **CORS** — 使用 Hono 的内置功能：从 'hono/cors' 导入 { cors } app.use('/api/*', cors({ origin: ['https://example.com'] })) ### 步骤 4：布线在主入口点挂载所有路由组： // src/index.ts 从 'hono' 导入 { Hono } 从 './types' 导入类型 { Env } 从 './routes/users' 导入用户从“./routes/posts”导入帖子从“./routes/auth”导入身份验证从 './middleware/error-handler' 导入 { errorHandler } const app = new Hono<{ 绑定: Env }>() // 全局错误处理程序 app.onError(错误处理程序) // 挂载路线 app.route('/api/users', 用户) app.route('/api/posts', 帖子) app.route('/api/auth', auth) // 健康检查 app.get('/api/health', (c) => c.json({ status: 'ok' })) 导出默认应用程序 ### 步骤 5：创建类型 // src/types.ts 导出接口环境 { 数据库：D1数据库 KV: KVNamespace // 如果需要 R2: R2Bucket // 如果需要 API_SECRET: string // 秘密 } ### 第6步：生成API_ENDPOINTS.md 记录所有端点。请参阅 [references/endpoint-docs-template.md]() 了解格式： ## POST /api/用户创建一个新用户。 - **Auth**：必需（不记名令牌） - **正文**：`{名称：字符串，电子邮件：字符串}` - **响应 201**：`{ 用户：用户 }` - **响应 400**：`{ 错误：字符串，详细信息：ZodError }` ## 关键模式 ### Zod 验证始终使用“@hono/zod-validator”验证请求主体：从 '@hono/zod-validator' 导入 { zValidator } app.post('/', zValidator('json', schema), async (c) => { const body = c.req.valid('json') // 完全类型化 }) 安装：`pnpm add @hono/zod-validator zod` ### 错误处理使用 [assets/error-handler.ts]() 中的标准错误处理程序：导出 const errorHandler = (err: 错误, c: 上下文) => { 控制台.错误（错误）返回 c.json({ 错误: err.message }, 500) } **API 路由必须返回 JSON 错误，而不是重定向。** `fetch()` 默默地遵循重定向，然后客户端尝试将 HTML 解析为 JSON。 ### RPC 类型安全对于 Worker 和 client 之间的端到端类型安全： // Worker: 导出app类型导出类型 AppType = 应用程序类型 // 客户端：使用hc（Hono客户端）从 'hono/client' 导入 { hc } 从 '../worker/src/index' 导入类型 { AppType } const client = hc('https://api.example.com') const res = wait client.api.users.$get() // 完全类型化 ### 路由组与单个文件项目规模|结构 ---|--- < 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]() | Auth中间件模板 [assets/error-handler.ts]() |标准 JSON 错误处理程序

Hono Api 脚手架

包含技能