分分钟带你玩转 Web Services【2】：Apache CXF 深度解析与实践指南

目录#

Apache CXF 简介
核心概念与架构
实战演练一：使用 JAX-WS 构建 SOAP Web Service
实战演练二：使用 JAX-RS 构建 RESTful Web Service
高级特性：拦截器
最佳实践与常见问题
总结
参考资料

一、Apache CXF 简介#

Apache CXF 是一个开源的、全功能的、易于使用的 Web 服务框架。它源自于 Celtix 和 XFire 项目的合并，现在是 Apache 软件基金会的顶级项目。

主要特性：

标准支持：全面支持 JAX-WS 和 JAX-RS 等 Java EE 标准。
多种数据绑定：默认支持 JAXB（Java Architecture for XML Binding），也支持 JSON 绑定（如 Jackson）。
多种传输协议：支持 HTTP、Servlet、JMS 等。
灵活性：可以轻松地嵌入到 Spring 应用或其他 Java 应用中。
可扩展性：通过拦截器（Interceptors）机制，可以方便地扩展功能，如日志、安全、监控等。
工具支持：提供 wsdl2java、java2wsdl 等工具，方便客户端和服务端的代码生成。

二、核心概念与架构#

理解 CXF 的核心架构有助于我们更好地使用它。

前端（Frontend）：这相当于 CXF 的编程模型。最常用的是 JAX-WS 和 JAX-RS。
- JAX-WS：用于构建基于 SOAP 的 Web 服务。它使用注解（如 @WebService）来定义服务。
- JAX-RS：用于构建 RESTful Web 服务。它使用注解（如 @Path, @GET, @POST）来定义资源和操作。
数据绑定（Data Binding）：负责 Java 对象与 XML/JSON 等格式之间的相互转换。
- JAXB：是 CXF 的默认数据绑定方式，用于 XML 转换。
- Jackson 或 Jettison：常用于 JSON 转换。
传输（Transport）：定义消息如何被发送和接收。最常用的是 HTTP 协议，通过 Servlet 在 Web 容器（如 Tomcat）中运行。
拦截器（Interceptors）：这是 CXF 架构中最强大和核心的概念。拦截器允许你在消息处理的生命周期（如输入、输出、预处理、后处理）中插入自定义逻辑。常见的用途包括日志记录、身份验证、授权、消息加密/解密等。

简化架构图：

[JAX-WS/JAX-RS 代码] -> [CXF 前端] -> [数据绑定 (JAXB/Jackson)] -> [拦截器链] -> [传输层 (HTTP/JMS)]

三、实战演练一：使用 JAX-WS 构建 SOAP Web Service#

我们将创建一个简单的 CalculatorService，提供加法和减法运算。

步骤 1：定义服务接口（SEI - Service Endpoint Interface）#

使用 JAX-WS 注解 @WebService。

// CalculatorService.java
package com.example.service;
 
import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.jws.WebParam;
 
@WebService
public interface CalculatorService {
    
    @WebMethod
    double add(@WebParam(name = "a") double a, @WebParam(name = "b") double b);
    
    @WebMethod
    double subtract(@WebParam(name = "a") double a, @WebParam(name = "b") double b);
}

步骤 2：实现服务接口#

// CalculatorServiceImpl.java
package com.example.service.impl;
 
import javax.jws.WebService;
import com.example.service.CalculatorService;
 
@WebService(endpointInterface = "com.example.service.CalculatorService")
public class CalculatorServiceImpl implements CalculatorService {
 
    @Override
    public double add(double a, double b) {
        return a + b;
    }
 
    @Override
    public double subtract(double a, double b) {
        return a - b;
    }
}

步骤 3：发布服务（使用 Spring Boot）#

在 Maven pom.xml 中添加依赖：

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-spring-boot-starter-jaxws</artifactId>
    <version>3.5.5</version> <!-- 请使用最新版本 -->
</dependency>

创建一个配置类来发布服务：

// CxfConfig.java
package com.example.config;
 
import org.apache.cxf.Bus;
import org.apache.cxf.jaxws.EndpointImpl;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.example.service.impl.CalculatorServiceImpl;
 
import javax.xml.ws.Endpoint;
 
@Configuration
public class CxfConfig {
 
    @Autowired
    private Bus bus; // CXF 提供的 Bus
 
    @Bean
    public Endpoint calculatorEndpoint() {
        EndpointImpl endpoint = new EndpointImpl(bus, new CalculatorServiceImpl());
        endpoint.publish("/calculator"); // 服务发布的相对路径
        return endpoint;
    }
}

步骤 4：启动并测试#

启动 Spring Boot 应用后，你可以通过以下方式访问：

WSDL 地址： http://localhost:8080/services/calculator?wsdl
使用 SoapUI 或 Postman 等工具，根据 WSDL 生成 SOAP 请求进行测试。

四、实战演练二：使用 JAX-RS 构建 RESTful Web Service#

我们将创建一个简单的 UserService，提供对用户资源的 CRUD 操作。

步骤 1：定义数据模型#

// User.java
package com.example.model;
 
import javax.xml.bind.annotation.XmlRootElement;
 
@XmlRootElement // 用于 XML 序列化
public class User {
    private Long id;
    private String name;
    private String email;
 
    // 无参构造函数、Getter 和 Setter 是 JAXB 所必需的
    public User() {}
 
    public User(Long id, String name, String email) {
        this.id = id;
        this.name = name;
        this.email = email;
    }
 
    // ... 省略 Getter 和 Setter
}

步骤 2：创建 JAX-RS 资源类#

// UserResource.java
package com.example.rest;
 
import com.example.model.User;
import org.springframework.stereotype.Component;
 
import javax.ws.rs.*;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.atomic.AtomicLong;
 
@Path("/users")
@Produces(MediaType.APPLICATION_JSON) // 默认产生 JSON
@Consumes(MediaType.APPLICATION_JSON) // 默认消费 JSON
@Component // Spring 的注解，将其声明为 Bean
public class UserResource {
 
    private List<User> users = new ArrayList<>();
    private AtomicLong counter = new AtomicLong();
 
    public UserResource() {
        // 初始化一些测试数据
        users.add(new User(counter.incrementAndGet(), "Alice", "[email protected]"));
        users.add(new User(counter.incrementAndGet(), "Bob", "[email protected]"));
    }
 
    @GET
    public List<User> getAllUsers() {
        return users;
    }
 
    @GET
    @Path("/{id}")
    public Response getUserById(@PathParam("id") Long id) {
        User user = users.stream()
                         .filter(u -> u.getId().equals(id))
                         .findFirst()
                         .orElse(null);
        if (user != null) {
            return Response.ok(user).build();
        } else {
            return Response.status(Response.Status.NOT_FOUND).build();
        }
    }
 
    @POST
    public Response createUser(User user) {
        user.setId(counter.incrementAndGet());
        users.add(user);
        return Response.status(Response.Status.CREATED).entity(user).build();
    }
}

步骤 3：配置 JAX-RS（使用 Spring Boot）#

在 pom.xml 中添加 JAX-RS 依赖：

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-spring-boot-starter-jaxrs</artifactId>
    <version>3.5.5</version>
</dependency>
<!-- 如果需要 JSON 支持，添加 Jackson -->
<dependency>
    <groupId>com.fasterxml.jackson.jaxrs</groupId>
    <artifactId>jackson-jaxrs-json-provider</artifactId>
    <version>2.14.2</version>
</dependency>

创建配置类：

// RestConfig.java
package com.example.config;
 
import com.example.rest.UserResource;
import com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider;
import org.apache.cxf.bus.spring.SpringBus;
import org.apache.cxf.endpoint.Server;
import org.apache.cxf.jaxrs.JAXRSServerFactoryBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
 
import javax.ws.rs.ext.MessageBodyReader;
import javax.ws.rs.ext.MessageBodyWriter;
import java.util.Arrays;
 
@Configuration
public class RestConfig {
 
    @Bean
    public Server jaxRsServer() {
        JAXRSServerFactoryBean factory = new JAXRSServerFactoryBean();
        factory.setResourceClasses(UserResource.class);
        factory.setResourceProvider(new SpringResourceProvider());
        // 设置 JSON 提供者
        factory.setProviders(Arrays.asList(new JacksonJsonProvider()));
        factory.setAddress("/rest"); // REST 服务的根路径
        return factory.create();
    }
}

步骤 4：启动并测试#

启动应用后，可以使用浏览器或 curl 命令测试：

GET http://localhost:8080/rest/users （获取所有用户）
GET http://localhost:8080/rest/users/1 （获取 ID 为 1 的用户）
POST http://localhost:8080/rest/users （创建新用户）

五、高级特性：拦截器#

拦截器是 CXF 的灵魂。我们以实现一个简单的日志拦截器为例。

创建日志拦截器#

// LoggingInInterceptor.java
package com.example.interceptor;
 
import org.apache.cxf.interceptor.Fault;
import org.apache.cxf.message.Message;
import org.apache.cxf.phase.Phase;
import org.apache.cxf.phase.PhaseInterceptor;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
 
import java.io.ByteArrayInputStream;
import java.io.InputStream;
 
public class LoggingInInterceptor implements PhaseInterceptor<Message> {
 
    private static final Logger logger = LoggerFactory.getLogger(LoggingInInterceptor.class);
 
    @Override
    public void handleMessage(Message message) throws Fault {
        // 获取输入流并记录内容
        try (InputStream is = message.getContent(InputStream.class)) {
            if (is != null) {
                byte[] bytes = is.readAllBytes();
                String soapMessage = new String(bytes);
                logger.info("Incoming SOAP Request: \n{}", soapMessage);
 
                // 重要：将流重置，以便后续处理
                message.setContent(InputStream.class, new ByteArrayInputStream(bytes));
            }
        } catch (Exception e) {
            logger.error("Error during logging", e);
        }
    }
 
    @Override
    public void handleFault(Message message) {
        // 处理错误
    }
 
    @Override
    public String getId() {
        return "CustomLoggingInInterceptor";
    }
 
    @Override
    public String getPhase() {
        return Phase.RECEIVE; // 在接收阶段执行
    }
}

将拦截器添加到端点#

修改之前的 CxfConfig 类：

@Bean
public Endpoint calculatorEndpoint() {
    EndpointImpl endpoint = new EndpointImpl(bus, new CalculatorServiceImpl());
    endpoint.publish("/calculator");
    
    // 添加自定义日志拦截器
    endpoint.getInInterceptors().add(new LoggingInInterceptor());
    
    return endpoint;
}

现在，所有发送到 /calculator 端点的 SOAP 请求都会被记录下来。

六、最佳实践与常见问题#

最佳实践#

接口与实现分离：在 JAX-WS 中，始终先定义服务端点接口（SEI），再实现它。这提高了代码的清晰度和可测试性。
使用 Spring/Spring Boot：利用 CXF 与 Spring 的无缝集成，通过配置管理端点、拦截器和数据绑定，使应用更易于维护。
统一异常处理：
- JAX-WS：使用 @WebFault 注解创建自定义异常。
- JAX-RS：使用 ExceptionMapper 接口将异常转换为友好的 HTTP 响应。
版本管理：对于 RESTful API，在 URL 路径（如 /api/v1/users）或 Accept 头中明确指定版本号。
安全性：结合 Spring Security 或 CXF 自带的 WS-Security 拦截器来实现认证和授权。

常见问题#

问题：No message body writer found 错误。
- 原因： JAX-RS 服务无法将 Java 对象序列化为客户端请求的格式（如 JSON/XML）。
- 解决：确保添加了正确的依赖（如 jackson-jaxrs-json-provider）并且模型类有无参构造函数和 Getter/Setter。
问题：WSDL 无法访问或 404 错误。
- 原因：服务发布路径不正确或 Servlet 配置有误。
- 解决：检查 CXF Servlet 的映射路径（默认是 /services/*）和你的端点发布路径。
问题：命名空间或元素名不符合预期。
- 原因： JAXB/JAX-WS 注解使用不当。
- 解决：使用 @XmlType, @XmlElement 等注解显式控制生成的 XML 结构和命名空间。

七、总结#

Apache CXF 是一个强大而灵活的 Web 服务框架，它极大地简化了 SOAP 和 RESTful 服务的开发。通过本文，我们了解了其核心架构，并通过两个完整的实战示例演示了如何构建服务。我们还探讨了其强大的拦截器机制和一些最佳实践。

掌握 CXF 的关键在于理解其“配置优于编码”的理念，并熟练运用 JAX-WS 和 JAX-RS 标准。希望这篇指南能帮助你在 Web Services 的世界里更加游刃有余。

目录#

一、Apache CXF 简介#

二、核心概念与架构#

三、实战演练一：使用 JAX-WS 构建 SOAP Web Service#

步骤 1：定义服务接口（SEI - Service Endpoint Interface）#

步骤 2：实现服务接口#

步骤 3：发布服务（使用 Spring Boot）#

步骤 4：启动并测试#

四、实战演练二：使用 JAX-RS 构建 RESTful Web Service#

步骤 1：定义数据模型#

步骤 2：创建 JAX-RS 资源类#

步骤 3：配置 JAX-RS（使用 Spring Boot）#

步骤 4：启动并测试#

五、高级特性：拦截器#

创建日志拦截器#

将拦截器添加到端点#

六、最佳实践与常见问题#

最佳实践#

常见问题#

七、总结#

参考资料#