03-Headers、Body、Status Code

POST /v1/chat/completions HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer sk-xxxxx
X-Request-Id: req_abc123

import { Hono } from 'hono'
 
const app = new Hono()
 
app.post('/v1/chat/completions', (c) => {
  // 读取单个 Header
  const contentType = c.req.header('Content-Type')
  // → 'application/json'
 
  // 读取 Authorization
  const auth = c.req.header('Authorization')
  // → 'Bearer sk-xxxxx'
 
  // 读取自定义 Header
  const requestId = c.req.header('X-Request-Id')
 
  return c.json({ requestId })
})

app.get('/v1/models', (c) => {
  // 方式一：通过 c.header()
  c.header('X-Request-Id', 'req_abc123')
  c.header('Cache-Control', 'no-store')
  c.header('X-RateLimit-Remaining', '97')
 
  return c.json({ models: [] })
})
 
// 方式二：直接操作 Response Headers
app.get('/v1/status', (c) => {
  return new Response('OK', {
    headers: {
      'X-Request-Id': 'req_abc123',
      'Content-Type': 'text/plain',
    },
  })
})

// 全局限流和追踪中间件
app.use('*', async (c, next) => {
  const requestId = crypto.randomUUID()
 
  // 请求头：记录客户端信息
  const clientIp = c.req.header('X-Forwarded-For') ?? 'unknown'
  const userAgent = c.req.header('User-Agent') ?? ''
 
  await next()
 
  // 响应头：回传追踪信息和限流状态
  c.res.headers.set('X-Request-Id', requestId)
  c.res.headers.set('X-RateLimit-Limit', '100')
  c.res.headers.set('X-RateLimit-Remaining', '97')
  c.res.headers.set('Cache-Control', 'no-store')
})

{
  "model": "gpt-4",
  "messages": [
    { "role": "user", "content": "Hello" }
  ],
  "stream": true
}

app.post('/v1/audio/transcriptions', async (c) => {
  const reader = c.req.raw.body.getReader()
 
  let totalSize = 0
  while (true) {
    const { done, value } = await reader.read()
    if (done) break
 
    totalSize += value.byteLength
    // 逐块处理，不需要把整个文件放内存
  }
 
  return c.json({ totalSize })
})

app.post('/v1/chat/completions', async (c) => {
  // JSON Body → 自动解析
  const body = await c.req.json()
  // body.model === 'gpt-4'
 
  // 纯文本 Body
  const text = await c.req.text()
 
  // Form Data（含文件上传）
  const formData = await c.req.formData()
  const file = formData.get('image') as File
 
  return c.json({ received: true })
})

// JSON 响应
app.get('/v1/models', (c) => {
  return c.json({
    object: 'list',
    data: [{ id: 'gpt-4', object: 'model' }],
  })
})
 
// 纯文本响应
app.get('/health', (c) => {
  return c.text('OK')
})
 
// 流式 SSE 响应
app.post('/v1/chat/completions', async (c) => {
  const stream = new ReadableStream({
    async start(controller) {
      const encoder = new TextEncoder()
 
      // 模拟逐 token 输出
      const tokens = ['你', '好', '，', '世界', '！']
      for (const token of tokens) {
        const chunk = {
          choices: [{ delta: { content: token } }],
        }
        controller.enqueue(
          encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`)
        )
        // 模拟生成延迟
        await new Promise((r) => setTimeout(r, 100))
      }
 
      // 发送结束标记
      controller.enqueue(encoder.encode('data: [DONE]\n\n'))
      controller.close()
    },
  })
 
  return new Response(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-store',
      'Connection': 'keep-alive',
    },
  })
})

import { streamSSE } from 'hono/streaming'
 
app.post('/v1/chat/completions', async (c) => {
  return streamSSE(c, async (stream) => {
    const tokens = ['你', '好', '，', '世界', '！']
 
    for (const token of tokens) {
      const chunk = {
        choices: [{ delta: { content: token } }],
      }
      await stream.writeSSE({
        data: JSON.stringify(chunk),
        event: 'message',
      })
      await stream.sleep(100)
    }
 
    await stream.writeSSE({ data: '[DONE]' })
  })
})

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718880030
 
{
  "error": {
    "message": "Rate limit exceeded. Please retry after 30 seconds.",
    "type": "rate_limit_exceeded"
  }
}

// 401：认证失败
if (!apiKey || !isValidApiKey(apiKey)) {
  return c.json(
    { error: { message: 'Invalid API key', type: 'authentication_error' } },
    401
  )
}
 
// 403：授权失败
if (!hasModelAccess(user, 'gpt-4')) {
  return c.json(
    { error: { message: 'No access to this model', type: 'permission_error' } },
    403
  )
}

if (body.temperature && typeof body.temperature !== 'number') {
  return c.json(
    {
      error: {
        message: 'temperature must be a number',
        type: 'invalid_request_error',
        param: 'temperature',
      },
    },
    422
  )
}

if (!isModelAvailable('gpt-4')) {
  c.header('Retry-After', '60')
  return c.json(
    { error: { message: 'Model is temporarily unavailable', type: 'service_unavailable' } },
    503
  )
}

// 200（默认）
app.get('/v1/models', (c) => {
  return c.json({ data: [] })
})
 
// 201 Created
app.post('/v1/fine_tuning/jobs', async (c) => {
  const job = await createFineTuningJob(await c.req.json())
  return c.json(job, 201)
})
 
// 204 No Content
app.delete('/v1/models/:id', (c) => {
  deleteModel(c.req.param('id'))
  return c.body(null, 204)
})

// 统一错误响应格式
const errorResponse = (c: Context, status: number, message: string, type: string) => {
  return c.json(
    {
      error: {
        message,
        type,
      },
    },
    status
  )
}
 
app.post('/v1/chat/completions', async (c) => {
  // 参数校验
  const body = await c.req.json().catch(() => null)
  if (!body) {
    return errorResponse(c, 400, 'Invalid JSON', 'invalid_request_error')
  }
 
  if (!body.messages || !Array.isArray(body.messages)) {
    return errorResponse(c, 422, 'messages is required and must be an array', 'invalid_request_error')
  }
 
  // 业务逻辑
  try {
    const result = await callModel(body)
    return c.json(result)
  } catch (err) {
    if (err instanceof ModelUnavailableError) {
      c.header('Retry-After', '60')
      return errorResponse(c, 503, 'Model unavailable', 'service_unavailable')
    }
    return errorResponse(c, 500, 'Internal server error', 'server_error')
  }
})

app.onError((err, c) => {
  console.error('Unhandled error:', err)
 
  // 根据环境返回不同详细程度
  const message =
    process.env.NODE_ENV === 'production'
      ? 'Internal server error'
      : err.message
 
  return c.json(
    {
      error: {
        message,
        type: 'server_error',
      },
    },
    500
  )
})
 
// 404 兜底
app.notFound((c) => {
  return c.json(
    {
      error: {
        message: `Cannot ${c.req.method} ${c.req.path}`,
        type: 'not_found_error',
      },
    },
    404
  )
})