SOAP API 并非难以应对：构建 SOAP 集成前需要了解的关键内容

使用基于 SOAP 的 API 构建第一个集成可能令人感到畏惧。

最近，帮助几家公司将其应用程序与使用基于 SOAP 的 API 的第三方应用程序和服务进行集成。对有 SOAP 经验的开发人员而言，这种集成较为简单。但对于初学者来说，SOAP 的学习曲线相当陡峭，并且会遇到许多新术语和缩写，如 XML、WSDL、envelope、procedure 等等。

接下来，将介绍一些 SOAP 的基本概念，并探讨一些工具和资源，这些工具和资源可以使 SOAP 集成的构建变得更为轻松（毕竟，SOAP 中的“S”代表“简单”）！

什么是 SOAP？

首先，介绍一下 SOAP 的基础知识。如果需要详细了解 SOAP 规范及其历史，可以访问 w3.org。这里简要概述一下。

SOAP 最初代表“简单对象访问协议”（Simple Object Access Protocol）。它主要用于处理 CRUD（创建、读取、更新、删除）操作，是一种以简单方式访问对象（如库存或客户数据）的协议。SOAP API 公开了外部服务可以访问和操作的对象类型，并明确了第三方如何发出 CRUD 请求。

后来，SOAP 不再使用这个首字母缩写，因为其功能超出了对象操作，但其核心理念保持不变：它是一种让两个系统以可预测方式进行通信的协议。

Web 服务和 WSDL

SOAP API 提供 Web 服务，这些服务由一个或多个过程（称为操作）组成。例如，可以创建一个“天气预报” Web 服务，包含“获取 10 天预报”操作或“提供最新温度数据”操作。

每个操作的请求都有特定的输入格式，响应则具有可预测的格式。例如，“获取 10 天预报”操作可能接受邮政编码作为输入，并返回该邮政编码未来 10 天的华氏温度数组。

发布基于 SOAP 的 Web 服务时，会生成一个 WSDL（Web 服务描述语言）文件。WSDL 采用 XML 格式，概述了服务提供的各种操作以及每个操作的预期输入和响应。

以下是一个基本“计算器服务”的简化 WSDL 示例。此 WSDL 定义了一些基本的计算器运算（如加法、减法、乘法和除法），并声明了一个“Add”操作：

<wsdl:operation name="Add">
 <wsdl:documentation xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
  Adds two integers. This is a test WebService. ©DNE Online
 </wsdl:documentation>
 <wsdl:input message="tns:AddSoapIn"/>
 <wsdl:output message="tns:AddSoapOut"/>
</wsdl:operation>

若查看该 XML 的详细内容，可以看到它引用了消息类型。以下部分定义了包含几个整数的复杂输入类型：

<wsdl:message name="AddSoapIn">
 <wsdl:part name="parameters" element="tns:Add"/>
</wsdl:message>

<s:element name="Add">
 <s:complexType>
  <s:sequence>
   <s:element minOccurs="1" maxOccurs="1" name="intA" type="s:int"/>
   <s:element minOccurs="1" maxOccurs="1" name="intB" type="s:int"/>
  </s:sequence>
 </s:complexType>
</s:element>

SOAP 经常被批评为冗长，WSDL 文件也不例外。但简单来说，上述 XML 实际上描述了“该服务有一个操作，它接受两个整数（intA 和 intB）作为输入”。

使用 SOAP API

想要调用一个加法操作，需要两个整数。这就需要从 WSDL 中创建一个 HTTP 请求，因为 SOAP API 基于 HTTP。

SOAP API 使用 XML 进行通信，因此首先需要设置正确的标头：Content-Type: text/xml; charset=utf-8。

发送的数据必须是 XML 格式，SOAP 将数据包装在 SOAP 信封中（信封定义了消息的结构）。从计算器 WSDL 中可以获取信封的结构。在 SOAP 信封的 “body” 中，声明要调用的操作，并包含操作期望的输入值。最终的 HTTP 请求如下所示：

curl http://www.dneonline.com/calculator.asmx \
  --request POST \
  --header "Content-Type: text/xml; charset=utf-8" \
  --data \
'<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
 <soap:Body>
    <Add xmlns="http://tempuri.org/">
     <intA>15</intA>
     <intB>27</intB>
    </Add>
 </soap:Body>
</soap:Envelope>'

发送请求后，得到的响应同样是 XML 格式，并且也被包装在信封中。响应的正文包含 WSDL 中定义的结果，即我们发送的两个数字之和：

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 <soap:Body>
  <AddResponse xmlns="http://tempuri.org/">
   <AddResult>42</AddResult>
  </AddResponse>
 </soap:Body>
</soap:Envelope>

虽然这种方式能返回结果，但手动编写 XML 请求容易出错，且复杂的 XML 解析可能显得繁琐。为了简化操作，可以使用一些工具来处理这些请求和响应。

SOAP 工具

手动解析 WSDL 和编写 HTTP 请求是非常繁琐的，因此应尽量避免。我推荐使用专门的 SOAP 工具，这些工具可以解析 WSDL 并提供操作列表及其输入。以下是一些优秀的工具：

SmartBear 的 SoapUI 是一个流行的工具，提供了优秀的图形用户界面，帮助在 WSDL 中进行导航。打开任何操作时，会显示示例请求，可以在应用程序中填写并执行这些请求。

最新版本的 HTTP 客户端 Postman 也支持导入 WSDL，并提供预填充的示例请求，允许从应用程序内部直接发送请求到 Web 服务。

这些图形化工具非常适合探索 SOAP API。建议在编写集成代码之前，先熟悉 Web 服务的操作。一旦对 SOAP API 的工作原理有了充分了解，就可以开始编写代码了。

编写代码以与 SOAP API 交互

手动解析 WSDL 和编写 HTTP 请求容易出错，并且体验通常很差。避免使用字符串文字模板化 XML 进行编码。为了简化与基于 SOAP 的 Web 服务交互，建议使用专门的 SOAP 库。

无论使用 Python、NodeJS、C# 还是其他现代编程语言，通常都有可用的 SOAP 库。例如，在 NodeJS 中，可以使用命名恰当的 soap 包。

这个库可以接受 WSDL 的 URL，并创建一个功能齐全的 HTTP 客户端对象，能够调用 Web 服务的操作。它可以处理操作调用、WSDL 解析、XML 请求的格式化以及 XML 响应的反序列化等工作。以下是一个使用 soap 库调用 “Add” 操作的示例：

var soap = require("soap");
const wsdlUrl = "http://www.dneonline.com/calculator.asmx?WSDL";
const args = { intA: 15, intB: 27 };
soap.createClient(wsdlUrl, function (err, client) {
  client.Add(args, (err, result) => {
    console.log(`The API returned a sum of ${result.AddResult}`);
  });
});

在这个例子中，请求的响应包含一个属性 AddResult，函数会打印出预期的结果：The API returned a sum of 42。

进一步抽象 SOAP

在构建将产品与客户使用的其他应用程序集成时，嵌入式集成平台即服务（iPaaS）可以简化与 SOAP API 的交互。嵌入式 iPaaS 提供低代码集成构建器，内置了适用于常见基于 SOAP 的应用程序（如 Salesforce）的预构建连接器，从而无需编写代码即可与多种 SOAP API 进行交互。

对于那些没有内置连接器的较为冷门的 SOAP API，它们通常提供一个 SOAP 组件，用于简化发出 SOAP 请求的复杂性。

通过嵌入式 iPaaS，可以几乎无需编写代码就与基于 SOAP 的 API 进行交互。