implementing-api-patterns

API 模式技能

用途

根据具体用例，采用最合适的模式和框架来设计和实现 API。根据 API 消费方、性能要求和类型安全需求，在 REST、GraphQL、gRPC 和 tRPC 之间进行选择。

何时使用此技能

适用于：

• 为 Web、移动端或服务消费方构建后端 API
• 将前端组件（表单、表格、仪表板）连接到数据库
• 实现分页、速率限制或缓存策略
• 自动生成 OpenAPI 文档
• 在 REST、GraphQL、gRPC 或 tRPC 模式之间进行选择
• 集成身份验证和授权
• 优化 API 性能和可扩展性

快速决策框架

WHO CONSUMES YOUR API?
├─ PUBLIC/THIRD-PARTY DEVELOPERS → REST with OpenAPI
│  ├─ Python → FastAPI (auto-docs, 40k req/s)
│  ├─ TypeScript → Hono (edge-first, 50k req/s, 14KB)
│  ├─ Rust → Axum (140k req/s, <1ms latency)
│  └─ Go → Gin (100k+ req/s, mature ecosystem)
│
├─ FRONTEND TEAM (same org)
│  ├─ TypeScript full-stack? → tRPC (E2E type safety)
│  └─ Complex data needs? → GraphQL
│      ├─ Python → Strawberry
│      ├─ Rust → async-graphql
│      ├─ Go → gqlgen
│      └─ TypeScript → Pothos
│
├─ SERVICE-TO-SERVICE (microservices)
│  └─ High performance → gRPC
│      ├─ Rust → Tonic
│      ├─ Go → Connect-Go (browser-friendly)
│      └─ Python → grpcio
│
└─ MOBILE APPS
   ├─ Bandwidth constrained → GraphQL (request only needed fields)
   └─ Simple CRUD → REST (standard, well-understood)

REST 框架选择

Python：FastAPI（推荐）

主要功能： 自动生成 OpenAPI 文档、Pydantic v2 验证、async/await、40k req/s

基本示例：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.post("/items")
async def create_item(item: Item):
    return {"id": 1, **item.dict()}

有关 FastAPI 模式，请参阅 references/rest-design-principles.md 和 examples/python-fastapi/。

TypeScript：Hono（边缘优先）

主要功能： 14KB 包体积、可在任何运行时上运行（Node/Deno/Bun/edge）、Zod 验证、50k req/s

基本示例：

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

const app = new Hono()
app.post('/items', zValidator('json', z.object({
  name: z.string(), price: z.number()
})), (c) => c.json({ id: 1, ...c.req.valid('json') }))

有关 Hono 模式，请参阅 references/rest-design-principles.md 和 examples/typescript-hono/。

TypeScript：tRPC（全栈类型安全）

主要功能： 无需代码生成、端到端类型安全、React Query 集成、WebSocket 订阅

基本示例：

import { initTRPC } from '@trpc/server'
import { z } from 'zod'

const t = initTRPC.create()
export const appRouter = t.router({
  createItem: t.procedure
    .input(z.object({ name: z.string(), price: z.number() }))
    .mutation(({ input }) => ({ id: '1', ...input }))
})
export type AppRouter = typeof appRouter

有关配置模式，请参阅 references/trpc-setup-guide.md 和 examples/typescript-trpc/。

Rust：Axum（高性能）

主要功能： Tower 中间件、类型安全的提取器、140k req/s、编译时验证

基本示例：

use axum::{routing::post, Json, Router};
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct CreateItem { name: String, price: f64 }

#[derive(Serialize)]
struct Item { id: u64, name: String, price: f64 }

async fn create_item(Json(payload): Json<CreateItem>) -> Json<Item> {
    Json(Item { id: 1, name: payload.name, price: payload.price })
}

有关 Axum 模式，请参阅 references/rest-design-principles.md 和 examples/rust-axum/。

Go：Gin（成熟的生态系统）

主要功能： Go 生态系统中规模最大、100k+ req/s、结构体标签验证

基本示例：

type Item struct {
    Name  string  `json:"name" binding:"required"`
    Price float64 `json:"price" binding:"required,gt=0"`
}

r := gin.Default()
r.POST("/items", func(c *gin.Context) {
    var item Item
    if c.ShouldBindJSON(&item); err != nil {
        c.JSON(400, gin.H{"error": err.Error()}); return
    }
    c.JSON(201, item)
})

有关 Gin 模式，请参阅 references/rest-design-principles.md 和 examples/go-gin/。

性能基准

语言	框架	Req/s	延迟	冷启动	内存	最适用于
Rust	Actix-web	~150k	<1ms	N/A	2-5MB	最大吞吐量
Rust	Axum	~140k	<1ms	N/A	2-5MB	易用性 + 性能
Go	Gin	~100k+	1-2ms	N/A	5-10MB	成熟的生态系统
TypeScript	Hono	~50k	<5ms	<5ms	128MB	边缘部署
Python	FastAPI	~40k	5-10ms	1-2s	30-50MB	开发者体验
TypeScript	Express	~15k	10-20ms	1-3s	50-100MB	遗留系统

注意：

• 基准测试假设使用单核和 JSON 响应
• 实际性能会随工作负载复杂度而变化
• 冷启动仅适用于无服务器／边缘部署

分页策略

基于游标（推荐）

优点： 可处理实时变化，不会跳过或重复记录，可扩展至数十亿条记录

FastAPI 示例：

@app.get("/items")
async def list_items(cursor: Optional[str] = None, limit: int = 20):
    query = db.query(Item).filter(Item.id > cursor) if cursor else db.query(Item)
    items = query.limit(limit).all()
    return {
        "items": items,
        "next_cursor": items[-1].id if items else None,
        "has_more": len(items) == limit
    }

基于偏移量（仅适用于简单场景）

仅用于静态数据集（<10k 条记录）且需要直接访问页面的场景。

完整模式和前端集成请参阅 references/pagination-patterns.md。

OpenAPI 文档

框架	OpenAPI 支持	文档 UI	配置
FastAPI	自动	Swagger UI + ReDoc	内置
Hono	中间件插件	Swagger UI	@hono/swagger-ui
Axum	utoipa crate	Swagger UI	手动注解
Gin	swaggo/swag	Swagger UI	注释注解

FastAPI 示例（零配置）：

app = FastAPI(title="My API", version="1.0.0")

@app.post("/items", tags=["items"])
async def create_item(item: Item) -> Item:
    """Create item with name and price"""
    return item
# Docs at /docs, /redoc, /openapi.json

有关各框架的配置，请参阅 references/openapi-documentation.md。 使用 scripts/generate_openapi.py 以编程方式提取规范。

前端集成模式

表单 → REST POST/PUT

后端：

class UserCreate(BaseModel):
    email: EmailStr; name: str; age: int

@app.post("/api/users", status_code=201)
async def create_user(user: UserCreate):
    return {"id": 1, **user.dict()}

前端：

const res = await fetch('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(data)
})
if (!res.ok) throw new Error((await res.json()).detail)

表格 → 带分页的 GET

请参阅上文的游标分页示例和 references/pagination-patterns.md。

AI 聊天 → SSE 流式传输

后端：

from sse_starlette.sse import EventSourceResponse

@app.post("/api/chat")
async def chat(message: str):
    async def gen():
        for chunk in llm_stream(message):
            yield {"event": "message", "data": chunk}
    return EventSourceResponse(gen())

前端：

const es = new EventSource('/api/chat')
es.addEventListener('message', (e) => appendToChat(e.data))

请参阅 examples/，查看与各前端技能对应的完整集成示例。

速率限制

FastAPI 示例（令牌桶）：

from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter

@app.get("/items")
@limiter.limit("100/minute")
async def list_items():
    return {"items": []}

请参阅 references/rate-limiting-strategies.md，了解滑动窗口、分布式模式和 Redis 实现。

GraphQL 库

适用于前端需要灵活获取数据，或移动应用受带宽限制的情况。

按语言划分：

• Python：Strawberry 0.287（基于类型提示，支持异步）
• Rust：async-graphql（高性能，基于 tokio）
• Go：gqlgen（根据 Schema 生成代码）
• TypeScript：Pothos（类型安全的构建器，无需代码生成）

请参阅 references/graphql-schema-design.md，了解 Schema 模式和 N+1 问题的预防方法。 请参阅 examples/graphql-strawberry/，查看完整的 Python 示例。

用于微服务的 gRPC

适用于服务间通信，具有强类型和高性能优势。

按语言划分：

• Rust：Tonic（异步、类型安全、代码生成）
• Go：Connect-Go（兼容 gRPC，且适用于浏览器）
• Python：grpcio（官方实现）
• TypeScript：@connectrpc/connect（适用于浏览器和 Node.js）

请参阅 references/grpc-protobuf-guide.md，了解 Protocol Buffers 指南。 请参阅 examples/grpc-tonic/，查看完整的 Rust 示例。

其他资源

参考资料

• references/rest-design-principles.md - REST 资源建模、HTTP 方法、状态码
• references/graphql-schema-design.md - Schema 模式、解析器优化、N+1 问题的预防方法
• references/grpc-protobuf-guide.md - Proto3 语法、服务定义、流式传输
• references/trpc-setup-guide.md - 路由器模式、中间件、Zod 验证
• references/pagination-patterns.md - 游标与偏移分页的对比及数学说明
• references/rate-limiting-strategies.md - 令牌桶、滑动窗口、Redis
• references/caching-patterns.md - HTTP 缓存、应用缓存策略
• references/versioning-strategies.md - URI、标头、媒体类型版本控制
• references/openapi-documentation.md - 各框架的 Swagger/OpenAPI 最佳实践

脚本（无令牌执行）

• scripts/generate_openapi.py - 根据代码生成 OpenAPI 规范
• scripts/validate_api_spec.py - 验证是否符合 OpenAPI 3.1
• scripts/benchmark_endpoints.py - 对 API 端点进行负载测试

示例

• examples/python-fastapi/ - 完整的 FastAPI REST API
• examples/typescript-hono/ - Hono 边缘优先 API
• examples/typescript-trpc/ - tRPC 端到端类型安全 API
• examples/rust-axum/ - Axum REST API
• examples/go-gin/ - Gin REST API
• examples/graphql-strawberry/ - Python GraphQL
• examples/grpc-tonic/ - Rust gRPC

快速参考

选择 REST 的情况： 公共 API、标准 CRUD、需要缓存、要求提供 OpenAPI 文档 选择 GraphQL 的情况： 前端需要灵活查询、移动端受带宽限制、数据嵌套复杂 选择 gRPC 的情况： 服务间通信、要求高性能、双向流式传输 选择 tRPC 的情况： TypeScript 全栈开发、前后端由同一团队负责、端到端类型安全

分页： 生产环境规模下始终使用基于游标的分页，仅在简单场景下使用基于偏移量的分页 文档： 优先选择可自动生成 OpenAPI 文档的框架（FastAPI、Hono） 性能： 追求最高吞吐量时选择 Rust（Axum），追求成熟度时选择 Go（Gin），注重开发体验时选择 Python（FastAPI）