WSDL 教程

WSDL 教程

WSDL 教程

WSDL(Web Services Description Language,Web 服务描述语言)是一种基于 XML 的语言,用于描述 Web 服务"能做什么、怎么调用"。它是 SOAP 服务生态的核心组成部分,类似"服务的使用说明书"。

WSDL 解决什么问题

• 用机器可读的方式描述服务的接口
• 客户端可自动解析并生成调用代码
• 与 SOAP 配合,实现跨语言、跨平台的服务调用

核心结构

definitions (根)
├── types         数据类型(XSD)
├── message       消息定义
├── portType      操作(方法)集合
├── binding       绑定协议(SOAP/HTTP)
└── service       服务端口地址

最小示例片段

<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
  <wsdl:message name="HelloRequest">
    <wsdl:part name="name" type="xsd:string"/>
  </wsdl:message>
  <wsdl:portType name="Greeter">
    <wsdl:operation name="sayHello">
      <wsdl:input message="tns:HelloRequest"/>
    </wsdl:operation>
  </wsdl:portType>
</wsdl:definitions>

本教程将带你理解 WSDL 文档的各个组成部分。

WSDL 简介

WSDL 简介

WSDL 1.1 由 W3C 于 2001 年发布,描述网络服务的接口;WSDL 2.0(2007)重命名为"Web Services Description Language"并简化了模型。REST 流行后,WSDL 主要用于传统 SOAP 服务场景(企业集成、金融、电信)。

WSDL 与 SOAP、UDDI 的关系

• WSDL:描述服务接口(做什么、怎么调)
• SOAP:传输消息的 XML 协议(怎么传)
• UDDI:服务注册与发现(去哪找)

核心概念

调用流程

客户端获取 WSDL
 → 生成存根(stub)代码
 → 按 binding 封装 SOAP 请求
 → 发送到 service 地址
 → 解析响应

获取 WSDL 的方式

许多 SOAP 服务在 URL 后加 ?wsdl 即可获取,如 https://example.com/api?wsdl。

WSDL 文档

WSDL 文档

理解 WSDL 文档的完整结构,是编写与阅读 WSDL 的基础。

完整结构示例

<?xml version="1.0"?>
<wsdl:definitions
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:tns="http://example.com/greet"
    targetNamespace="http://example.com/greet">

  <!-- 1. 类型:定义数据结构 -->
  <wsdl:types>
    <xsd:schema targetNamespace="http://example.com/greet">
      <xsd:element name="HelloRequest">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="name" type="xsd:string"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </wsdl:types>

  <!-- 2. 消息:请求/响应 -->
  <wsdl:message name="HelloRequestMsg">
    <wsdl:part element="tns:HelloRequest" name="parameters"/>
  </wsdl:message>

  <!-- 3. 端口类型:操作 -->
  <wsdl:portType name="GreeterPortType">
    <wsdl:operation name="sayHello">
      <wsdl:input message="tns:HelloRequestMsg"/>
      <wsdl:output message="tns:HelloResponseMsg"/>
    </wsdl:operation>
  </wsdl:portType>

  <!-- 4. 绑定:协议 -->
  <wsdl:binding name="GreeterBinding" type="tns:GreeterPortType">
    <soap:binding style="document"
        transport="http://schemas.xmlsoap.org/soap/http"/>
  </wsdl:binding>

  <!-- 5. 服务:地址 -->
  <wsdl:service name="GreeterService">
    <wsdl:port name="GreeterPort" binding="tns:GreeterBinding">
      <soap:address location="http://example.com/greet"/>
    </wsdl:port>
  </wsdl:service>

</wsdl:definitions>

阅读顺序建议

从下往上读更容易理解:service(在哪) → binding(怎么传) → portType(有什么方法) → message/types(数据长什么样)。

WSDL 端口

WSDL 端口

portType 与 port 是 WSDL 中定义"接口"与"端点"的核心概念,容易混淆,这里单独讲解。

portType(接口)

portType 是操作的集合,类似编程语言的"接口(interface)"。每个 operation 定义一次调用的输入输出:

<wsdl:portType name="CalculatorPortType">
  <wsdl:operation name="Add">
    <wsdl:input message="tns:AddRequest"/>
    <wsdl:output message="tns:AddResponse"/>
    <wsdl:fault message="tns:CalcError"/>   <!-- 可选的错误 -->
  </wsdl:operation>

  <wsdl:operation name="Subtract">
    <wsdl:input message="tns:SubRequest"/>
    <wsdl:output message="tns:SubResponse"/>
  </wsdl:operation>
</wsdl:portType>

消息交换模式

• 请求-响应:最常用,一个输入一个输出
• 单向:只有输入(通知类)
• 通知:只有输出(服务端推送)

port(端点)

port 把 portType + binding 绑定到一个具体网络地址:

<wsdl:port name="CalcPort" binding="tns:CalcBinding">
  <soap:address location="https://calc.example.com/soap"/>
</wsdl:port>

类比

portType ≈ 接口定义;port ≈ 接口的一个部署地址;一个 portType 可以有多个 port(不同地址/协议)。

WSDL 绑定

WSDL 绑定

binding 元素把 portType 的操作绑定到具体的传输协议与消息格式,常见为 SOAP over HTTP。

SOAP 绑定示例

<wsdl:binding name="GreeterBinding" type="tns:GreeterPortType">
  <soap:binding style="document"
      transport="http://schemas.xmlsoap.org/soap/http"/>
  <wsdl:operation name="sayHello">
    <soap:operation soapAction="http://example.com/greet/sayHello"/>
    <wsdl:input>
      <soap:body use="literal"/>
    </wsdl:input>
    <wsdl:output>
      <soap:body use="literal"/>
    </wsdl:output>
  </wsdl:operation>
</wsdl:binding>

关键属性

• style:document(文档风格)或 rpc(过程调用风格)
• transport:传输协议(SOAP/HTTP、SOAP/SMTP 等)
• soapAction:HTTP 头中的 SOAPAction 值
• use:encoding(编码)或 literal(字面量)

其他绑定

• HTTP GET/POST 绑定:WSDL 也支持直接 HTTP 调用(非 SOAP)
• MIME 绑定:带附件的消息

绑定与实现

同一 portType 可定义多个 binding(如 SOAP 版与 HTTP 版),客户端按需选择。实际开发中通常由框架(如 Java JAX-WS、.NET WCF)自动生成 WSDL 的 binding 部分。

WSDL UDDI

WSDL UDDI

UDDI(Universal Description, Discovery and Integration,统一描述、发现和集成)是 Web 服务的注册与发现标准,与 WSDL、SOAP 并称 Web 服务三要素。

UDDI 的作用

• 注册:服务提供商把服务(WSDL)发布到注册中心
• 发现:服务消费者按分类/关键词查找服务
• 集成:获取 WSDL 后自动生成客户端调用

UDDI 数据结构

businessEntity   企业信息
├── businessService  服务信息
│   └── bindingTemplate  绑定信息(指向 WSDL)
│       └── tModel        技术模型(接口规范)

现实状况

• 公有 UDDI 注册中心已基本退出历史舞台
• 企业内部服务网关(如 API 管理平台)承担了类似职能
• WSDL 依然是 SOAP 服务的接口契约,配合工具链使用

从 UDDI 到现代服务发现

微服务时代,服务发现由注册中心(Consul、Nacos、Eureka)与 API 网关完成;接口描述则演进为 OpenAPI(Swagger)用于 REST 服务。理解 UDDI 有助于理解服务治理的演变脉络。

WSDL 总结

WSDL 总结

回顾 WSDL 的核心知识与它在 Web 服务生态中的位置。

要点回顾

• WSDL 用 XML 描述 Web 服务接口:类型、消息、操作、绑定、地址
• 五大元素:types / message / portType / binding / service
• portType 定义操作,port 定义端点地址,binding 定义协议
• 配合 SOAP 实现跨平台调用,配合 UDDI 实现服务发现

使用场景

• 传统企业系统集成(ERP/CRM 对接)
• 金融、电信等行业的 SOAP 服务
• 代码生成:wsdl2java、svcutil、wsdl2py 自动生成客户端

与 REST 对比

学习建议

理解 WSDL 的结构与设计思想,即使今天以 REST 为主,面对遗留 SOAP 系统的维护与对接时仍能从容应对。

WSDL 语法

WSDL 语法

WSDL 语法速查:根元素、命名空间与关键属性,方便编写和阅读时查阅。

根元素与命名空间

<wsdl:definitions
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:tns="目标命名空间"
    targetNamespace="http://example.com/">

元素层级

definitions
├── types            (可选)
│   └── schema       (XSD)
├── message          (0..n)
│   └── part
├── portType         (0..n)
│   └── operation
│       ├── input
│       ├── output
│       └── fault
├── binding          (0..n)
│   ├── soap:binding
│   └── operation → soap:operation / soap:body
└── service          (0..n)
    └── port → soap:address

常用属性

校验工具

# Python 校验 XML 格式
python3 -c "import xml.dom.minidom; xml.dom.minidom.parse('service.wsdl'); print('OK')"

# 在线校验/解析工具: SOAPUI、WSDL 查看器