API 设计：公开 XML 或对象答案

【问题标题】：API Design: Expose XML or ObjectsAPI 设计：公开 XML 或对象
【发布时间】：2008-12-15 14:25:13
【问题描述】：

我们正在着手开发一项新的中间层服务，该服务将允许内部客户端系统在某些底层数据存储中创建、更新和查询记录。该服务将聚合多达 3 个独立的底层数据存储。就本问题而言，假设：

数据存储 #1：专有 XML 数据库。
数据存储#2：现成的关系数据库。
数据存储#3：平面文件存储（以二进制形式存储的文件）。

客户端将不知道（也不关心）他们正在查询/更新哪个数据存储。新服务将做出该决定。我的问题是：我的 API 应该公开 XML 还是对象？例如。新的 API 将有一个 add 方法。假设我们的系统是一个车载存储系统，那么API的add方法可能是这样的：

AddNewCar( CarObject car )

或者，它可能看起来像这样：

AddNewCar( string carXml )

现在，即使第 2 种方法在入口处被弱类型化，XML 也将立即根据模式进行验证，至少。

新服务将用 C# 编写（尚未确定哪个版本，但可能是 WCF 的 3/3.5）。 API 的客户端可以是 C#/VBA/VB.Net/C++/Java)。

更多细节请告诉我。谢谢

更新：请注意，API 还将通过消息总线发布 XML。例如。添加新车时，将发布汽车 XML，以便任何对新车感兴趣的人都会收到通知。

【问题讨论】：

【解决方案1】：

您不应该公开 XML，因为这会修复您的格式以及您未来可能面临的有关基础架构的任何决定。我总是会走强类型路线，以确保您正确地将您的实现从使用中抽象出来。

如果您采用 XML 路线并在开发过程中发现 XML 必须因某种原因而更改，那么更改 API 的所有用途以纠正该问题将比强类型化困难得多API 并将 XML 细节隐藏在对象后面。

【讨论】：

抱歉，不确定您所说的“远离使用的抽象实现”是什么意思。由于不同的底层数据源，我不会在内部使用 XML（写入 XML DB 时除外）。 XML 是我对实现的抽象（即 3 个数据存储）。
通过使用 XML 作为抽象，你失去了强类型的优点，如果这些对象不符合客户端的使用，编译器会告诉你的客户端对这些对象的更改。使用 XML 接口，直到运行时才发现错误，这肯定更令人沮丧。

【解决方案2】：

我会说公开一个对象 API。虽然不是因为上面另一篇文章中提到的原因 - 公开 XML 会导致更难更改的固定格式。

可以说，强类型业务对象的 API 与 XML 一样难以更改 - 两者都需要重新编译和重新构建。所以这不是你应该丢弃 XML 的原因。

原因 - IMNSHO - 是抽象级别的原因。在 API 级别，您谈论的是哪些业务对象或服务可以对哪些其他业务对象执行哪些操作。因此，API 必须根据业务对象进行对话。

正如在另一篇文章中已经提到的，您始终可以使用 XML 表示来支持业务对象。将业务对象和服务的 XML 表示保持在较低的抽象级别，您的 API 将为您提供 XML 的所有灵活性，同时允许您构建具有良好语义的更高级别的 API。

【讨论】：

【解决方案3】：

您应该使用对象创建 API，并在需要时利用 WCF 提供 XML API。

【讨论】：

【解决方案4】：

您应该使用对象创建一个 API，然后围绕该 API 创建一个 Web 服务接口（例如，对于 Java，您将在您的接口上使用 java2wsdl，然后使用 wsdl2java 创建一个框架服务器端实现或客户端实现，我确信 WCF 中存在等效的方法），所有其他系统都可以查询。

由于您拥有多语言客户端，我认为 Web 服务是您的最佳选择，并且（忽略业务逻辑实现）只需几分钟即可在您的 API 之上工作。您可以将 wsdl 或 xsd 文件分发给所有客户端软件的开发人员，然后他们可以使用这些文件简单快速地与您的系统交互。

【讨论】：

【解决方案5】：

当然，从最终用户开发人员的角度来看，强类型方法是最简单的，这是我更喜欢的。但是，如果最终所有内容都在幕后转换为 Xml，或者您不确定您的客户会采用哪种方法，我绝对建议您同时支持这两种方法。

【讨论】：

如果你想要对象，只有最好的。例如。如果您想创建报告，那么 XML 可能是最好的，因为您可以在其上运行 XSLT 来生成报告。我不知道，也不能在这个阶段假设我的客户实际上会如何处理这些数据。