Apache CXF：从WSDL到Java代码的快速生成指南-CSDN博客

本文链接：https://blog.csdn.net/weixin_35752122/article/details/148884953

简介：Apache CXF是一个用于构建和开发Web服务的开源Java框架，支持WS-*协议、RESTful服务和SOAP。本教程将指导读者如何使用CXF从WSDL文件生成Java代码，涵盖安装、准备WSDL文件、使用 wsdl2java 工具、理解生成的代码、实现服务、部署和测试的完整流程。同时，文中介绍了Apache CXF的其他功能，如动态客户端、JAXB数据绑定、Spring集成等，帮助开发者更方便地开发和调试Web服务。
apache-cxf生成wsdl

1. Apache CXF简介和安装

1.1 Apache CXF简介

Apache CXF是一个开源的服务框架，用于提供Web服务的快速开发。它提供了完整的数据绑定，允许开发者将数据绑定到Java对象，以便于Java开发者更方便地使用Web服务。CXF支持JAX-WS，也支持基于原始XML消息的SOAP服务。它是一个高效、灵活、强大的服务框架，非常适合用于构建和开发服务导向架构（SOA）。

1.2 安装Apache CXF

安装Apache CXF是一个简单的过程。首先，需要下载最新版本的Apache CXF，并解压到你选择的目录。然后，将CXF的bin目录添加到你的系统环境变量中，以便于可以全局访问到CXF的命令行工具。最后，可以通过执行 cxfversion 命令来验证安装是否成功。如果安装成功，将会显示CXF的版本号。

$ cxfversion

安装成功后，就可以开始使用Apache CXF进行Web服务的开发了。接下来的章节将会介绍如何准备和解析WSDL文件，以及如何使用wsdl2java工具将WSDL文件转换为Java代码。

2. WSDL文件准备与解析

2.1 WSDL文件的重要性与结构

2.1.1 WSDL的基本概念和作用

WSDL（Web Services Description Language）是一种基于XML的接口描述语言，用于描述网络服务的性质。它使服务提供者可以明确地定义和公布服务的接口，而服务消费者则可以准确地了解如何与服务进行交互。WSDL文档包括了服务可用的操作和绑定这些操作的消息格式。这些信息对于开发人员和自动化工具来说至关重要，因为在没有WSDL的情况下，他们将需要手动分析和解析服务接口。

2.1.2 WSDL文件的主要元素解析

一个典型的WSDL文档包含以下几个核心元素：

types：使用XML Schema定义所有的数据类型。
message：定义了在通信过程中交换的消息数据结构。
portType：定义了一组操作，每个操作可以看作是一个方法。
binding：规定了特定协议（如SOAP）和消息格式的绑定方式。
service：定义了一个或多个端点（port），每个端点将portType中的操作映射到一个具体的网络地址。

WSDL文件是机器可读的，因此能够被各种工具解析，生成代码或配置文件，从而加速开发进程。

2.2 WSDL文件的编写和验证

2.2.1 手动编写WSDL文件

手动编写WSDL文件通常需要对WSDL的结构有深入的理解。通常情况下，开发人员会根据已有的服务接口需求来手动编写。以下是编写WSDL文件的简化步骤：

定义数据类型（types）。
创建消息定义（message）。
设定端口类型（portType）和操作（operation）。
定义绑定（binding）到具体的协议上。
创建服务（service）和端点（port）。

示例代码块展示了如何定义一个简单的WSDL文件结构：

<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
             xmlns:tns="http://example.com/MyService"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             targetNamespace="http://example.com/MyService">
    <types>
        <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
            <xs:element name="addNumbers">
                <xs:complexType>
                    <xs:sequence>
                        <xs:element name="a" type="xs:int"/>
                        <xs:element name="b" type="xs:int"/>
                    </xs:sequence>
                </xs:complexType>
            </xs:element>
            <xs:element name="addNumbersResponse">
                <xs:complexType>
                    <xs:sequence>
                        <xs:element name="result" type="xs:int"/>
                    </xs:sequence>
                </xs:complexType>
            </xs:element>
        </xs:schema>
    </types>
    <message name="addNumbers">
        <part name="parameters" element="tns:addNumbers"/>
    </message>
    <message name="addNumbersResponse">
        <part name="parameters" element="tns:addNumbersResponse"/>
    </message>
    <portType name="计算器">
        <operation name="addNumbers">
            <input message="tns:addNumbers"/>
            <output message="tns:addNumbersResponse"/>
        </operation>
    </portType>
    <binding name="计算器SOAP" type="tns:计算器">
        <soap:binding style="document"
                      transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="addNumbers">
            <soap:operation soapAction="urn/AddNumbers"/>
            <input>
                <soap:body use="literal"/>
            </input>
            <output>
                <soap:body use="literal"/>
            </output>
        </operation>
    </binding>
    <service name="加法计算器">
        <port name="加法计算器SOAP" binding="tns:计算器SOAP">
            <soap:address location="http://example.com/MyService"/>
        </port>
    </service>
</definitions>

2.2.2 使用工具验证WSDL文件的有效性

手动编写WSDL文件容易出错，幸运的是有许多工具可以帮助我们验证WSDL的有效性。例如，使用Apache CXF自带的工具或在线WSDL验证服务。这些工具可以检查WSDL是否符合XML和WSDL规范，以及所有必要的元素是否都已正确定义。

使用命令行验证WSDL文件的一个示例：

java -jar cxf-tools-x.x.x.jar wsdl2java -validate WSDL_URL

在这里， cxf-tools-x.x.x.jar 是Apache CXF提供的工具jar包， WSDL_URL 是你的WSDL文件所在的位置。执行这个命令将会对WSDL文件进行验证，并打印出结果。如果存在错误或警告，工具将指出具体问题所在，使得开发人员可以据此修正WSDL文档。

WSDL文件的有效性是后续使用 wsdl2java 工具进行代码生成的前提条件，因此确保WSDL文件的正确性和完整性是整个开发流程中的一个关键步骤。

3. 使用wsdl2java工具转换WSDL到Java代码

3.1 wsdl2java工具的使用方法

3.1.1 安装和配置wsdl2java工具

wsdl2java是Apache CXF框架中用来将WSDL文件转换为Java代码的一个命令行工具。转换过程中，它会生成一系列Java源代码，包括服务端接口、客户端代理以及它们的相关实现，从而简化Web服务的调用流程。安装wsdl2java之前，确保已经正确安装了Apache CXF及其依赖的环境。

首先，下载并解压Apache CXF的发行包。解压后，在 bin 目录下可以找到 wsdl2java 的脚本（在Windows下是 .bat 文件，在Unix/Linux/Mac下是 .sh 文件）。接下来需要将该目录添加到系统的PATH环境变量中，或者直接使用相对路径调用该脚本。

在命令行中执行以下命令可以配置环境：

export PATH=/path/to/cxf/bin:$PATH    # Unix/Linux/Mac
set PATH=/path/to/cxf/bin;%PATH%      # Windows

3.1.2 通过命令行使用wsdl2java

使用 wsdl2java 可以通过命令行来执行，其基本用法如下：

wsdl2java [options] <WSDL-file-url>

这里， [options] 允许你添加参数来定制生成的Java代码，例如指定包名( -p )，生成JAX-WS注解( -frontend jaxws21 )，或者排除某些文件( -exsh 等)。 <WSDL-file-url> 是一个指向WSDL文件的URL，可以是本地文件路径或网络地址。

例如，若要生成一个包含注解的Java代码，可以使用以下命令：

wsdl2java -p com.example.service -frontend jaxws21 http://localhost/service?wsdl

这会创建一个名为 com.example.service 的包，并在其中生成带有JAX-WS注解的Java类，这些类基于 http://localhost/service?wsdl 指定的WSDL文件。

3.2 从WSDL到Java代码的转换过程详解

3.2.1 WSDL到Java代码转换原理

WSDL到Java代码的转换过程基于一系列的代码生成模板，这些模板定义了如何将WSDL中的抽象定义映射到Java语言结构上。具体来说，转换过程大致分为以下几个步骤：

解析WSDL文件 ： wsdl2java 首先会解析WSDL文件，识别出其中定义的类型、消息、端口类型、绑定和端点等信息。
应用代码模板 ：使用Apache CXF提供的代码模板将解析出的信息转化为Java代码。模板中定义了Java类和方法的结构，以及WSDL中服务和操作的具体Java表示。
生成源代码文件 ：依据模板处理的结果，生成Java源代码文件，包括服务接口定义和客户端代理类。
编译和组织代码 ：最终生成的Java源代码文件通常需要被编译和打包，以便在项目中使用。

3.2.2 转换过程中的常见问题及解决方案

在使用 wsdl2java 进行代码转换时，可能会遇到一些问题，如生成的代码不符合预期、转换失败等。常见的问题包括WSDL文件不完整或结构错误、代码生成选项使用不当等。

解决方案通常涉及以下几个方面：

验证WSDL文件 ：确保WSDL文件遵循标准规范并且结构正确无误。
选择合适的代码生成选项 ：根据项目需求选择合适的 -frontend 选项，以及是否有JAX-WS注解的支持等。
自定义代码模板 ：在必要时，修改或创建自定义的代码模板来满足特定的代码风格或设计模式。
查阅文档和社区 ：当遇到难题时，可以通过查阅Apache CXF的官方文档或在社区中寻求帮助。

下面表格展示了 wsdl2java 命令行选项的一些示例以及它们的用途：

选项	用途
`-d <dir>`	指定生成代码的目标目录。
`-p <package>`	指定生成代码的Java包名。
`-impl`	生成服务接口的实现类。
`-client`	生成客户端代理类。
`-server`	生成服务端的部署类。
`-wsdlLocation`	指定WSDL文件的位置，这在WSDL文件中没有指定位置时使用。
`-help`	显示命令行帮助信息。

接下来，是一个简单的示例代码块，展示了如何执行 wsdl2java 命令：

wsdl2java -d /path/to/output/dir -p com.example.service \
    -impl -client \
    -frontend jaxws21 \
    http://localhost/MyService?wsdl

在上述命令中，我们指定了输出目录、包名、要求生成实现类和客户端代理，并指定了使用JAX-WS 2.1前端。

通过这样的命令， wsdl2java 将按照指定参数和WSDL文件，生成相应的Java源代码，使得Web服务的调用和实现变得更加简单高效。

4. Apache CXF生成的Java代码结构与应用实现

4.1 Java代码结构的详细解读

4.1.1 生成代码的目录结构

当使用 wsdl2java 工具成功将WSDL文件转换为Java代码后，会得到一个包含多个文件和目录的项目结构。这个结构是根据WSDL文件中定义的服务、端点以及数据类型来设计的。例如，假设你的WSDL文件定义了一个名为 HelloService 的服务，那么生成的代码结构大致如下：

HelloService/
|-- src/
|   `-- org/
|       `-- example/
|           `-- hello/
|               |-- HelloPortType.java
|               |-- HelloService.java
|               |-- ObjectFactory.java
|               `-- types/
|                   |-- HelloFault.java
|                   `-- SayHello.java
`-- pom.xml

src/ 目录包含了所有的源代码。
org/example/hello/ 包含了生成的类文件。
- HelloPortType.java - 服务端点的接口。
- HelloService.java - 服务类，提供了服务接口的实现。
- ObjectFactory.java - 包含了用于创建复杂类型实例的工厂类。
- types/ - 包含了WSDL中定义的复杂类型定义。
- HelloFault.java - 自定义的服务异常类型。
- SayHello.java - 客户端和服务端交互的消息类型。
pom.xml - Maven项目对象模型文件，用于管理项目构建和依赖。

4.1.2 代码文件功能和作用域

每个生成的Java代码文件在服务的实现中扮演了特定的角色：

HelloPortType.java - 定义了服务的接口，客户端可以使用这个接口调用远程方法。
HelloService.java - 实现了 HelloPortType 接口，并封装了底层网络通信的细节。
ObjectFactory.java - 提供了创建复杂类型对象的静态方法，确保了对象创建的一致性和便捷性。
HelloFault.java - 标识了可能从服务端抛出的异常信息。
SayHello.java - 定义了服务请求和响应的消息类型。

理解这些文件和它们的作用对于进一步开发和维护是十分关键的。通过这种方式，Apache CXF提供了一种简单而有效的方式来处理SOAP服务的客户端和服务端代码生成。

4.2 服务端和客户端代码的实现步骤

4.2.1 服务端代码的编写和配置

服务端的实现涉及到几个步骤：编写实现接口的类、配置服务并启动服务器。

编写服务端实现

首先，你需要提供服务接口的具体实现。根据上面的例子，我们创建一个简单的 HelloServiceImpl 类：

package org.example.hello;

import javax.jws.WebService;
import org.example.hello.SayHello;

@WebService(endpointInterface = "org.example.hello.HelloPortType")
public class HelloServiceImpl implements HelloPortType {
    public SayHello sayHello(String name) {
        return new SayHello("Hello, " + name + "!");
    }
}

在这个类中， @WebService 注解表明这个类提供了一个Web服务。 endpointInterface 属性指定了服务接口。

配置服务并启动服务器

接下来，我们需要配置服务，并将其发布到一个Web服务器上。通常这通过一个配置文件来完成，这里我们用代码来演示：

import org.apache.cxf.jaxws.EndpointImpl;
import javax.xml.ws.Endpoint;

public class Server {
    public static void main(String[] args) {
        Endpoint endpoint = Endpoint.publish("http://localhost:8080/hello", new HelloServiceImpl());
        System.out.println("Service is published...");
    }
}

这段代码创建了一个端点（ Endpoint ），并将其绑定到 HelloServiceImpl 类的实例上。我们通过指定一个URL地址来发布服务，客户端可以通过这个地址访问我们的服务。

4.2.2 客户端代码的编写和调用

客户端代码的编写主要是创建一个代理类来与服务端通信。

创建服务代理

通过CXF的 JAXWsDynamicClientFactory 类，可以轻松创建一个服务代理：

import org.apache.cxf.jaxws.endpoint.client.JAXWsDynamicClientFactory;
import javax.xml.namespace.QName;

public class Client {
    public static void main(String[] args) {
        JAXWsDynamicClientFactory dcf = JAXWsDynamicClientFactory.newInstance();
        QName serviceName = new QName("http://example.org/hello/", "HelloService");
        Object serviceProxy = dcf.createClient(serviceName);

        // 客户端调用
        Object[] response = (Object[]) serviceProxy.invoke("sayHello", "World");
        System.out.println(response[0]);
    }
}

在上面的代码中，我们首先创建了一个 JAXWsDynamicClientFactory 实例，然后使用服务的名称创建了一个代理对象。之后，我们调用了服务的 sayHello 方法，并打印了结果。

运行客户端

客户端代码启动后，将通过代理调用服务端的 sayHello 方法，并显示出服务端返回的消息。

以上步骤展示了如何使用Apache CXF来创建SOAP服务的客户端和服务端，并通过生成的Java代码进行远程调用。通过这种方式，开发者可以将精力集中在业务逻辑的实现上，而不是底层通信的细节。

5. 服务部署与测试及Apache CXF的高级应用

5.1 服务的部署和调试方法

在开发Web服务之后，如何有效地将服务部署并确保它能够按预期工作是至关重要的。Apache CXF提供了多种部署选项，包括独立部署、集成到Servlet容器如Tomcat或Jetty，以及与Spring集成。

5.1.1 Apache CXF服务的部署步骤

部署Apache CXF服务可以遵循以下步骤：

准备服务类 : 首先确保你有一个通过Apache CXF框架注解或配置文件定义的服务接口及其实现。
打包服务 : 将服务类以及相关的配置文件打包成一个WAR或JAR文件。如果是在Servlet容器中部署，一般使用WAR格式。Spring Boot应用通常使用JAR文件。
部署到服务器 : 将打包后的文件部署到Web服务器或应用服务器上。如果是WAR文件，可以通过服务器的管理界面或使用命令行工具进行部署。JAR文件则可以直接运行，前提是已经安装了支持Spring Boot的运行时环境。
启动服务 : 启动服务器或运行JAR文件后，Apache CXF服务应当开始监听配置的端口，等待客户端调用。

5.1.2 服务部署后的测试流程

服务部署后，进行充分的测试是确保服务质量的关键一环。

单元测试 : 在服务编码阶段，应编写单元测试以验证业务逻辑的正确性。
集成测试 : 部署服务后，运行集成测试确保服务端点可以正确响应请求。
负载测试 : 对服务进行负载测试，确保服务在高并发情况下的稳定性和性能。
故障排查 : 如果在测试过程中发现问题，需要进行故障排查。这可能包括查看服务器日志、使用调试工具逐步执行代码等。

5.2 Apache CXF的高级功能探究

5.2.1 动态客户端的生成与应用

动态客户端生成是Apache CXF提供的一个高级特性，它允许开发者在不创建静态客户端代码的情况下，直接从WSDL动态地创建客户端代理。

动态客户端生成的步骤如下 :

加载WSDL : 使用 Service 类加载WSDL文件。
创建客户端 : 通过 Service 类的 create() 方法创建一个动态代理实例。
调用服务 : 使用生成的客户端实例调用Web服务。

示例代码片段如下:

Service service = new Service(new URL(wsdlURL), new QName(targetNamespace, serviceName));
MyService myServiceProxy = service.getPort(MyService.class);
// 使用myServiceProxy作为服务客户端调用远程方法