JSON API 最佳实践

一致的 JSON 设计让 API 更易消费和维护。遵循以下规范可提升前后端协作效率。

命名与结构

统一使用 camelCase 或 snake_case，不要混用。嵌套层级建议不超过 2–3 层。列表用数组，实体用对象，避免难以查询和文档化的深层嵌套。

null 与错误处理

明确区分 null 与字段缺失。错误响应应结构化：{"error": {"code": "INVALID_INPUT", "message": "..."}}，便于程序化处理。

校验

部署前校验 JSON 格式。在 CI 中使用 JSON Schema 验证。开发阶段可用 WaiHub JSON 格式化工具快速发现语法错误。