Spring 整合 Apache CXF 開發 JAX-RS RESTful Web Service 完整實戰：Maven 依賴、配置、驗證與源碼

Spring 整合 Apache CXF 開發 JAX-RS RESTful Web Service 完整實戰：Maven 依賴、配置、驗證與源碼

JAX-RS (JSR-311/339/370) 是 Java RESTful Web Service 標準 API。Apache CXF 是成熟的 JAX-RS 實現，與 Spring 無縫整合。本文記錄從 Maven 依賴、web.xml、Spring XML 配置、服務實現到瀏覽器驗證的全流程，附 GitHub 源碼地址。

什麼是 JAX-RS？

• Java API for RESTful Web Services，定義註解驅動開發 REST 服務的標準：@Path, @GET, @POST, @Produces, @Consumes, @PathParam 等。
• 主流實現：Jersey (RI)、RESTEasy、Apache CXF、Spring MVC (非標準但事實標準)。

項目技術棧

• 框架：Spring 4.1.4 + Spring MVC + MyBatis 3.2.8
• CXF 版本：3.0.3 (對應 JAX-RS 2.0)
• 數據庫：MySQL 5.1.38 + Druid 1.0.15
• 構建：Maven + Tomcat7 Maven Plugin
• JSON 序列化：Jackson 1.1.1 (CXF 3.x 默認)

Maven 核心依賴

<properties>
    <cxf.version>3.0.3</cxf.version>
    <spring.version>4.1.4.RELEASE</spring.version>
    <jax.ws.rs>2.0.1</jax.ws.rs>
    <jackson.version>1.1.1</jackson.version>
</properties>

<dependencies>
    <!-- CXF JAX-RS 前端 -->
    <dependency>
        <groupId>org.apache.cxf</groupId>
        <artifactId>cxf-rt-frontend-jaxrs</artifactId>
        <version>${cxf.version}</version>
    </dependency>
    <!-- HTTP 傳輸 -->
    <dependency>
        <groupId>org.apache.cxf</groupId>
        <artifactId>cxf-rt-transports-http</artifactId>
        <version>${cxf.version}</version>
    </dependency>
    <!-- 服務描述 (WADL) -->
    <dependency>
        <groupId>org.apache.cxf</groupId>
        <artifactId>cxf-rt-rs-service-description</artifactId>
        <version>${cxf.version}</version>
    </dependency>
    <!-- JSON Provider -->
    <dependency>
        <groupId>org.codehaus.jackson</groupId>
        <artifactId>jackson-jaxrs</artifactId>
        <version>${jackson.version}</version>
    </dependency>
    <!-- JAX-RS API -->
    <dependency>
        <groupId>javax.ws.rs</groupId>
        <artifactId>javax.ws.rs-api</artifactId>
        <version>${jax.ws.rs}</version>
    </dependency>
    <!-- Spring + MyBatis 略 -->
</dependencies>

web.xml：註冊 CXFServlet

<servlet>
    <servlet-name>CXFServlet</servlet-name>
    <servlet-class>org.apache.cxf.transport.servlet.CXFServlet</servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>CXFServlet</servlet-name>
    <url-pattern>/ws/*</url-pattern>
</servlet-mapping>

所有 /ws/* 請求委派給 CXF 處理。

Spring XML：發布 JAX-RS 端點

<bean id="userWSService" class="cn.edu.hdu.wsdemo.wsservice.UserWSService" />
<bean id="jsonProvider" class="org.codehaus.jackson.jaxrs.JacksonJsonProvider" />

<jaxrs:server id="users" address="/apis">
    <jaxrs:serviceBeans>
        <ref bean="userWSService" />
    </jaxrs:serviceBeans>
    <jaxrs:providers>
        <ref bean="jsonProvider" />
    </jaxrs:providers>
</jaxrs:server>

• address="/apis"：相對於 /ws，完整路徑 /ws/apis。
• jsonProvider：註冊 Jackson 序列化提供者，自動處理 JSON 轉換。

服務實現類

@Path("/userwsservice/")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class UserWSService {

    @Autowired
    private IUserService userService;

    @GET
    @Path("/users/{id}/")
    public User getUser(@PathParam("id") String id) {
        Map param = new HashMap<>();
        param.put("id", id);
        List list = userService.query(param);
        return list.isEmpty() ? null : list.get(0);
    }

    @POST
    @Path("/users/getall")
    public List getAllUsers() {
        return userService.query(new HashMap<>());
    }
}

啟動與驗證

mvn clean tomcat:run

1. 服務列表頁：https://localhost:8080/wsdemo/ws → 顯示已發布端點。
2. WADL 文檔：https://localhost:8080/wsdemo/ws/apis?_wadl → 機器可讀服務描述。
3. 調用 GET：https://localhost:8080/wsdemo/ws/apis/userwsservice/users/4 → 返回 JSON 用戶對象。

關鍵截圖

源碼地址

https://github.com/peterchenhdu/demos/tree/master/wsdemo

常見坑點

1. Jackson 版本衝突：CXF 3.x 依賴 Jackson 1.x，Spring Boot 2.x 默認 Jackson 2.x → 排除傳遞依賴或升級 CXF 到 3.3+ (支持 Jackson 2)。
2. 命名空間衝突：jaxrs:server 需引入 xmlns:jaxrs="https://cxf.apache.org/jaxrs"。
3. Provider 註冊順序：多 Provider 時按註冊順序匹配媒體類型，JSON 放前面。
4. 參數綁定：@PathParam、@QueryParam、@FormParam、@HeaderParam、@Context (注入 HttpServletRequest 等)。
5. 異常映射：實現 ExceptionMapper<E> 並註冊為 Provider，統一錯誤響應格式。

參考資料

JavaCodeGeeks - Creating JAX-RS Web Service Using Apache CXF