Middlewares 层设计

// directory
src/
  middleware/
    auth.ts        认证中间件（JWT 验证）
    api-key.ts     API Key 验证中间件
    logger.ts      请求日志中间件
    error.ts       错误处理（onError 注册）
    request-id.ts  请求 ID 注入
    permissions.ts 权限校验中间件

// src/index.ts
import { Hono } from 'hono'
import { logger } from 'hono/logger'
import { cors } from 'hono/cors'
import { secureHeaders } from 'hono/secure-headers'
import type { AppEnv } from './types'
import { requestIdMiddleware } from './middleware/request-id'
import { authMiddleware } from './middleware/auth'
import { registerErrorHandler } from './middleware/error'
 
const app = new Hono<AppEnv>()
 
// 1. 日志——最先注册，确保所有请求（包括被后续中间件拦截的）都有日志
app.use('*', logger())
 
// 2. 请求 ID——在日志之后，这样日志里就能带上请求 ID
app.use('*', requestIdMiddleware())
 
// 3. CORS——在鉴权之前，因为浏览器跨域的 OPTIONS 预检请求不带 token
app.use('*', cors({
  origin: ['https://example.com'],
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
}))
 
// 4. 安全响应头
app.use('*', secureHeaders())
 
// 5. 认证——只有 /api/* 下的接口需要
app.use('/api/*', authMiddleware())
 
// 6. 错误兜底——注册在最外层
registerErrorHandler(app)

// src/routes/admin.ts
import { Hono } from 'hono'
import type { AppEnv } from '../types'
import { adminOnlyMiddleware } from '../middleware/permissions'
 
export const adminApp = new Hono<AppEnv>()
 
// admin 组下的所有接口都要先过 adminOnly
adminApp.use('*', adminOnlyMiddleware())
 
adminApp.get('/stats', async (c) => {
  // 能走到这里，说明已经是管理员了
  return c.json({ totalUsers: 1024 })
})
 
adminApp.delete('/users/:id', async (c) => {
  const id = c.req.param('id')
  // 删除操作
  return c.json({ message: `User ${id} deleted` })
})

// src/routes/posts.ts
import { Hono } from 'hono'
import type { AppEnv } from '../types'
import { authMiddleware } from '../middleware/auth'
import { ownerOnlyMiddleware } from '../middleware/permissions'
 
export const postsApp = new Hono<AppEnv>()
 
// 获取文章列表——公开接口，不需要认证
postsApp.get('/', async (c) => {
  // ...
  return c.json(posts)
})
 
// 删除文章——需要认证 + 作者本人
postsApp.delete('/:id', authMiddleware(), ownerOnlyMiddleware(), async (c) => {
  const id = c.req.param('id')
  // ...
  return c.json({ message: `Post ${id} deleted` })
})

// src/middleware/auth.ts
import { createMiddleware } from 'hono/factory'
import type { AppEnv } from '../types'
 
export const authMiddleware = createMiddleware<AppEnv>(async (c, next) => {
  const header = c.req.header('Authorization')
 
  if (!header || !header.startsWith('Bearer ')) {
    return c.json({ error: 'Missing or invalid Authorization header' }, 401)
  }
 
  const token = header.slice(7)
 
  try {
    const secret = c.env.JWT_SECRET
    // 这里省略了具体的 JWT 验证逻辑
    // 假设 verifyJWT 返回解码后的 payload
    const payload = await verifyJWT(token, secret)
 
    // 把用户信息写入 context，后面的路由可以直接取
    c.set('user', {
      id: payload.sub,
      email: payload.email,
      role: payload.role,
    })
 
    await next()
  } catch {
    return c.json({ error: 'Invalid or expired token' }, 401)
  }
})

// anti-pattern.ts
// 不要这样写
app.get('/api/users', async (c) => {
  try {
    const users = await db.select().from(usersTable)
    return c.json(users)
  } catch (error) {
    console.error(error)
    return c.json({ error: 'Internal Server Error' }, 500)
  }
})

// src/middleware/error.ts
import type { AppEnv } from '../types'
import type { Hono } from 'hono'
 
// 自定义错误基类，方便区分业务异常和系统异常
export class AppError extends Error {
  constructor(
    public statusCode: number,
    public message: string,
    public code?: string,
  ) {
    super(message)
  }
}
 
export class NotFoundError extends AppError {
  constructor(resource: string) {
    super(404, `${resource} not found`, 'NOT_FOUND')
  }
}
 
export class UnauthorizedError extends AppError {
  constructor(message = 'Unauthorized') {
    super(401, message, 'UNAUTHORIZED')
  }
}
 
// 注册全局错误处理器
export function registerErrorHandler(app: Hono<AppEnv>) {
  app.onError((err, c) => {
    // 业务异常：有明确的状态码和消息
    if (err instanceof AppError) {
      return c.json(
        { error: err.message, code: err.code },
        err.statusCode,
      )
    }
 
    // 系统异常：不暴露具体错误信息给客户端
    console.error(`[Unhandled Error] ${err.message}`, err.stack)
 
    return c.json(
      { error: 'Internal Server Error', code: 'INTERNAL_ERROR' },
      500,
    )
  })
}

// src/routes/users.ts
import { Hono } from 'hono'
import type { AppEnv } from '../types'
import { NotFoundError } from '../middleware/error'
 
export const usersApp = new Hono<AppEnv>()
 
usersApp.get('/:id', async (c) => {
  const id = c.req.param('id')
  const user = await db.select().from(usersTable).where(eq(usersTable.id, id))
 
  if (!user) {
    // 直接抛错，onError 会统一处理响应格式
    throw new NotFoundError('User')
  }
 
  return c.json(user)
})

// src/middleware/request-id.ts
import { createMiddleware } from 'hono/factory'
import type { AppEnv } from '../types'
 
export const requestIdMiddleware = createMiddleware<AppEnv>(async (c, next) => {
  // 生成一个请求 ID，优先用客户端传过来的（方便前端追踪）
  const requestId = c.req.header('X-Request-ID') || crypto.randomUUID()
 
  // 写入 context
  c.set('requestId', requestId)
 
  await next()
 
  // 在响应头里也带上，方便客户端排查问题
  c.header('X-Request-ID', requestId)
})

// src/types.ts
export type AppEnv = {
  Bindings: {
    JWT_SECRET: string
    DB: D1Database
  }
  Variables: {
    // 每个字段对应一个 c.set() 的 key
    user: {
      id: number
      email: string
      role: string
    }
    requestId: string
    db: DrizzleD1Database
  }
}

// flow
请求进入
  → logger 中间件：（不写入 context，只打印日志）
  → requestId 中间件：c.set('requestId', 'abc-123')
  → auth 中间件：c.set('user', { id: 1, email: '...', role: 'admin' })
  → 路由 handler：c.get('requestId'), c.get('user')

// wrong-order.ts
// 鉴权中间件在前，CORS 在后
app.use('/api/*', async (c, next) => {
  const token = c.req.header('Authorization')
  if (!token) {
    return c.json({ error: 'Unauthorized' }, 401)
  }
  await next()
})
app.use('/api/*', cors({ origin: 'http://localhost:3000' }))