如何用wadl2java生成含POST/PUT参数的REST服务模板并解决非GET代码无效问题

哥们，我之前也碰到过一模一样的情况——用wadl2java和cxf-wadl2java-plugin生成的代码，GET方法好好的，POST/PUT却根本没法正常调用。其实核心问题大多出在WADL规范不严谨或者插件配置不到位上，下面我一步步给你捋清楚怎么解决：

一、先排查你的WADL问题（POST/PUT失效的核心原因） #

很多时候问题出在WADL里对非GET方法的参数/请求体定义不完整。比如你只引用了xsd，但没在资源方法里明确关联请求体类型。给你个正确的WADL示例，假设你的book.xsd里定义了Book实体：

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://wadl.dev.java.net/2009/02" xmlns:ns="http://superbooks" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <grammars>
        <include href="book.xsd"/>
    </grammars>
    <resources base="http://localhost:8080/api">
        <resource path="/books">
            <!-- GET方法示例（略） -->
            <method name="POST">
                <request>
                    <!-- 关键：绑定请求体到XSD定义的Book类型 -->
                    <representation mediaType="application/json" element="ns:Book"/>
                </request>
                <response>
                    <representation mediaType="application/json" element="ns:Book"/>
                </response>
            </method>
            <resource path="/{bookId}">
                <!-- 路径参数必须明确标注style="template" -->
                <param name="bookId" type="xsd:string" style="template"/>
                <method name="PUT">
                    <request>
                        <representation mediaType="application/json" element="ns:Book"/>
                    </request>
                    <response status="200"/>
                </method>
            </resource>
        </resource>
    </resources>
</application>

这里要注意两个关键点：

• 非GET方法必须在<request>标签里通过<representation>指定媒体类型和对应XSD元素，不然wadl2java不知道要生成请求体绑定的代码；
• 路径参数要通过<param>的style="template"明确标注，否则生成的方法会缺失路径参数注解。

二、正确配置cxf-wadl2java-plugin插件 #

Maven插件的配置直接影响代码生成的完整性，尤其是服务端接口的生成。给你一份标准配置：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.cxf</groupId>
            <artifactId>cxf-wadl2java-plugin</artifactId>
            <version>3.6.2</version> <!-- 建议用最新稳定版 -->
            <executions>
                <execution>
                    <id>generate-rest-code</id>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>wadl2java</goal>
                    </goals>
                    <configuration>
                        <wadlFile>src/main/resources/api.wadl</wadlFile> <!-- 你的WADL路径 -->
                        <packageName>com.superbooks.api</packageName> <!-- 生成代码的包名 -->
                        <serverAPI>true</serverAPI> <!-- 启用服务端接口生成（必填，否则只生成客户端） -->
                        <jaxrsVersion>2.1</jaxrsVersion> <!-- 指定JAX-RS版本，自动生成规范注解 -->
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

重点说明：

• <serverAPI>true</serverAPI>：如果需要生成服务端的REST接口（而非仅客户端代理），这个选项必须打开；
• <jaxrsVersion>：指定版本后，插件会自动生成@POST、@Consumes、@PathParam等规范注解，不用手动补。

三、生成后的代码示例（服务端+客户端） #

按上面的配置生成后，服务端接口会是这样的：

package com.superbooks.api;

import javax.ws.rs.Consumes;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("/books")
public interface BooksResource {

    @POST
    @Consumes({ MediaType.APPLICATION_JSON })
    @Produces({ MediaType.APPLICATION_JSON })
    Book createBook(Book content);

    @PUT
    @Path("/{bookId}")
    @Consumes({ MediaType.APPLICATION_JSON })
    void updateBook(@PathParam("bookId") String bookId, Book content);
}

客户端则会生成对应的代理类，直接实例化后就能调用POST/PUT方法，参数会自动序列化为请求体。

四、常见坑点提醒 #

• 确保WADL里的XSD引用路径正确，插件能找到对应的schema文件，不然会报错或生成空的实体类；
• 如果是表单参数（application/x-www-form-urlencoded），要改用<param>标签并设置style="form"，而非<representation>；
• 生成代码后检查注解：比如@POST是否遗漏，@Consumes的媒体类型是否和WADL一致。

这样调整后，生成的POST/PUT方法应该就能正常使用了。

内容的提问来源于stack exchange，提问作者Jamie