合理结构应统一返回含code、message、data三层的JSON，code为数字型HTTP语义码（如200），data内嵌业务字段与错误详情，错误响应保持同构以避免前端多套解析逻辑。
XML上传接口返回 JSON 响应的合理结构设计
XML上传接口本身不规定返回格式，但服务端应统一返回结构化的 JSON，避免前端反复适配不同字段或错误形态。核心原则是：成功必含 code、message、data 三层，且 code 为数字型 HTTP 语义码（如 200 表示业务成功），不混用字符串如 "SUCCESS"。
为什么不能直接返回原始 XML 解析结果
前端消费的是结构化数据，不是 XML 字符串。若返回 {"xml": "<root><id>123</id></root>"}，等于把解析责任推给调用方，违背 API 职责分离。常见问题包括：
- 前端重复写 XML 解析逻辑，各端不一致
- 无法统一做字段校验、空值处理、类型转换（如
<amount>100.5</amount>应转为 number） - 服务端无法在返回前注入元信息（如耗时、版本、签名）
标准成功响应的 JSON 字段定义
一个可落地的最小可行结构如下，兼顾兼容性与扩展性：
{
"code": 200,
"message": "OK",
"data": {
"upload_id": "upl_abc123",
"parsed_at": "2024-06-15T10:22:33Z",
"valid_records": 42,
"invalid_records": 3,
"summary": {
"total": 45,
"errors": [
{"line": 7, "reason": "missing required field 'email'"},
{"line": 12, "reason": "invalid phone format"}
]
}
},
"timestamp": 1718446953
}
关键点说明：
-
code必须与 HTTP 状态码语义对齐，200表示上传+解析+校验全部成功；207（Multi-Status）可用于部分成功场景，但需在文档中明确定义 -
data内部结构按业务域组织，避免平铺所有字段（如不建议把upload_id和errors并列在顶层） -
timestamp是服务端生成时间戳（秒级或毫秒级），用于排查时序问题，非必需但强烈建议
错误响应必须保持同构结构
哪怕上传失败，也要返回和成功一致的三字段外壳，否则前端需写两套解析逻辑。典型错误响应示例：
{
"code": 400,
"message": "Invalid XML syntax at line 3, column 12",
"data": {
"raw_error": "XMLParseError: Unexpected token '<'",
"suggestion": "Check for unclosed tags or invalid entities"
}
}
容易被忽略的细节：
- HTTP 状态码（如
400）和 JSON 中的code必须一致，不能出现 HTTP 200 + JSON code=400 的矛盾组合 -
message面向开发者，要具体（如指出哪行哪列），不能只写“请求失败” -
data在错误时可为空对象{}，但不能省略，否则破坏结构契约
{"error": "xxx"}，而成功时用标准结构。这种割裂会让前端增加大量条件判断，后期维护成本陡增。 
