接口规范需兼顾机器可解析性与人类可读性，统一JSON结构、RESTful URI命名、字段类型约束、业务错误码体系、Swagger自动文档及路径版本控制。

接口定义既要让机器能正确解析，也要让人一眼看懂意图。规范性解决协作和稳定性问题，可读性降低理解成本、减少误用。两者不是取舍关系，而是同一目标的两面：写得清楚，才容易对得准。

统一结构与语义化命名

所有接口返回统一 JSON 格式，包含 code（业务状态码）、message（简明提示）、data（实际载荷），避免前端反复适配不同结构。URI 严格使用名词复数、小写、连字符，如 /api/v2/user-orders，不出现 /getUserById 或 /Api/UserInfo 这类动词或大小混用形式。

• 资源集合用复数：/products、/notifications
• 单个资源加 ID：/products/123、/notifications/456
• 从属关系用层级：/users/789/orders 表示用户 789 的订单列表

字段约束与类型明确

参数不是“能传就行”，而是“该传什么、怎么传”必须清晰。用 OpenAPI 规范描述每个字段：是否必填（required: true）、类型（string / integer / boolean）、格式（如 email、date-time）、长度或取值范围。避免用 Object 或泛型 Map 接收多字段，优先封装为 DTO。

• ID 类字段统一用 integer 或 string（如 UUID），不混用
• 开关类字段用 boolean，不传 "0" / "1" 字符串
• 时间字段统一用 ISO 8601 格式（"2026-06-17T11:24:00+08:00"）

错误体系与文档同步

错误不能只靠 HTTP 状态码，需配套业务错误码 + 可读消息。比如 40001 表示“参数缺失”，40002 表示“参数格式错误”，前端可据此做差异化提示。文档必须与代码实时一致——通过 Swagger 自动生成，每次接口变更自动更新 UI 页面，拒绝手写文档滞后。

• 错误码全局唯一，按模块分段（如 400xx 用户模块，500xx 订单模块）
• 错误响应结构与正常响应一致：{"code":40001,"message":"缺少 user_id","data":{}}
• Swagger 注解嵌入代码，而非单独维护 YAML 文件

版本控制与演进友好

不加版本的接口等于没有契约。版本号放在路径中（/api/v1/），不放在 Header 或参数里。v1 上线后，新增需求优先在 v1 内兼容扩展（如加可选字段），重大变更再发布 v2，并行维护至少一个大版本周期。

• v2 不删除 v1 接口，仅标记 deprecated 并设下线时间
• 新字段默认提供合理默认值，避免调用方因未传而失败
• 废弃字段保留在响应中一段时期，逐步引导迁移