Apache CXF WebService 完整教程

目录

1. 什么是 Apache CXF？
2. 核心概念：JAX-WS 与 JAX-RS
3. 环境准备
4. 第一部分：JAX-WS (SOAP WebService)
   • 1 快速入门：第一个 JAX-WS 服务
   • 2 发布服务
   • 3 调用服务 (客户端)
   • 4 高级特性：Spring 集成
5. 第二部分：JAX-RS (RESTful WebService)
   • 1 快速入门：第一个 JAX-RS 服务
   • 2 发布服务
   • 3 调用服务 (客户端)
   • 4 常用注解详解
6. CXF 常用特性
   • 1 数据格式转换 (XML/JSON)
   • 2 异常处理
   • 3 拦截器
7. 总结与最佳实践

什么是 Apache CXF？

Apache CXF 是一个开源的、功能强大的 WebService 框架，它提供了对多种 WebService 标准的支持，使得创建和消费 WebService 变得非常简单。

CXF 的核心特点：

• 支持标准广泛：全面支持 JAX-WS (Java API for XML Web Services) 和 JAX-RS (Java API for RESTful Web Services) 标准。
• 灵活的传输方式：支持 SOAP 1.1, SOAP 1.2, XML/HTTP, REST/HTTP 等多种协议和数据格式。
• 多种集成方式：可以轻松集成到 Spring、Servlet 容器中，也可以作为独立服务器运行。
• 丰富的扩展性：提供拦截器、数据绑定、Schema 生成等强大的扩展机制。

CXF 是一个“胶水”框架，帮你把 POJO (普通 Java 对象) 包装成符合标准的 WebService。

核心概念：JAX-WS 与 JAX-RS

在学习 CXF 之前，必须理解它所支持的两大标准，因为它们代表了两种完全不同的 WebService 风格。

• 如果你需要构建一个传统的、企业级的、有严格契约的 WebService，选择 JAX-WS。
• 如果你需要构建一个轻量级的、易于被浏览器和移动端消费的 API，选择 JAX-RS。

环境准备

1. JDK: 1.8 或更高版本。
2. IDE: Eclipse for Java EE 或 IntelliJ IDEA。
3. 构建工具: Maven (推荐) 或 Gradle。
4. Web 服务器: Tomcat (推荐) 或 Jetty。

第一部分：JAX-WS (SOAP WebService)

我们将创建一个简单的用户查询服务。

1 快速入门：第一个 JAX-WS 服务

创建 Maven 项目

在 pom.xml 中添加 CXF 和 Spring 的依赖（如果使用 Spring 发布，Spring 是必需的）。

<dependencies>
    <!-- CXF 核心依赖 -->
    <dependency>
        <groupId>org.apache.cxf</groupId>
        <artifactId>cxf-rt-frontend-jaxws</artifactId>
        <version>3.4.5</version> <!-- 使用最新稳定版 -->
    </dependency>
    <dependency>
        <groupId>org.apache.cxf</groupId>
        <artifactId>cxf-rt-transports-http</artifactId>
        <version>3.4.5</version>
    </dependency>
    <!-- 如果需要将服务发布到 Servlet 容器，需要此依赖 -->
    <dependency>
        <groupId>org.apache.cxf</groupId>
        <artifactId>cxf-rt-transports-http-jetty</artifactId>
        <version>3.4.5</version>
    </dependency>
    <!-- Spring 依赖，用于集成 -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>5.3.20</version>
    </dependency>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-web</artifactId>
        <version>5.3.20</version>
    </dependency>
</dependencies>

创建服务接口和实现

服务接口需要使用 @WebService 注解。

UserService.java (接口)

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;
@WebService(name = "UserService", targetNamespace = "http://service.cxf.example.com") // 建议设置命名空间
public interface UserService {
    @WebMethod
    String getUserById(@WebParam(name = "userId") String userId);
}

UserServiceImpl.java (实现)

import javax.jws.WebService;
@WebService(endpointInterface = "com.example.cxf.service.UserService") // 指向接口
public class UserServiceImpl implements UserService {
    @Override
    public String getUserById(String userId) {
        System.out.println("Server received request for user: " + userId);
        if ("001".equals(userId)) {
            return "{\"id\":\"001\", \"name\":\"Alice\", \"email\":\"alice@example.com\"}";
        }
        return "User not found";
    }
}

2 发布服务

CXF 提供了多种方式发布服务，这里介绍最常用的两种。

使用 Jetty 内嵌服务器（独立运行）

import org.apache.cxf.jaxws.JaxWsServerFactoryBean;
public class ServerMain {
    public static void main(String[] args) {
        // 1. 创建 JaxWsServerFactoryBean
        JaxWsServerFactoryBean factory = new JaxWsServerFactoryBean();
        // 2. 设置服务实现类
        factory.setServiceClass(UserServiceImpl.class);
        // 3. 设置发布地址
        factory.setAddress("http://localhost:8080/userService");
        // 4. 创建并启动服务
        factory.create();
        System.out.println("UserService started at http://localhost:8080/userService?wsdl");
    }
}

运行 ServerMain，然后访问 http://localhost:8080/userService?wsdl，如果能看到 WSDL 文件内容，说明服务发布成功。

集成到 Spring 和 Tomcat（企业级应用）

配置 Spring

在 src/main/resources 下创建 applicationContext.xml。

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:jaxws="http://cxf.apache.org/jaxws"
       xsi:schemaLocation="
           http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans.xsd
           http://cxf.apache.org/jaxws
           http://cxf.apache.org/schemas/jaxws.xsd">
    <!-- 1. 导入 CXF 的 Bean 定义 -->
    <import resource="classpath:META-INF/cxf/cxf.xml"/>
    <import resource="classpath:META-INF/cxf/cxf-servlet.xml"/>
    <!-- 2. 发布 JAX-WS 服务 -->
    <jaxws:endpoint id="userService"
                    implementor="com.example.cxf.service.UserServiceImpl"
                    address="/userService"/>
</beans>

配置 web.xml

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance