04-REST API设计规范

# 好
GET    /users
POST   /users
GET    /users/42
PATCH  /users/42
DELETE /users/42
 
# 不好
GET    /getUsers
POST   /createUser
POST   /deleteUser

GET /users/42/conversations
GET /users/42/conversations/7

GET /users?page=2&per_page=20
GET /users?sort=created_at&order=desc
GET /users?role=admin&status=active

// 成功响应
{
  "data": {
    "id": 42,
    "name": "白川",
    "role": "admin"
  }
}
 
// 列表响应
{
  "data": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 156
  }
}
 
// 错误响应（OpenAI 风格）
{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

# offset-based（传统）
GET /users?page=3&per_page=20
 
# cursor-based（游标）
GET /users?cursor=eyJpZCI6NjB9&limit=20

# URL 路径
GET /v1/users
GET /v2/users
 
# Header
GET /users
Api-Version: 2024-01-15

POST /users
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
 
{ "name": "白川" }

// 前端生成请求 ID
const requestId = crypto.randomUUID()
 
const response = await fetch('/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Idempotency-Key': requestId,
  },
  body: JSON.stringify({
    model: 'gpt-4',
    messages: [{ role: 'user', content: '帮我写一篇文章' }],
  }),
})

// middleware/idempotency.ts
import { Context, Next } from 'hono'
 
export async function idempotencyMiddleware(c: Context, next: Next) {
  const key = c.req.header('Idempotency-Key')
 
  if (key) {
    // 查缓存/数据库，看这个 key 是否已经处理过
    const cached = await c.env.IDEMPOTENCY_KV.get(`req:${key}`)
    if (cached) {
      return c.json(JSON.parse(cached), 200)
    }
  }
 
  await next()
 
  // 请求成功后，缓存结果
  if (key && c.res.status === 200) {
    const body = await c.res.clone().json()
    await c.env.IDEMPOTENCY_KV.put(`req:${key}`, JSON.stringify(body), {
      expirationTtl: 86400, // 24 小时过期
    })
  }
}

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

# 非流式
POST /v1/chat/completions
{ "stream": false }
 
# 流式
POST /v1/chat/completions
{ "stream": true }

// 请求
{
  "model": "gpt-4",
  "messages": [
    { "role": "user", "content": "北京今天天气怎么样？" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    }
  ]
}

// 响应
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\":\"北京\"}"
        }
      }]
    }
  }]
}

# 方案 A：同步等待（短任务）
POST /v1/chat/completions
→ 等待 5-15 秒 → 200 OK + 结果
 
# 方案 B：异步轮询（长任务）
POST /v1/images/generations
→ 202 Accepted + { "task_id": "xxx", "status": "processing" }
 
GET /v1/tasks/xxx
→ 200 OK + { "task_id": "xxx", "status": "completed", "result": {...} }

// routes/chat.ts
import { Hono } from 'hono'
import { z } from 'zod'
import { zValidator } from '@hono/zod-validator'
 
type Bindings = {
  OPENAI_API_KEY: string
  IDEMPOTENCY_KV: KVNamespace
}
 
const chatSchema = z.object({
  model: z.string(),
  messages: z.array(z.object({
    role: z.enum(['system', 'user', 'assistant']),
    content: z.string(),
  })),
  stream: z.boolean().optional().default(false),
  temperature: z.number().min(0).max(2).optional(),
  max_tokens: z.number().positive().optional(),
})
 
const chat = new Hono<{ Bindings: Bindings }>()
 
// POST /v1/chat/completions
chat.post('/completions', zValidator('json', chatSchema), async (c) => {
  const body = c.req.valid('json')
  const idempotencyKey = c.req.header('Idempotency-Key')
 
  // 幂等性检查
  if (idempotencyKey) {
    const cached = await c.env.IDEMPOTENCY_KV.get(`chat:${idempotencyKey}`)
    if (cached) {
      return c.json(JSON.parse(cached))
    }
  }
 
  // 调用大模型 API
  const response = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${c.env.OPENAI_API_KEY}`,
    },
    body: JSON.stringify(body),
  })
 
  if (!body.stream) {
    // 非流式：直接返回 JSON
    const result = await response.json()
 
    // 缓存结果用于幂等
    if (idempotencyKey) {
      await c.env.IDEMPOTENCY_KV.put(
        `chat:${idempotencyKey}`,
        JSON.stringify(result),
        { expirationTtl: 86400 }
      )
    }
 
    return c.json(result)
  }
 
  // 流式：透传 SSE
  return new Response(response.body, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
    },
  })
})
 
// GET /v1/chat/conversations/:id/messages
// 获取对话历史（cursor-based 分页）
chat.get('/conversations/:id/messages', async (c) => {
  const conversationId = c.req.param('id')
  const cursor = c.req.query('cursor')
  const limit = Number(c.req.query('limit') ?? 20)
 
  // 从数据库查询，cursor 指向某条消息的 ID
  // ... 省略数据库查询逻辑
 
  return c.json({
    data: messages,
    meta: {
      next_cursor: messages.length === limit
        ? messages[messages.length - 1].id
        : null,
    },
  })
})
 
export default chat

// index.ts
import { Hono } from 'hono'
import chat from './routes/chat'
 
const app = new Hono()
 
// 版本路由
const v1 = new Hono()
v1.route('/chat', chat)
 
app.route('/v1', v1)
 
// 全局错误处理
app.onError((err, c) => {
  console.error(err)
  return c.json({
    error: {
      message: err.message ?? 'Internal server error',
      type: 'server_error',
      code: 'internal_error',
    },
  }, 500)
})
 
export default app