---

title: API设计规范与OpenAPI 3.1实践

keywords:

• REST
• OpenAPI 3.1
• JSON Schema
• Idempotency-Key
• 版本管理
• 分页
• 错误码
• 幂等
• 安全
• 速率限制

description: 基于 OpenAPI 3.1 规范化 API 设计，涵盖资源建模、分页与错误码、幂等与安全实践，并给出可验证的示例。

date: 2025-11-25

categories:

• 文章资讯
• 技术教程

---

概述

良好的 API 具备一致的资源建模、可预期的错误表达与稳定的版本策略。本文结合 OpenAPI 3.1 与 JSON Schema，提供规范清单与示例，便于生成文档与校验接口。

设计要点（已验证）

• 资源建模：使用名词复数，如 /users、/orders/{id}。
• 版本策略：路径或头信息（如 Accept: application/vnd.api+json;version=1）。
• 分页：采用 page/page_size 或基于游标的 cursor，返回 total/next。
• 错误码：统一结构 { code, message, traceId }，HTTP 状态与业务码映射清晰。
• 幂等：对写操作使用 Idempotency-Key 防重复；重试仅限幂等接口。
• 安全：使用 OAuth2/JWT，避免敏感信息泄漏于错误与日志。

OpenAPI 3.1 示例（片段）

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 列出用户
      parameters:
        - in: query
          name: page
          schema: { type: integer, minimum: 1, default: 1 }
        - in: query
          name: page_size
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  total: { type: integer }
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      required: [ id, name ]
      properties:
        id: { type: string }
        name: { type: string }

错误与幂等示例

HTTP/1.1 409 Conflict
Content-Type: application/json
{
  "code": "ORDER_ALREADY_EXISTS",
  "message": "订单已存在",
  "traceId": "abc123"
}

POST /orders
Idempotency-Key: 2025-11-25-7f3e

验证与生成

• 使用 openapi-cli/swagger-cli 校验规范；CI 中强制校验。
• 结合代码生成（如客户端/服务端骨架），确保接口与文档一致。
• 合规检查：敏感字段脱敏与错误信息不含内部细节。

常见误区

• 返回的状态码与业务结果不匹配（如出错仍返回 200）。
• 不同接口的错误结构不一致，难以监控与排障。
• 无幂等支持导致重试造成重复下单或扣费。

结语

规范的 API 设计与 OpenAPI 驱动的文档/校验，可显著提升对接效率与稳定性，降低维护成本。