API设计规范与OpenAPI 3.1实践

概述良好的 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 驱动的文档/校验，可显著提升对接效率与稳定性，降低维护成本。