Hono 深入使用指南：从入门到精通

// 你的代码可以在任何地方运行
import { Hono } from 'hono'

const app = new Hono()

app.get('/', (c) => {
  // 使用标准 Response
  return new Response('Hello World')

  // 或使用 Hono 的便捷方法
  return c.text('Hello World')
})

// Cloudflare Workers
export default app

// Node.js
// import { serve } from '@hono/node-server'
// serve(app)

// Deno
// Deno.serve(app.fetch)

// Bun
// export default { fetch: app.fetch }

{
  "name": "hono",
  "dependencies": {}  // 完全零依赖！
}

// 默认预设 - 平衡性能和功能
import { Hono } from 'hono'

// Quick 预设 - 优化冷启动（Serverless）
import { Hono } from 'hono/quick'

// Tiny 预设 - 极致轻量（< 12KB）
import { Hono } from 'hono/tiny'

app.use('*', async (c, next) => {
  // 1. 请求开始 - Context 被创建
  console.log('Request started')

  // 2. Context 在整个请求周期内存活
  await next()

  // 3. 响应发送后 - Context 被销毁
  console.log('Request ended')
})

app.get('/user/:id', (c) => {
  // URL 参数
  const id = c.req.param('id')

  // 查询参数
  const page = c.req.query('page')           // 单个值
  const tags = c.req.queries('tag')          // 多个值数组

  // 请求头
  const auth = c.req.header('Authorization')
  const userAgent = c.req.header('User-Agent')

  // 请求方法和路径
  const method = c.req.method  // GET, POST, etc.
  const path = c.req.path      // /user/123
  const url = c.req.url        // https://example.com/user/123

  return c.json({ id, page, tags })
})

app.post('/api/data', async (c) => {
  // JSON 解析
  const json = await c.req.json()

  // 表单数据
  const formData = await c.req.formData()
  const name = formData.get('name')

  // 纯文本
  const text = await c.req.text()

  // 二进制数据
  const blob = await c.req.blob()
  const arrayBuffer = await c.req.arrayBuffer()

  return c.json({ received: json })
})

app.post('/upload', async (c) => {
  // 解析多部分表单（文件上传）
  const body = await c.req.parseBody()

  // body 结构：
  // {
  //   file: File,
  //   name: string,
  //   description: string
  // }

  const file = body.file as File

  if (file) {
    console.log('File name:', file.name)
    console.log('File size:', file.size)
    console.log('File type:', file.type)

    // 读取文件内容
    const content = await file.arrayBuffer()
  }

  return c.json({ success: true })
})

app.get('/responses', (c) => {
  // JSON 响应
  return c.json({ message: 'Hello' })

  // JSON 带状态码
  return c.json({ error: 'Not Found' }, 404)

  // 文本响应
  return c.text('Hello World')

  // HTML 响应
  return c.html('<h1>Hello</h1>')

  // 重定向
  return c.redirect('/new-path')
  return c.redirect('/new-path', 301)  // 永久重定向

  // 自定义响应
  return c.body('Custom Body', 201, {
    'X-Custom-Header': 'value'
  })

  // 直接返回 Response 对象
  return new Response('Hello', {
    status: 200,
    headers: { 'Content-Type': 'text/plain' }
  })
})

app.get('/headers', (c) => {
  // 设置单个头部
  c.header('X-Custom-Header', 'value')

  // 设置多个头部
  c.header('X-Powered-By', 'Hono')
  c.header('X-Version', '1.0.0')

  // 设置状态码
  c.status(201)

  return c.json({ created: true })
})

// 中间件设置数据
app.use('*', async (c, next) => {
  const startTime = Date.now()
  c.set('startTime', startTime)

  await next()

  const endTime = Date.now()
  console.log(`Request took ${endTime - startTime}ms`)
})

// 路由处理器获取数据
app.get('/', (c) => {
  const startTime = c.get('startTime')
  return c.json({ startTime })
})

// 定义变量类型
type Variables = {
  user: {
    id: string
    name: string
    role: 'admin' | 'user'
  }
  requestId: string
  startTime: number
}

// 创建类型化的应用
const app = new Hono<{ Variables: Variables }>()

// 中间件：类型安全的 set
app.use('*', async (c, next) => {
  c.set('requestId', crypto.randomUUID())
  c.set('startTime', Date.now())
  await next()
})

// 路由：类型安全的 get
app.get('/profile', (c) => {
  const user = c.get('user')       // 类型: { id: string, name: string, role: 'admin' | 'user' }
  const requestId = c.get('requestId')  // 类型: string

  return c.json({ user, requestId })
})

// 定义绑定类型
type Bindings = {
  DB: D1Database           // D1 数据库
  KV: KVNamespace          // KV 存储
  BUCKET: R2Bucket         // R2 对象存储
  API_KEY: string          // 环境变量
  QUEUE: Queue             // 队列
}

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

app.get('/data', async (c) => {
  // 访问绑定
  const db = c.env.DB
  const kv = c.env.KV
  const bucket = c.env.BUCKET
  const apiKey = c.env.API_KEY

  // 使用 D1
  const users = await db.prepare('SELECT * FROM users').all()

  // 使用 KV
  const cache = await kv.get('cache-key')

  // 使用 R2
  const object = await bucket.get('file.pdf')

  return c.json({ users, cache })
})

app.get('/config', (c) => {
  // 注意：Node.js 中需要通过 process.env 访问
  const apiKey = process.env.API_KEY
  const dbUrl = process.env.DATABASE_URL

  // 或者通过 c.env（需要在启动时传入）
  return c.json({ apiKey })
})

type Env = {
  Bindings: {
    DB: D1Database
    KV: KVNamespace
  }
  Variables: {
    user: User
    requestId: string
  }
}

const app = new Hono<Env>()

app.use('*', async (c, next) => {
  // c.env 的类型是 Env['Bindings']
  const db = c.env.DB

  // c.set/get 的类型是 Env['Variables']
  c.set('requestId', '123')

  await next()
})

app.use('*', async (c, next) => {
  console.log('1. 外层中间件 - 请求阶段')

  await next()  // 进入下一层

  console.log('4. 外层中间件 - 响应阶段')
})

app.use('*', async (c, next) => {
  console.log('2. 内层中间件 - 请求阶段')

  await next()  // 进入路由处理器

  console.log('3. 内层中间件 - 响应阶段')
})

app.get('/', (c) => {
  console.log('路由处理器')
  return c.text('Hello')
})

// 输出顺序：
// 1. 外层中间件 - 请求阶段
// 2. 内层中间件 - 请求阶段
// 路由处理器
// 3. 内层中间件 - 响应阶段
// 4. 外层中间件 - 响应阶段

import { Hono } from 'hono'
import { logger } from 'hono/logger'
import { cors } from 'hono/cors'
import { secureHeaders } from 'hono/secure-headers'

const app = new Hono()

// 1. 日志中间件（第一个）
app.use('*', logger())

// 2. 安全头部
app.use('*', secureHeaders())

// 3. CORS
app.use('*', cors({
  origin: ['https://example.com', 'https://app.example.com'],
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowHeaders: ['Content-Type', 'Authorization'],
  credentials: true,
}))

// 4. 请求 ID
app.use('*', async (c, next) => {
  c.set('requestId', crypto.randomUUID())
  await next()
})

// 只应用于 /api/* 路径
app.use('/api/*', async (c, next) => {
  console.log('API middleware')
  await next()
})

// 多路径中间件
app.use(['/admin/*', '/dashboard/*'], async (c, next) => {
  // 只应用于 admin 和 dashboard
  await next()
})

import { createMiddleware } from 'hono/factory'

// 计时中间件
const timing = createMiddleware(async (c, next) => {
  const start = Date.now()

  await next()

  const end = Date.now()
  c.header('X-Response-Time', `${end - start}ms`)
})

app.use('*', timing)

import { createMiddleware } from 'hono/factory'

// 限流中间件
const rateLimit = (options: {
  max: number        // 最大请求数
  window: number     // 时间窗口（ms）
}) => {
  const requests = new Map<string, number[]>()

  return createMiddleware(async (c, next) => {
    const ip = c.req.header('cf-connecting-ip') || 'unknown'
    const now = Date.now()

    // 获取该 IP 的请求记录
    let timestamps = requests.get(ip) || []

    // 清理过期记录
    timestamps = timestamps.filter(t => now - t < options.window)

    // 检查是否超限
    if (timestamps.length >= options.max) {
      return c.json({ error: 'Too Many Requests' }, 429)
    }

    // 记录本次请求
    timestamps.push(now)
    requests.set(ip, timestamps)

    await next()
  })
}

// 使用
app.use('/api/*', rateLimit({
  max: 100,
  window: 60 * 1000  // 1 分钟
}))

import { createMiddleware } from 'hono/factory'

// 定义中间件添加的变量
type AuthVariables = {
  user: {
    id: string
    email: string
    role: 'admin' | 'user'
  }
}

// 创建类型安全的中间件
const authMiddleware = createMiddleware<{ Variables: AuthVariables }>(
  async (c, next) => {
    const token = c.req.header('Authorization')?.replace('Bearer ', '')

    if (!token) {
      return c.json({ error: 'Unauthorized' }, 401)
    }

    // 验证 token
    const user = await verifyToken(token)

    if (!user) {
      return c.json({ error: 'Invalid token' }, 401)
    }

    // 设置用户信息（类型安全）
    c.set('user', user)

    await next()
  }
)

// 在类型化的应用中使用
const app = new Hono<{ Variables: AuthVariables }>()

app.use('/api/*', authMiddleware)

app.get('/api/profile', (c) => {
  // TypeScript 知道 user 的类型！
  const user = c.get('user')
  return c.json({ user })
})

import { logger } from 'hono/logger'

app.use('*', logger())

// 自定义日志格式
app.use('*', logger((message) => {
  console.log(`[${new Date().toISOString()}] ${message}`)
}))

import { cors } from 'hono/cors'

// 允许所有来源
app.use('*', cors())

// 自定义配置
app.use('*', cors({
  origin: 'https://example.com',
  allowMethods: ['GET', 'POST'],
  allowHeaders: ['Content-Type'],
  exposeHeaders: ['X-Total-Count'],
  maxAge: 3600,
  credentials: true,
}))

// 动态来源
app.use('*', cors({
  origin: (origin) => {
    return origin.endsWith('.example.com') ? origin : 'https://example.com'
  }
}))

import { jwt } from 'hono/jwt'

app.use('/api/*', jwt({
  secret: 'your-secret-key',
}))

// 访问 JWT payload
app.get('/api/me', (c) => {
  const payload = c.get('jwtPayload')
  return c.json({ user: payload })
})

import { bearerAuth } from 'hono/bearer-auth'

app.use('/admin/*', bearerAuth({
  token: 'your-secret-token',
}))

// 动态验证
app.use('/admin/*', bearerAuth({
  verifyToken: async (token, c) => {
    return token === await getValidToken()
  }
}))

import { basicAuth } from 'hono/basic-auth'

app.use('/admin/*', basicAuth({
  username: 'admin',
  password: 'secret',
}))

// 动态验证
app.use('/admin/*', basicAuth({
  verifyUser: async (username, password, c) => {
    return await checkCredentials(username, password)
  }
}))

import { compress } from 'hono/compress'

// 默认配置（gzip 优先）
app.use('*', compress())

// 自定义配置
app.use('*', compress({
  threshold: 1024,  // 最小压缩大小（字节）
  encoding: 'gzip', // 'gzip' | 'deflate'
}))

import { cache } from 'hono/cache'

app.get('/static/*', cache({
  cacheName: 'static-assets',
  cacheControl: 'max-age=31536000', // 1 年
}))

// 条件缓存
app.get('/api/data', cache({
  cacheName: 'api-cache',
  cacheControl: 'max-age=60',
  wait: true,
}))

import { etag } from 'hono/etag'

app.use('*', etag())

// 弱 ETag
app.use('*', etag({ weak: true }))

import { prettyJSON } from 'hono/pretty-json'

app.use('*', prettyJSON())

// 只在开发环境启用
if (process.env.NODE_ENV === 'development') {
  app.use('*', prettyJSON())
}

import { secureHeaders } from 'hono/secure-headers'

app.use('*', secureHeaders())

// 自定义配置
app.use('*', secureHeaders({
  contentSecurityPolicy: {
    defaultSrc: ["'self'"],
    scriptSrc: ["'self'", "'unsafe-inline'"],
    styleSrc: ["'self'", "'unsafe-inline'"],
  },
  xFrameOptions: 'DENY',
  xContentTypeOptions: 'nosniff',
}))

const app = new Hono()

// HTTP 方法
app.get('/', (c) => c.text('GET'))
app.post('/', (c) => c.text('POST'))
app.put('/', (c) => c.text('PUT'))
app.delete('/', (c) => c.text('DELETE'))
app.patch('/', (c) => c.text('PATCH'))
app.options('/', (c) => c.text('OPTIONS'))

// 所有方法
app.all('/', (c) => c.text('Any method'))

// 自定义方法
app.on('PURGE', '/', (c) => c.text('PURGE'))

// 命名参数
app.get('/users/:id', (c) => {
  const id = c.req.param('id')
  return c.json({ id })
})

// 多个参数
app.get('/posts/:category/:slug', (c) => {
  const category = c.req.param('category')
  const slug = c.req.param('slug')
  return c.json({ category, slug })
})

// 可选参数
app.get('/posts/:id?', (c) => {
  const id = c.req.param('id')  // 可能是 undefined
  return c.json({ id: id || 'all' })
})

// 通配符
app.get('/files/*', (c) => {
  const path = c.req.param('*')  // 捕获所有路径
  return c.text(`File: ${path}`)
})

// 数字 ID
app.get('/users/:id{[0-9]+}', (c) => {
  const id = c.req.param('id')  // 只匹配数字
  return c.json({ id })
})

// UUID
app.get('/items/:uuid{[0-9a-f-]{36}}', (c) => {
  const uuid = c.req.param('uuid')
  return c.json({ uuid })
})

// 自定义正则
app.get('/slugs/:slug{[a-z0-9-]+}', (c) => {
  const slug = c.req.param('slug')
  return c.json({ slug })
})

// 使用 Hono 实例分组
const api = new Hono()

api.get('/users', (c) => c.json([]))
api.get('/users/:id', (c) => c.json({}))
api.post('/users', (c) => c.json({}))

// 挂载到主应用
app.route('/api/v1', api)

// 结果：
// GET  /api/v1/users
// GET  /api/v1/users/:id
// POST /api/v1/users

app
  .get('/chain', (c) => c.text('GET'))
  .post('/chain', (c) => c.text('POST'))
  .put('/chain', (c) => c.text('PUT'))

// 或者使用 route()
app.route('/users')
  .get((c) => c.json([]))
  .post((c) => c.json({}))

// 长期运行的服务器（默认）
import { Hono } from 'hono'
const app = new Hono()
// 使用 SmartRouter: RegExpRouter + TrieRouter

// Serverless/冷启动优化
import { Hono } from 'hono/quick'
const app = new Hono()
// 使用 LinearRouter，注册路由更快

// 极致轻量
import { Hono } from 'hono/tiny'
const app = new Hono()
// 使用 PatternRouter，最小体积

// 不推荐：过多动态路由
app.get('/:a/:b/:c/:d/:e', handler)

// 推荐：合理使用静态前缀
app.get('/api/v1/users/:id/posts/:postId', handler)

// RegExpRouter 会优先匹配静态路由
app.get('/users/me', handlerMe)      // 静态，优先匹配
app.get('/users/:id', handlerId)     // 动态，次优先

// 不推荐：平铺所有路由
app.get('/api/users', handler)
app.get('/api/posts', handler)
app.get('/api/comments', handler)

// 推荐：按前缀分组
const api = new Hono()
api.get('/users', handler)
api.get('/posts', handler)
api.get('/comments', handler)

app.route('/api', api)

import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

// 定义 schema
const userSchema = z.object({
  name: z.string().min(3).max(50),
  email: z.string().email(),
  age: z.number().int().min(18).max(120),
  role: z.enum(['admin', 'user']).default('user'),
})

// 应用验证
app.post('/users', zValidator('json', userSchema), async (c) => {
  // 类型安全！data 的类型自动推导
  const data = c.req.valid('json')
  // data: { name: string, email: string, age: number, role: 'admin' | 'user' }

  const user = await db.createUser(data)
  return c.json(user, 201)
})

// JSON body
app.post('/json', zValidator('json', schema), (c) => {
  const data = c.req.valid('json')
  return c.json(data)
})

// 查询参数
const querySchema = z.object({
  page: z.string().regex(/^\d+$/).transform(Number),
  limit: z.string().regex(/^\d+$/).transform(Number),
})

app.get('/list', zValidator('query', querySchema), (c) => {
  const { page, limit } = c.req.valid('query')
  // page 和 limit 是 number 类型！
  return c.json({ page, limit })
})

// 表单数据
app.post('/form', zValidator('form', schema), (c) => {
  const data = c.req.valid('form')
  return c.json(data)
})

// 路由参数
const paramSchema = z.object({
  id: z.string().uuid(),
})

app.get('/users/:id', zValidator('param', paramSchema), (c) => {
  const { id } = c.req.valid('param')
  return c.json({ id })
})

// 请求头
const headerSchema = z.object({
  'x-api-key': z.string().min(32),
})

app.get('/protected', zValidator('header', headerSchema), (c) => {
  const headers = c.req.valid('header')
  return c.json({ authenticated: true })
})

app.post(
  '/users',
  zValidator('json', userSchema, (result, c) => {
    if (!result.success) {
      return c.json({
        error: 'Validation failed',
        details: result.error.flatten(),
      }, 400)
    }
  }),
  (c) => {
    const data = c.req.valid('json')
    return c.json({ success: true, data })
  }
)

import { z } from 'zod'

// 嵌套对象
const addressSchema = z.object({
  street: z.string(),
  city: z.string(),
  zipCode: z.string().regex(/^\d{5}$/),
  country: z.string().length(2),
})

const createUserSchema = z.object({
  name: z.string().min(3),
  email: z.string().email(),
  password: z.string()
    .min(8, 'Password must be at least 8 characters')
    .regex(/[A-Z]/, 'Password must contain an uppercase letter')
    .regex(/[a-z]/, 'Password must contain a lowercase letter')
    .regex(/[0-9]/, 'Password must contain a number'),
  address: addressSchema,
  tags: z.array(z.string()).min(1).max(10),
  metadata: z.record(z.string(), z.any()).optional(),
})

app.post('/users', zValidator('json', createUserSchema), async (c) => {
  const data = c.req.valid('json')
  // 完全类型安全的数据
  return c.json({ success: true })
})

// 字符串转数字
const paginationSchema = z.object({
  page: z.string().transform(Number),
  limit: z.string().transform(Number).default('10'),
})

app.get('/items', zValidator('query', paginationSchema), (c) => {
  const { page, limit } = c.req.valid('query')
  // page 和 limit 是 number 类型
  return c.json({ page, limit })
})

// 自定义转换
const dateSchema = z.object({
  date: z.string().transform((val) => new Date(val)),
})

app.get('/events', zValidator('query', dateSchema), (c) => {
  const { date } = c.req.valid('query')
  // date 是 Date 对象
  return c.json({ date: date.toISOString() })
})

import { vValidator } from '@hono/valibot-validator'
import * as v from 'valibot'

const schema = v.object({
  name: v.string([v.minLength(3)]),
  email: v.string([v.email()]),
})

app.post('/users', vValidator('json', schema), (c) => {
  const data = c.req.valid('json')
  return c.json(data)
})

import { tbValidator } from '@hono/typebox-validator'
import { Type } from '@sinclair/typebox'

const schema = Type.Object({
  name: Type.String({ minLength: 3 }),
  email: Type.String({ format: 'email' }),
})

app.post('/users', tbValidator('json', schema), (c) => {
  const data = c.req.valid('json')
  return c.json(data)
})