SAP Fiori开发：OData服务Atom XML与JSON格式选型实战解析

近几年做 SAP Fiori 相关的项目，几乎每次遇到“前端明明请求成功了，UI 却死活不显示数据”这种问题，最后追下去都会撞到同一个概念：数据到底是用 Atom XML 返回的，还是用 JSON 返回的。在 SAP Fiori 开发里，OData 服务常常同时支持两种数据表达方式，后端基础数据一样，HTTP 响应却可能长成完全不同的两副面孔。如果不把 Atom 与 JSON 背后的取舍逻辑理清楚，光靠“换成 JSON 试试”这种经验主义，排错效率会很差。

这篇文章不是 OData 规范的复制粘贴，而是从实战视角出发，把 Atom XML、JSON、OData v2/v4 的差异、Gateway 格式协商、UI5 模型偏好以及调试排错链路串起来讲。适合刚接触 Fiori/UI5 的前端开发者，也适合在 SAP Gateway 或 SEGW 上维护 OData 服务、需要对外接口标准化交付的顾问和架构师。读完你应该能回答一个高频问题：同一个 OData 服务，为什么一会儿给我 XML，一会儿给我 JSON，到底谁说了算。

1. 从一次“接口返回 403 CSRF”说起：格式问题如何影响 Fiori 排查链路

1.1 真实现场：保存失败，错误详情却没有被前端解析出来

有一次我在排一个 Fiori 审批应用的保存报错。用户点“提交”后，界面弹出一个非常笼统的“请求失败”，没有明细，后台看起来也没有进 ABAP 断点。Fiori 界面列表里看不到异常详情，打开浏览器开发者工具，发现保存接口返回的是 HTTP 403，原因跟 CSRF token 有关。这个本身是常见的 Gateway 防护机制问题，但有意思的是响应体不是普通的可读 JSON，而是一段 Atom XML 格式的 <m:error> 结构。

前端代码里通常这么写错误处理：

javascript复制error: function (oError) {
    var statusCode = oError.statusCode;
    var errorBody = oError.response ? oError.response.body : null;
    // 如果后端返回的是 XML，这里直接用 JSON.parse 会失败
}

很多 UI5 开发者习惯性认为“接口返回的数据就是 JSON”，拿到错误后第一反应是取 oError.responseJSON，或者用 JSON.parse(oError.response.body)。可当后端响应类型是 application/atom+xml 的时候，responseJSON 可能是空的，真正的错误码和错误消息全在那个 XML 文档里。也就是说，一个原本很简单的 CSRF token 缺失问题，会被人为包装成“页面没有正确显示后端消息”的第二个问题。

从这个场景能看到一个关键点：Fiori 开发里数据表达方式不是一个后端自嗨的细节，它直接决定了前端怎么解析、怎么提示、怎么继续调试。

1.2 同一个服务，为什么有时返回 Atom，有时返回 JSON

后端 OData 服务在收到请求时，并不天然知道调用方想接 XML 还是 JSON。正常情况下它通过两个入口来判断：

• HTTP 请求头里的 Accept 字段
• URL 上的 $format=json 或 $format=atom 参数

当浏览器地址栏直接访问 OData 实体集 URL 时，浏览器发出的 Accept 是 text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 这一串，并没有明确说要 JSON。SAP Gateway 在这种情况下往往按历史默认逻辑返回 Atom XML。而 Fiori 应用里的 SAPUI5 ODataModel 发请求时会带上自己的 Accept: application/json，网关就按 JSON 返回。

问题恰恰出现在两边不一致的时候。比如团队里有人在后端网关做了自定义逻辑，或者在反向代理层改了请求头，甚至某些 Fiori 模型实例配置里没有显式打开 JSON 选项，都可能导致前端拿到 Atom XML。从现象看，接口 URL 完全没变，返回的数据却“换了语言”。

1.3 一个容易被混淆的边界：数据格式不等于传输协议

这里需要稍微把概念收拢一下。OData 本身是一个基于 HTTP 的数据访问协议，数据格式是它承载业务内容的外壳。HTTP 是传输通道，OData 是查询语义，Atom XML 和 JSON 都是把这套语义“写”出来的表达方式。可以类比成：寄快递时地址信息是核心，手写在面单上还是打印出来，并不影响快递员理解，但会影响后续系统录入的难易程度。理解这一点之后，再回头看 XML 与 JSON 的“取舍”，焦点就不会只停留在“哪个快哪个慢”，而会上升到“服务端和消费端谁更容易解析、谁更符合生态习惯”这个层面。

2. OData 为什么有两副面孔：Atom 基因、JSON 生态、v4 重新洗牌

2.1 AtomPub 是 OData 的“出厂设置”

要理解为什么 SAP Gateway 的 OData 服务会跟 Atom XML 扯上关系，得从 OData 协议的老家说起。OData 早期由微软推动，设计上直接借用了 Atom Publishing Protocol（AtomPub）这套基于 XML 的内容发布标准。AtomPub 原本是用来发布、编辑博客文章和时间序列内容的，它定义了 feed、entry、link、category 等一套词汇表。OData 把 AtomPub 的“文章订阅”语义改造成“数据集合访问”语义：一组业务数据就是一个 feed，一条业务数据就是一个 entry，字段类型则放在扩展的 m:properties 和 d: 命名空间里。

SAP NetWeaver Gateway 和后来的 SEGW 事务码，基本上是在 OData v2 时代被引入 ABAP 世界的。这个时代的服务天然默认支持 Atom XML，因为协议规范自己就从那里长出来。所以你在很多旧文档、旧项目里看到的 OData 示例，响应体都是 <feed>、<entry> 包裹的 XML，这是历史原因，不是 SAP 没事找事。

2.2 浏览器生态把 JSON 推上前台

到了 2010 年前后，前端开发已经全面转向 JavaScript 与 Ajax。浏览器里解析 XML 需要 XML DOM，代码写起来啰嗦，跨浏览器行为还不一致；而 JSON 跟 JavaScript 对象字面量几乎是同构的，一个 JSON.parse() 就能变成可以直接访问的对象。于是 OData 社区开始把 JSON 作为一种补充格式纳入实现。OData v2 的 JSON 表示法也顺势出现，SAP Gateway 在支持 Atom XML 的同时，逐步实现了对 application/json 的响应。

SAPUI5 作为 Fiori 前端的核心框架，背后的数据绑定机制天然更适合 JSON。UI5 的 ODataModel 拿到 JSON 响应后，可以很快把数据转换成模型上下文里的值；如果服务端返回 Atom XML，框架内部仍然能解析，但路径处理和性能都会更重。UI5 最终选择默认或者说主动请求 JSON，本质上是被 JavaScript 生态推动的。

2.3 OData v4 重新洗牌

OData 发展到 v4，正式以 JSON 作为基准格式，不再默认依赖 AtomPub。OData v4 的响应用 @odata.context、@odata.id、value 这些带 @ 前缀的控制字段来描述元数据，结构比 v2 的 verbose JSON 更干净。很多外部系统看到 v4 的 JSON 响应，会以为它跟普通 REST API 很像，但 Fiori 项目里大量存量服务其实是 OData v2。SAP 的 On-Premise 环境里，Gateway 服务往往还是走 v2 路线，响应里会出现 "d" 和 "results" 这类 v2 时代的包装层。理解 v4 和 v2 的差异，才不会拿外部 REST 的经验硬套 Fiori 服务。

下面这张对照表可以把三种常见表达形式快速放在一起看：

对于一个 OData v2 服务，如果调用方没有明确表达偏好，服务端返回 Atom XML 很常见；如果调用方带上 Accept: application/json，则会进入 verbose JSON。不要把 OData v4 的 JSON 格式与 OData v2 的 JSON 格式完全等同，这是 Fiori 实际项目里很多人容易踩的第二层坑。

3. Atom XML 到底是不是“重”在无意义标签：打开一个 Gateway 响应逐层看

3.1 一个典型的 Gateway Atom feed 长什么样

为了让概念落地，我用常见的 OData v2 实体集响应举个例子。这里简化了字段，但保留了 Atom 结构的关键元素：

xml复制<?xml version="1.0" encoding="utf-8"?>
<feed xml:base="https://esd.example.com/sap/opu/odata/sap/ZDEMO_SRV/"
      xmlns="http://www.w3.org/2005/Atom"
      xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
      xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
  <id>https://esd.example.com/sap/opu/odata/sap/ZDEMO_SRV/ProductSet</id>
  <title type="text">ProductSet</title>
  <updated>2025-06-01T08:30:00Z</updated>
  <link rel="self" title="ProductSet" href="ProductSet"/>
  <entry>
    <id>https://esd.example.com/sap/opu/odata/sap/ZDEMO_SRV/ProductSet('100')</id>
    <title type="text">ProductSet</title>
    <updated>2025-06-01T08:30:00Z</updated>
    <category term="ZDEMO_SRV.Product"
              scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
    <link href="ProductSet('100')" rel="edit" title="Product"/>
    <content type="application/xml">
      <m:properties>
        <d:ProductID>100</d:ProductID>
        <d:Name>工业控制器</d:Name>
        <d:Price>1999.90</d:Price>
        <d:Stock>50</d:Stock>
        <d:UpdatedAt m:type="Edm.DateTimeOffset">2025-06-01T08:30:00Z</d:UpdatedAt>
      </m:properties>
    </content>
  </entry>
</feed>

这段 XML 看着确实比 JSON 啰嗦，但每一层都承担了职责。<feed> 与 <entry> 表达的是“集合”与“单条数据”的语义；<link rel="edit"> 告诉客户端当前数据可以通过哪个相对路径做更新；<category term> 标明这条数据的实体类型；<content> 里面才是真正的业务字段。

3.2 Atom 的结构不是纯冗余：self、edit、关联和类型

有人会觉得 Atom XML 的 namespace 前缀和 link 标签很多余，实际上在复杂业务模型里它们作用不小。当后端服务启用了 $expand，会把主子表数据一次性嵌套返回，Atom 响应里会用 <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/OrderItems"> 这种形式表达“这条 Product 主数据关联哪些 OrderItem”。如果不用 Atom 而用普通 XML，字段和关联关系的语义就没有标准化的标签体系来承载。

另外，SAP Gateway 的 $metadata 文档永远以 XML 的 CSDL 格式输出。这是一个经常让人意外的地方：即便你的 Fiori 前端一贯用 JSON 读业务数据，它底层仍然要先去读 XML 元数据，才能知道每个实体有哪些属性、主键是什么、哪些属性允许过滤排序。Atom XML 在运行时是被业务接口调用，元数据 XML 则是给框架做“地图”用的，两者不是一回事。

3.3 用 XML DOM 消费 Atom 时的注意点

如果你在自定义 Node.js 或者 Python 脚本里拉取 OData Atom 数据，应该使用标准的 XML 解析器，不要用正则表达式去抠 <d:Name> 标签之间的内容。命名空间会让标签在不同的服务里出现不同前缀，正则很容易写死。比如有的服务把 d: 前缀改成 sap: 或 default:，你的匹配就废了。正确的做法是解析成 DOM 或对象树，再按 localName 而非完整前缀取值。

还有个实际体验上的点：浏览器开发者工具直接查看 XML 响应时，默认不会像 JSON 那样套一层可折叠的树形美化视图，你需要展开原始标签看。这个视觉差异会进一步让人产生“Atom 不好读”的感觉。与其说是 Atom XML 本身不适合表达 OData，不如说现代前端工具链已经被 JSON 宠坏了。

4. UI5 为什么更偏爱 JSON：verbose JSON 的结构、优势与隐藏成本

4.1 OData v2 的 JSON 响应外有一层“壳”

先看 OData v2 verbose JSON 的经典结构。请求同一个 ProductSet，如果网关返回 JSON，得到的往往是这种形式：

json复制{
  "d": {
    "results": [
      {
        "__metadata": {
          "id": "https://esd.example.com/sap/opu/odata/sap/ZDEMO_SRV/ProductSet('100')",
          "uri": "https://esd.example.com/sap/opu/odata/sap/ZDEMO_SRV/ProductSet('100')",
          "type": "ZDEMO_SRV.Product"
        },
        "ProductID": "100",
        "Name": "工业控制器",
        "Price": "1999.90",
        "Stock": 50,
        "UpdatedAt": "/Date(1717237800000+0000)/"
      }
    ],
    "__next": "https://esd.example.com/sap/opu/odata/sap/ZDEMO_SRV/ProductSet?$skiptoken=100_"
  }
}

这里外面套了一个 "d" 对象，集合数据放在 "results" 数组里，分页游标放在 "__next" 里。字段 "__metadata" 保存了资源唯一标识、实体类型等元信息。UI5 解析这种结构时，会自动把 results 部分当作表格或列表控件的行数据。

4.2 JSON 在 UI5 数据绑定里的同构优势

SAPUI5 的控件数据绑定基于 JavaScript 对象属性访问。例如一个 sap.m.Table 的 items 绑定到一个 path "/ProductSet"，框架拿到 JSON 后会先剥掉 d/ 这层包装，把后面的数据映射到模型上下文。如果同样是列表数据，用 XML 也可以实现，但框架内部需要做 XML DOM 遍历，路径解析和类型转换的成本明显更高。

写前端代码时更明显。有人喜欢直接调用 ODataModel 的 read 方法：

javascript复制var oModel = new sap.ui.model.odata.v2.ODataModel({
    serviceUrl: "/sap/opu/odata/sap/ZDEMO_SRV/",
    json: true
});

oModel.read("/ProductSet", {
    success: function (oData, oResponse) {
        // oData.results 就是业务数据数组
        var aProducts = oData.results;
    },
    error: function (oError) {
        // 如果后端返回 XML，oError 里的结构会让你多花很多时间
    }
});

这里的 oData.results 直接可读，几乎和本地 Ajax 请求一致。在 UI5 的视图里，JSON 响应也能顺利被 Model 框架转化为绑定上下文。UI5 从框架设计层面就把 JSON 视为更“顺手”的数据形态，这并不奇怪。

4.3 JSON 也有隐藏成本

JSON 不是没有代价。OData v2 verbose JSON 会对每条记录附带一份 __metadata，当一次加载几百条数据时，重复的 URI 和 type 字段会占用不少体积。实际项目里有人为了追求“返回变小”，把 __metadata 去掉，但去掉后 UI5 模型可能无法正确处理导航、编辑路径和 type 判断，得不偿失。

JSON 对日期时间的表达也不标准。SAP Gateway 返回的 Edm.DateTime / Edm.DateTimeOffset，在 JSON 里常常是 /Date(1717237800000+0000)/ 这种特殊字符串，不是 ISO 8601。前端如果直接展示，会出现一串数字加时区的诡异内容，必须做格式化解析。XML 响应里日期反而是标准的 ISO 文字，只是解析成本在别处。这就很典型：一种数据表达方式在结构上让你舒服，就必定会在另一个维度上还回来一些额外处理。

5. 网关侧的格式协商：Accept 头、$format 与 Atom/JSON 的实际切换

5.1 一次 OData 请求的协商链路

HTTP 内容协商是决定 Atom 还是 JSON 的“裁判”。正常情况下，客户端发起请求时带一个 Accept 头，服务端会按自己支持的格式和优先级选择一个最匹配的媒体类型返回。比如 Postman 或 Node 脚本里显式加：

http复制GET /sap/opu/odata/sap/ZDEMO_SRV/ProductSet HTTP/1.1
Host: esd.example.com
Accept: application/json

Gateway 看到 application/json 可协商，就会返回 JSON。假如请求里什么都没加，或者加的是 application/xml，Gateway 就会按老路返回 Atom XML。

所以当你发现前后端格式对不上，第一步不是改后端代码，而是抓包看请求头里的 Accept 是什么，响应头里的 Content-Type 是什么。若请求头明明要 JSON，响应却是 application/atom+xml，那就要看网关的配置、URL 改写、代理层是否把 Accept 吞掉了。

5.2 用 $format 强制切换

想在测试工具里快速验证某种格式，最直接的方式是用系统查询选项 $format。例如：

• /ProductSet?$format=json 强制返回 JSON
• /ProductSet?$format=atom 强制返回 Atom XML

这个参数适合调试阶段使用，但我建议不要在生产 API 调用里长期依赖它。一来 $format 的优先级高于 Accept，如果前端代码没有正确处理格式，会造成明明改了请求头却不生效的错觉；二来有些 SAP Gateway 版本对 $format 的处理细节存在差异，同样的 URL 在升级后行为可能变化。生产环境应优先靠 Accept 和模型配置，让代码在 HTTP 语义层面保持一致。

5.3 UI5 模型配置与 Accpet 的关系

在 Fiori 应用里，最稳妥的做法是让 UI5 ODataModel 明确感知你要哪种格式。不同版本默认值不完全一致，不依赖默认值才是稳妥策略。显式设置 JSON 的做法类似这样：

javascript复制var oModel = new sap.ui.model.odata.v2.ODataModel({
    serviceUrl: "/sap/opu/odata/sap/ZDEMO_SRV/",
    json: true,
    tokenHandling: true
});

这段配置的意义在于：前端请求发出时，框架会给自己的 HTTP 客户端设置合适的 Accept 头。项目里有不少人把 json: true 漏掉，然后去后端调来调去，实际只是前端没有表明态度。设置完成后可以在网络面板里核对请求头，如果看到 Accept: application/json，说明前端姿态已经摆正。

5.4 元数据请求为什么大多还是 XML

即便 UI5 模型业务数据使用 JSON，底层仍需要通过 $metadata 获取服务元数据。CSDL 元数据文档在 OData v2 时代基本是 XML。UI5 框架拿到 XML 元数据后，会解析实体的属性名、类型、导航关联，再根据这些信息生成查询请求与绑定路径。很多人以为“Fiori 应用全链路 JSON”，其实框架自己内心同时维护着两套解析器：一套用来读 XML 元数据，一套用来消费 JSON 业务数据。不要在排查问题时只盯着业务数据接口，如果 $metadata 在 Fiori 应用沙盒启动阶段没有正确加载，后面的列表照样白屏。

6. 真实项目里的取舍：不要只拿响应体积当唯一标准

6.1 一份数据，两种格式的体积差异

经常有人说“JSON 比 XML 小”，这是有前提的。精简的无 __metadata JSON 确实比完整 Atom XML 小不少，因为 XML 有大量重复的标签、命名空间和开放关闭结构。但是 OData v2 verbose JSON 里每条数据带完整 __metadata 时，压缩优势并没有想象中那么大。下面是一个简单对比参考，基于我测试过的 SAP Gateway 中等复杂实体：

所以“换 JSON 就能大幅瘦身”过于理想化。真正的差距主要来自 XML 标签重复，而不是数据内容。更关键的优化方向是只请求需要的字段、合理分页、启用压缩，以及避免在列表接口里 expand 多余导航。

6.2 不同的消费端应该有不同的默认姿势

OData 服务往往不止给 Fiori 前端用。同一套服务，SAPUI5 前端可能喜欢 JSON，下游传统 EAI 中间件或 C#/.NET 客户端可能更愿意用 Atom XML，因为后者对 XML Schema 和 DataContractSerializer 更熟悉。这恰恰说明服务端不应该把格式“焊死”成一种，而是保留基于 Accept 的协商能力。

我曾经遇到一个集成项目，对方 Java 系统每次拉数据都在 URL 后面硬拼 $format=json，后来网关结构升级，把查询参数过滤掉了，对方接口直接报错。最后改成在 HTTP 客户端统一设置 Accept: application/json，问题才彻底消失。这说明消费端的代码应该优先遵循 HTTP 语义，把格式偏好写进标准请求头，而不是依赖业务 URL 的查询串。

6.3 真实问题的优先级排序

我自己的取舍标准排序是：正确定义 > 可调试性 > 性能 > 历史习惯。

正确定义排第一，指的是前后端要有清晰的 media type 契约，不要靠“默认 JSON”这种模糊认知。可调试性排第二，因为 Fiori 项目里大部分时间花在排错，JSON 在 DevTools 里肉眼可读，Atom XML 也不是灾难，只是不够直观。性能排第三，不是在超大数据量下完全忽略，但不要为了 5% 的体积优势让前后端解析逻辑充满边界条件。历史习惯放最后，比如某些 ABAP 团队一直习惯看 XML，这可以让步，但不应阻挡团队整体切换到更省心的 JSON。

6.4 什么时候坚持 Atom XML 反而是对的选择

有一个场景我坚持用 Atom XML：做 Gateway 服务原始语义排查，尤其是定位 $expand、$select、$link 关联关系是否生效时。Atom XML 的 <link rel>、<category term>、<m:properties> 层次清晰，能直观看出导航关系有没有正确拼接。相反，OData v2 verbose JSON 的 __deferred 结构容易让人忽略关联其实没有被展开。换句话说，Atom XML 更像一份“带注释的原始数据”，JSON 更像“渲染后的页面数据”。这两种表达方式没有绝对优劣，只有适不适合当前排查目标。

7. 格式问题排查清单：把经验固化成自己的操作流程

7.1 遇到空白列表先看四件事

如果你在 Fiori 应用沙盒启动阶段或本地调试时就发现列表空白、保存失败、错误信息看不懂，我建议按这个顺序排查：

1. 打开浏览器开发者工具 Network 面板，找到对应 OData 业务请求。
2. 查看 Request Headers 里的 Accept 是什么。如果没看到 application/json，前端模型配置还没有把 JSON 偏好表达出来。
3. 查看 Response Headers 里的 Content-Type。如果是 application/atom+xml，但前端代码按 JSON 解析，便会出错。
4. 看响应体的最外层。如果是 <feed> 或 <entry>，那就是 Atom；如果是 {"d":...} 或 {"value":...}，才是 JSON。

这套流程五分钟内能定位绝大多数“格式串台”问题。不要反问“后端为什么给 XML”，先确认前端有没有在 HTTP 层告诉后端自己期待什么。

7.2 写操作返回 403 时的额外检查项

Fiori 里写操作通常比读操作多一步 CSRF token 流程。UI5 模型的 tokenHandling 默认会尝试获取 token，但如果你的服务部署在代理之后、跨域环境或 Mock Server 下，token 获取可能失败，从而在 POST/PUT 时返回 403。检查项要同时覆盖 token 和格式：

• 请求流程中是否先请求过服务根路径或 $metadata 来换取 token。
• 写请求头里是否带上了 X-CSRF-Token。
• 403 响应体是 {"error":...} 还是 <m:error>。如果是后者，别急着用 JSON 解析。
• 代理层是否过滤了自定义请求头。

如果 403 响应是 Atom XML，页面错误处理没有做 XML 兜底，用户看到的可能只是“请求失败”，真正的错误原因需要你从原始网络报文里复制出来。这时我会用一个临时脚本或者 Postman 手动触发同样的写请求，把响应体完整保存下来再判断，别在 UI5 error handler 里反复 console.log undefined。

7.3 把格式选择固化到代码与文档里

项目早期就应该把“OData 响应格式策略”写成开发约定，避免每个开发者自行决定。前端代码统一显式