02-Request与Response模型

POST /api/chat HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer sk-xxxx
 
{"model": "gpt-4", "messages": [{"role": "user", "content": "你好"}]}

origin-form:    /api/chat?stream=true
absolute-form:  https://api.example.com/api/chat
authority-form: api.example.com
asterisk-form:  *

const request = new Request('https://api.example.com/api/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk-xxxx'
  },
  body: JSON.stringify({
    model: 'gpt-4',
    messages: [{ role: 'user', content: '你好' }]
  })
})
 
// 读取各部分
request.method        // "POST"
request.url           // "https://api.example.com/api/chat"
request.headers.get('Content-Type')  // "application/json"
await request.json()  // { model: 'gpt-4', messages: [...] }

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_abc123
 
{"id": "chatcmpl-xxx", "choices": [...]}

const response = new Response(
  JSON.stringify({ id: 'chatcmpl-xxx', content: '你好' }),
  {
    status: 200,
    headers: {
      'Content-Type': 'application/json',
      'X-Request-Id': 'req_abc123'
    }
  }
)
 
response.status                  // 200
response.ok                      // true
response.headers.get('Content-Type')  // "application/json"
await response.json()            // { id: 'chatcmpl-xxx', content: '你好' }

客户端构建 Request
  ↓
DNS 解析：域名 → IP 地址
  ↓
TCP 连接：三次握手
  ↓
TLS 握手（HTTPS）：协商加密参数
  ↓
发送请求：请求行 + Headers + Body
  ↓
服务端接收并处理
  ↓
返回 Response：状态行 + Headers + Body
  ↓
客户端接收并处理 Response

请求进入 → 中间件链（日志、鉴权、CORS…）→ 路由处理 → 构建 Response → 返回

// 客户端：序列化
const body = JSON.stringify({
  model: 'gpt-4',
  messages: [
    { role: 'system', content: '你是一位有帮助的助手。' },
    { role: 'user', content: '解释一下 HTTP 协议' }
  ],
  temperature: 0.7
})
 
// 服务端：反序列化
const data = await c.req.json()
// data.model === 'gpt-4'
// data.messages.length === 2

// 典型的聊天请求体
{
  "model": "gpt-4",
  "messages": [
    { "role": "system", "content": "..." },
    { "role": "user", "content": "..." },
    { "role": "assistant", "content": "..." },
    { "role": "user", "content": "..." }
  ],
  "stream": true
}

// 工具调用响应结构
{
  "choices": [{
    "message": {
      "tool_calls": [{
        "id": "call_abc",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"location\": \"北京\"}"
        }
      }]
    }
  }]
}

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
 
data: {"content": "你"}
 
data: {"content": "好"}
 
data: {"content": "，"}
 
data: {"content": "我是"}
 
data: [DONE]

// 普通响应：Body 是完整字符串
new Response(JSON.stringify({ content: '完整回复' }), {
  headers: { 'Content-Type': 'application/json' }
})
 
// 流式响应：Body 是 ReadableStream
const stream = new ReadableStream({
  async start(controller) {
    const encoder = new TextEncoder()
    for await (const chunk of generateContent()) {
      controller.enqueue(
        encoder.encode(`data: ${JSON.stringify({ content: chunk })}\n\n`)
      )
    }
    controller.enqueue(encoder.encode('data: [DONE]\n\n'))
    controller.close()
  }
})
 
new Response(stream, {
  headers: {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive'
  }
})

import { Hono } from 'hono'
import { stream, streamSSE } from 'hono/streaming'
 
const app = new Hono()
 
// 文本流
app.get('/api/stream', (c) => {
  return stream(c, async (stream) => {
    for await (const chunk of generateContent()) {
      await stream.write(chunk)
    }
  })
})
 
// SSE 流
app.get('/api/sse', (c) => {
  return streamSSE(c, async (stream) => {
    for await (const chunk of generateContent()) {
      await stream.writeSSE({
        data: JSON.stringify({ content: chunk }),
        event: 'message'
      })
    }
  })
})

app.post('/api/chat', async (c) => {
  // 读取请求方法
  c.req.method  // "POST"
 
  // 读取路径
  c.req.path    // "/api/chat"
 
  // 读取查询参数
  c.req.query('stream')  // "true" | undefined
 
  // 读取请求头
  c.req.header('Authorization')  // "Bearer sk-xxxx"
 
  // 读取并解析 JSON Body
  const body = await c.req.json()
 
  // 路由参数
  const id = c.req.param('id')  // 来自 /api/chat/:id
})

app.get('/api/health', (c) => {
  return c.json({ status: 'ok', timestamp: Date.now() })
})
 
app.get('/api/text', (c) => {
  return c.text('Hello, World!')
})
 
// 自定义状态码和 Headers
app.get('/api/resource/:id', (c) => {
  const id = c.req.param('id')
  return c.json(
    { id, name: 'example' },
    200,
    { 'X-Request-Id': crypto.randomUUID() }
  )
})

// 设置响应头
c.res.headers.set('X-Custom-Header', 'value')
 
// 返回标准 Response 对象
return new Response('custom', {
  status: 201,
  headers: { 'Content-Type': 'text/plain' }
})

// 中间件：读取 Request，可以修改或提前返回 Response
app.use('/api/*', async (c, next) => {
  const token = c.req.header('Authorization')
  if (!token) {
    return c.json({ error: 'Unauthorized' }, 401)
  }
  await next()
  // next() 之后可以继续操作 c.res
})
 
// 路由处理：读取 Request，构建 Response
app.post('/api/chat', async (c) => {
  const body = await c.req.json()
  // 处理业务逻辑...
  return c.json({ result: 'ok' })
})