17370845950

REST API 默认返回 JSON，因其轻量、易读、解析快，且被浏览器、移动端及主流框架原生支持；XML 仅适用于对接遗留系统等特定场景，应通过 Accept 头协商格式，保持响应结构一致。

REST API 默认返回 JSON，这是当前最主流、最推荐的做法。

为什么 JSON 是首选

JSON 格式轻量、易读、解析快，几乎所有编程语言都有成熟且安全的原生支持。浏览器端 JavaScript 直接内置解析能力，移动端和现代服务端框架（如 Spring Boot、Express、Django REST）也默认优先处理 JSON。相比之下，XML 更冗长、解析开销大、容易引入命名空间或 DTD 安全问题（如 XXE 攻击）。

• 客户端兼容性更广：前端 fetch/Axios、curl、Postman 默认发 JSON 请求、期望 JSON 响应
• 序列化/反序列化性能更好，尤其在高并发或资源受限环境（如 IoT、Serverless）
• 工具链更完善：OpenAPI（Swagger）规范以 JSON Schema 为核心，文档、Mock、SDK 生成更自然

什么时候可以考虑 XML

仅在明确对接遗留系统、政府或金融行业特定规范（如某些 SOAP 过渡系统、ISO 20022 报文）、或客户合同强制要求时才提供 XML 支持。不建议为新项目主动设计 XML 接口。

• 通过 Content-Type 和 Accept 头协商：客户端发 Accept: application/xml 才返回 XML
• 避免同时暴露 JSON/XML 路由（如 /api/users.json 和 /api/users.xml），违背 REST 的资源导向原则
• 若必须支持，确保 XML 输出严格验证、禁用外部实体、不依赖复杂命名空间

如何正确支持多格式（可选但推荐）

用 HTTP 内容协商（Content Negotiation）实现灵活响应，而非硬编码格式。服务器根据 Accept 请求头决定返回格式，同时保证同一资源 URL 行为一致。

• 默认 fallback 为 application/json（当 Accept 不匹配或未提供时）
• 显式支持常见类型：Accept: application/json, text/xml;q=0.9 → 返回 JSON；Accept: application/xml → 返回 XML
• 响应头中必须设置 Content-Type（如 application/json; charset=utf-8），不可省略

其他实用建议

保持响应结构一致性比格式选择更重要。无论 JSON 还是 XML，都应统一错误格式、分页字段、时间格式（ISO 8601）、空值处理方式。

• 错误响应示例（JSON）：{"error": "not_found", "message": "User not found", "status": 404}
• 时间字段统一用字符串（如 "created_at": "2025-05-20T08:30:00Z"），避免 XML 中的 xs:dateTime 或 JSON 中的时间戳数字引发歧义
• 不因格式切换而改变字段名或嵌套逻辑（例如不要 JSON 用 user_name，XML 用 userName）

基本上就这些。新项目直接上 JSON，留好协商扩展性，别为了“兼容”提前加 XML，除非真有甲方签字画押的要求。