API 设计模式实战：分页、过滤、排序与批量操作的统一 JSON 规范

根据 Postman 2025 年 API 报告，全球开发者平均每周调用超过 50 次第三方 API，而超过 60% 的 API 集成问题源于响应格式不规范——分页字段名不统一、过滤语法混乱、批量操作缺少幂等保证。这些看似琐碎的设计细节，在微服务架构下会像滚雪球一样放大：10 个服务各自定义分页格式，前端就需要写 10 套解析逻辑。本文将从实际工程出发，给出一套经过生产验证的统一 JSON 规范，覆盖 API 设计中最常见的四大模式。

📌 **记住：**API 设计不是「能用就行」，而是团队协作的契约。一个好的 JSON 规范能让前端减少 40% 的胶水代码，让后端减少 60% 的接口返工。

📄 一、统一响应结构：所有 API 的基础骨架

1.1 标准响应信封（Envelope Pattern）

在设计任何 API 之前，先确定一个统一的响应信封。所有接口——无论是成功、失败、还是部分成功——都使用同一个顶层结构：

// ✅ 推荐：统一响应信封
{
  "code": 0,
  "message": "success",
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-06-01T10:30:00Z"
  }
}

// ❌ 避免：每个接口返回不同结构
// 接口 A 返回 { result: ... }
// 接口 B 返回 { data: ... }
// 接口 C 返回 { items: [...] }

统一信封的 TypeScript 类型定义：

// api-types.ts — 统一响应类型
interface ApiResponse<T> {
  code: number           // 0 = 成功，非 0 = 错误码
  message: string        // 人类可读的消息
  data: T                // 业务数据
  meta?: {
    requestId: string    // 请求追踪 ID
    timestamp: string    // ISO 8601 时间戳
  }
}

// 错误响应扩展
interface ApiError {
  code: number
  message: string
  errors?: {             // 字段级错误（表单验证）
    field: string
    message: string
    code: string
  }[]
}

⚠️ **警告：**不要用 HTTP 状态码承载业务错误码。HTTP 400 表示请求格式错误，而「用户名已存在」应该是 HTTP 200 + code: 1001。混用会导致前端无法区分网络错误和业务错误。

1.2 三种错误码体系对比

💡 **提示：**公开 API（如开放平台）推荐字符串错误码 + HTTP 状态码组合；内部微服务推荐数字错误码，配合错误码文档自动生成。

📑 二、分页设计：三种策略的性能实测

分页是 API 设计中最常见也最容易做错的模式。很多团队直接用 ?page=1&size=20，直到数据量达到百万级才发现性能崩塌。

2.1 三种分页策略对比

性能实测数据（PostgreSQL 16，100 万行数据）：

⚡ **关键结论：**Offset 分页在第 1000 页时已经比 Cursor/Keyset 慢 90 倍。如果你的列表允许用户无限滚动或数据量超过 10 万行，必须使用 Cursor 或 Keyset 分页。

2.2 Cursor 分页的 JSON 规范

// 请求：GET /api/users?cursor=eyJpZCI6MTAwfQ&limit=20
// 响应
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      { "id": 101, "name": "Alice", "createdAt": "2026-06-01T10:00:00Z" },
      { "id": 102, "name": "Bob", "createdAt": "2026-06-01T10:01:00Z" }
    ],
    "pagination": {
      "cursor": "eyJpZCI6MTIwfQ",     // 下一页游标（null 表示最后一页）
      "hasMore": true,                  // 是否有更多数据
      "total": 50000                    // 可选：总数（昂贵查询可省略）
    }
  }
}

Cursor 分页的后端实现：

// cursor-pagination.ts — Cursor 分页核心实现
import { db } from './database'

interface CursorPayload {
  id: number
  createdAt: string
}

function encodeCursor(data: CursorPayload): string {
  return Buffer.from(JSON.stringify(data)).toString('base64url')
}

function decodeCursor(cursor: string): CursorPayload {
  return JSON.parse(Buffer.from(cursor, 'base64url').toString())
}

async function getUsers(cursor?: string, limit = 20) {
  const query = db.select().from('users')

  if (cursor) {
    const { id, createdAt } = decodeCursor(cursor)
    // Keyset 条件：先按时间排序，再按 ID 排序（处理时间相同的情况）
    query.where(function () {
      this.where('createdAt', '<', createdAt)
        .orWhere(function () {
          this.where('createdAt', '=', createdAt)
            .andWhere('id', '>', id)
        })
    })
  }

  const items = await query.orderBy('createdAt', 'desc')
    .orderBy('id', 'asc')
    .limit(limit + 1) // 多查一条判断是否有下一页

  const hasMore = items.length > limit
  if (hasMore) items.pop()

  const lastItem = items[items.length - 1]
  return {
    items,
    pagination: {
      cursor: hasMore ? encodeCursor({
        id: lastItem.id,
        createdAt: lastItem.createdAt
      }) : null,
      hasMore
    }
  }
}

⚠️ **警告：**Cursor 不能是纯 ID，必须包含排序字段。如果按 createdAt DESC 排序，Cursor 必须同时包含 createdAt 和 id，否则在时间相同的数据上会丢失记录。

2.3 Offset 分页的 JSON 规范（后台管理场景）

对于后台管理系统，用户需要跳到指定页码，Offset 分页仍然适用：

// 请求：GET /api/admin/orders?page=50&pageSize=20&status=paid
// 响应
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [ ... ],
    "pagination": {
      "page": 50,
      "pageSize": 20,
      "total": 15000,
      "totalPages": 750,
      "hasNext": true,
      "hasPrev": true
    }
  }
}

💡 提示：total 查询（SELECT COUNT(*)）在大表上可能需要数秒。如果用户不需要精确总数，可以用估算值（PostgreSQL 的 pg_class.reltuples）或直接省略 total 字段。

🔍 三、过滤与排序：声明式查询语法设计

3.1 过滤参数的三种方案

推荐：扁平参数 + 运算符后缀，兼顾可读性和灵活性：

// filter-parser.ts — 统一过滤参数解析器
interface FilterCondition {
  field: string
  operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'like' | 'between'
  value: string | string[]
}

function parseFilters(query: Record<string, string>): FilterCondition[] {
  const filters: FilterCondition[] = []
  const OPERATORS = ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'like', 'between']

  for (const [key, value] of Object.entries(query)) {
    // 跳过分页和排序参数
    if (['page', 'pageSize', 'cursor', 'limit', 'sort', 'fields'].includes(key)) continue

    // 解析 field_operator 格式，如 age_gte → { field: 'age', operator: 'gte' }
    const parts = key.split('_')
    const lastPart = parts[parts.length - 1]

    if (OPERATORS.includes(lastPart)) {
      const field = parts.slice(0, -1).join('_')
      const operator = lastPart as FilterCondition['operator']

      filters.push({
        field,
        operator,
        value: operator === 'in' ? value.split(',') :
               operator === 'between' ? value.split(',') : value
      })
    } else {
      // 没有运算符后缀，默认 eq
      filters.push({ field: key, operator: 'eq', value })
    }
  }

  return filters
}

// 使用示例
// GET /api/products?category=electronics&price_gte=100&price_lte=500&status_in=active,soldout
const filters = parseFilters(req.query)
// 结果: [
//   { field: 'category', operator: 'eq', value: 'electronics' },
//   { field: 'price', operator: 'gte', value: '100' },
//   { field: 'price', operator: 'lte', value: '500' },
//   { field: 'status', operator: 'in', value: ['active', 'soldout'] }
// ]

3.2 排序参数规范

// 单字段排序：GET /api/users?sort=-createdAt
// 多字段排序：GET /api/users?sort=-createdAt,+name
// 解释：- 表示降序，+ 表示升序（默认）

// sort-parser.ts — 排序参数解析
interface SortOption {
  field: string
  direction: 'asc' | 'desc'
}

function parseSort(sortParam?: string): SortOption[] {
  if (!sortParam) return [{ field: 'id', direction: 'desc' }] // 默认排序

  return sortParam.split(',').map(item => {
    const trimmed = item.trim()
    return {
      field: trimmed.startsWith('-') ? trimmed.slice(1) : trimmed.replace(/^\+/, ''),
      direction: trimmed.startsWith('-') ? 'desc' : 'asc'
    }
  })
}

3.3 字段选择（Sparse Fieldsets）

允许客户端指定只需要的字段，减少响应体积：

GET /api/users?fields=id,name,email

// 响应（只返回请求的字段）
{
  "code": 0,
  "data": {
    "items": [
      { "id": 1, "name": "Alice", "email": "alice@example.com" }
    ]
  }
}

📌 **记住：**字段选择在移动端尤其重要——一个返回 50 个字段的列表接口，如果移动端只需要 5 个字段，传输体积可以减少 90%。但要注意，字段选择不应影响服务端的查询逻辑——始终查询完整行，只在序列化时过滤字段。

📦 四、批量操作：幂等性与事务保证

4.1 批量创建

// POST /api/users/batch
// 请求
{
  "items": [
    { "name": "Alice", "email": "alice@example.com" },
    { "name": "Bob", "email": "bob@example.com" }
  ],
  "options": {
    "onError": "continue",          // continue | abort
    "idempotencyKey": "batch_abc123" // 防重复提交
  }
}

// 响应（部分成功）
{
  "code": 0,
  "message": "2 succeeded, 1 failed",
  "data": {
    "succeeded": [
      { "index": 0, "id": 101, "name": "Alice" },
      { "index": 2, "id": 103, "name": "Charlie" }
    ],
    "failed": [
      {
        "index": 1,
        "error": { "code": 1002, "message": "Email already exists" }
      }
    ],
    "summary": { "total": 3, "succeeded": 2, "failed": 1 }
  }
}

4.2 批量更新（PATCH）

// PATCH /api/users/batch
// 请求
{
  "items": [
    { "id": 101, "updates": { "status": "active" } },
    { "id": 102, "updates": { "status": "suspended", "reason": "spam" } }
  ]
}

4.3 批量删除

// DELETE /api/users/batch
// 请求
{
  "ids": [101, 102, 103],
  "softDelete": true  // 软删除（推荐）
}

// 响应
{
  "code": 0,
  "data": {
    "deleted": 3,
    "failedIds": []   // 删除失败的 ID 列表
  }
}

⚠️ **警告：**批量操作必须限制单次处理数量。建议设置上限为 100-500 条，超过限制返回 413 Payload Too Large 或提示分批处理。无限制的批量操作是 DDoS 攻击的温床。

🔧 五、完整实战：前后端联调代码

5.1 前端统一请求封装

// api-client.ts — 前端统一 API 客户端
interface ListParams {
  page?: number
  pageSize?: number
  cursor?: string
  sort?: string
  fields?: string
  [key: string]: any // 过滤参数
}

class ApiClient {
  constructor(private baseUrl: string) {}

  async list<T>(endpoint: string, params: ListParams): Promise<{
    items: T[]
    pagination: any
  }> {
    const query = new URLSearchParams()

    for (const [key, value] of Object.entries(params)) {
      if (value !== undefined && value !== null) {
        query.set(key, String(value))
      }
    }

    const response = await fetch(`${this.baseUrl}${endpoint}?${query}`)
    const json = await response.json()

    if (json.code !== 0) {
      throw new ApiError(json.code, json.message, json.errors)
    }

    return json.data
  }

  async batchCreate<T>(endpoint: string, items: Partial<T>[]) {
    const response = await fetch(`${this.baseUrl}${endpoint}/batch`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        items,
        options: {
          onError: 'continue',
          idempotencyKey: `batch_${Date.now()}`
        }
      })
    })
    return response.json()
  }
}

// 使用示例
const api = new ApiClient('https://api.example.com')

// 分页查询
const { items, pagination } = await api.list('/users', {
  cursor: 'eyJpZCI6MTAwfQ',
  limit: 20,
  sort: '-createdAt',
  status: 'active',
  fields: 'id,name,email'
})

// 批量创建
const result = await api.batchCreate('/users', [
  { name: 'Alice', email: 'alice@example.com' },
  { name: 'Bob', email: 'bob@example.com' }
])

5.2 后端统一响应中间件

// response-middleware.ts — Express 统一响应中间件
import { Request, Response, NextFunction } from 'express'

// 成功响应
function success(res: Response, data: any, meta?: object) {
  res.json({
    code: 0,
    message: 'success',
    data,
    meta: {
      requestId: res.getHeader('X-Request-Id'),
      timestamp: new Date().toISOString(),
      ...meta
    }
  })
}

// 错误响应
function error(res: Response, code: number, message: string, errors?: any[]) {
  res.status(200).json({  // 注意：HTTP 状态码始终 200
    code,
    message,
    errors: errors || [],
    meta: {
      requestId: res.getHeader('X-Request-Id'),
      timestamp: new Date().toISOString()
    }
  })
}

// Express 中间件：挂载到 res 对象
function responseMiddleware(req: Request, res: Response, next: NextFunction) {
  res.success = (data: any, meta?: object) => success(res, data, meta)
  res.error = (code: number, message: string, errors?: any[]) => error(res, code, message, errors)
  next()
}

✅ 最佳实践总结

⚡ 关键结论：API 设计的核心原则是一致性。与其在每个接口上追求「最优」设计，不如在所有接口上保持「统一」规范。前端开发者最大的痛苦不是某个接口设计得不好，而是 10 个接口有 10 种格式。用一套规范覆盖 80% 的场景，剩下的 20% 再特殊处理。

🔧 相关工具推荐

• 🔧 jsjson.com JSON 格式化工具 — 在线格式化和验证 API 响应 JSON
• 🔧 jsjson.com JSON 压缩工具 — 测量 API 响应的压缩效果
• 🔧 OpenAPI 3.1 — API 契约规范标准
• 🔧 Zod — TypeScript Schema 验证库，前后端共享类型
• 🔧 TypeBox — JSON Schema 类型安全生成