struts2: 玩转 rest-plugin

近期使用struts2的rest-plugin，参考官方示例struts2-rest-showcase，做了一个restful service小项目，但官网提供的这个示例过于简单，埋下了巨坑无数，下面是一些遇到的问题及解决办法：

注：下面这些问题，很多是相互关联的，要解决一个，得同时解决另一个。 

一、与config-browser-plugin、convension-plugin、非rest Action 共存的问题

rest-plugin的气场实在太强，一旦使用，config-browser-plugin、convension-plugin这二个plugin就挂了

解决思路：将所有rest服务，都放在/rest/路径下，用package的namespace把它隔离出来，其它常规的action，放在其它路径，这样二者就不冲突了

    <!-- Overwrite Convention -->
    <constant name="struts.convention.action.suffix" value="Controller" />
    <constant name="struts.convention.action.mapAllMatches" value="true" />
    <!--<constant name="struts.rest.content.restrictToGET" value="false" />-->
    <constant name="struts.convention.default.parent.package" value="rest-default" />
    <constant name="struts.convention.package.locators" value="action" />
    <!-- <constant name="struts.rest.namespace" value="/rest" /> -->
    <constant name="struts.convention.action.includeJars" value=".*?/_wl_cls_gen.*?jar(!/)?" />
    <constant name="struts.convention.exclude.parentClassLoader" value="true" />
    <constant name="struts.convention.action.fileProtocols" value="jar,zip,vfsfile,vfszip" />

    <constant name="struts.mapper.class" value="org.apache.struts2.dispatcher.mapper.PrefixBasedActionMapper" />
    <constant name="struts.mapper.prefixMapping" value="/rest:rest,:struts" />
    <constant name="struts.mapper.alwaysSelectFullNamespace" value="false" />

        <package name="default" namespace="/rest" extends="rest-default" />

二、拦截器及ModelDrive的问题

如果自定义拦截器（比如：自定义异常拦截器），默认情况下是无法拦截rest的Action

解决办法：

a) strut2.xml中定义二个package：rest-package、page-package，并在这二个package中，加上自己的拦截器，完整strut2.xml参考下面的内容：

<?xml version="1.0" encoding="UTF-8" ?>


<!DOCTYPE struts PUBLIC
    "-//Apache Software Foundation//DTD Struts Configuration 2.3//EN"
    "http://struts.apache.org/dtds/struts-2.3.dtd">

<struts>

    <bean name="xmlHandler" type="org.apache.struts2.rest.handler.ContentTypeHandler"
        class="com.cnblogs.yjmyzz.handler.XStreamHandler" />

    <bean name="jsonHandler" type="org.apache.struts2.rest.handler.ContentTypeHandler"
        class="com.cnblogs.yjmyzz.handler.JacksonHandler" />

    <!-- Overwrite Convention -->
    <constant name="struts.convention.action.suffix" value="Controller" />
    <constant name="struts.convention.action.mapAllMatches" value="true" />
    <!--<constant name="struts.rest.content.restrictToGET" value="false" />-->
    <constant name="struts.convention.default.parent.package"
        value="rest-default" />
    <constant name="struts.convention.package.locators" value="action" />
    <!-- <constant name="struts.rest.namespace" value="/rest" /> -->
    <constant name="struts.convention.action.includeJars" value=".*?/_wl_cls_gen.*?jar(!/)?" />
    <constant name="struts.convention.exclude.parentClassLoader"
        value="true" />
    <constant name="struts.convention.action.fileProtocols" value="jar,zip,vfsfile,vfszip" />

    <constant name="struts.mapper.class"
        value="org.apache.struts2.dispatcher.mapper.PrefixBasedActionMapper" />
    <constant name="struts.mapper.prefixMapping" value="/rest:rest,:struts" />
    <constant name="struts.mapper.alwaysSelectFullNamespace"
        value="false" />

    <package name="base-default" extends="struts-default">
        <global-results>
            <result name="error">/WEB-INF/common/error.jsp</result>
        </global-results>

        <global-exception-mappings>
            <exception-mapping exception="java.lang.Exception"
                result="error" />
        </global-exception-mappings>
    </package>

    <package name="rest-package" namespace="/rest" extends="base-default">
        <result-types>
            <result-type name="redirect"
                class="org.apache.struts2.dispatcher.ServletRedirectResult">
                <param name="statusCode">303</param>
            </result-type>
            <result-type name="redirectAction"
                class="org.apache.struts2.dispatcher.ServletActionRedirectResult">
                <param name="statusCode">303</param>
            </result-type>
        </result-types>
        <interceptors>
            <interceptor name="rest"
                class="org.apache.struts2.rest.ContentTypeInterceptor" />
            <interceptor name="restWorkflow"
                class="org.apache.struts2.rest.RestWorkflowInterceptor" />
            <interceptor name="messages"
                class="org.apache.struts2.interceptor.MessageStoreInterceptor" />
            <interceptor name="exceptionInterceptor"
                class="com.cnblogs.yjmyzz.interceptor.ExceptionInterceptor">
            </interceptor>
            <interceptor-stack name="restDefaultStack">
                <interceptor-ref name="exception" />
                <interceptor-ref name="alias" />
                <interceptor-ref name="servletConfig" />
                <interceptor-ref name="messages">
                    <param name="operationMode">AUTOMATIC</param>
                </interceptor-ref>
                <interceptor-ref name="prepare" />
                <interceptor-ref name="i18n" />
                <interceptor-ref name="chain" />
                <interceptor-ref name="debugging" />
                <interceptor-ref name="profiling" />
                <interceptor-ref name="actionMappingParams" />
                <interceptor-ref name="scopedModelDriven" />
                <interceptor-ref name="modelDriven">
                    <param name="refreshModelBeforeResult">true</param>
                </interceptor-ref>
                <interceptor-ref name="fileUpload" />
                <interceptor-ref name="checkbox" />
                <interceptor-ref name="staticParams" />
                <interceptor-ref name="params">
                    <param name="excludeParams">dojo..*</param>
                </interceptor-ref>
                <interceptor-ref name="rest" />
                <interceptor-ref name="conversionError" />
                <interceptor-ref name="validation">
                    <param name="excludeMethods">input,back,cancel,browse,index,show,edit,editNew,deleteConfirm,destroy,create</param>
                </interceptor-ref>
                <interceptor-ref name="restWorkflow">
                    <param name="excludeMethods">input,back,cancel,browse,index,show,edit,editNew,deleteConfirm,destroy,create</param>
                </interceptor-ref>
                <interceptor-ref name="exceptionInterceptor" />
            </interceptor-stack>
        </interceptors>
        <default-interceptor-ref name="restDefaultStack" />
        <default-class-ref class="org.apache.struts2.rest.RestActionSupport" />
    </package>

    <package name="page-package" namespace="/" extends="base-default">
        <interceptors>
            <interceptor name="exceptionInterceptor"
                class="com.cnblogs.yjmyzz.interceptor.ExceptionInterceptor">
            </interceptor>
            <interceptor-stack name="appStack">
                <interceptor-ref name="defaultStack">
                    <param name="modelDriven.refreshModelBeforeResult">true</param>
                </interceptor-ref>
                <interceptor-ref name="exceptionInterceptor" />
            </interceptor-stack>
        </interceptors>
        <default-interceptor-ref name="appStack" />
    </package>

</struts>

b) 所有rest Action继承自一个自定义基类，所有常规page的Action,继承自另一个自定义基类

这二个基类用@ParentPackage 指定package，分别对应struts2.xml中的配置，这样运行时，不管是rest action，还是非rest action，都能被拦截器拦截

package com.cnblogs.yjmyzz.action.base;

import org.apache.struts2.convention.annotation.ParentPackage;

import com.opensymphony.xwork2.ModelDriven;
import com.opensymphony.xwork2.ValidationAwareSupport;

@ParentPackage("rest-package")
public abstract class RestBaseAction extends ValidationAwareSupport implements
        ModelDriven<Object> {

    private static final long serialVersionUID = -8773131281804917145L;

    public abstract Object getModel();

}

package com.cnblogs.yjmyzz.action.base;

import org.apache.struts2.convention.annotation.ParentPackage;

import com.opensymphony.xwork2.ActionSupport;

@ParentPackage("page-package")
public class PageBaseAction extends ActionSupport {

    private static final long serialVersionUID = 2323603138082550798L;

}

另外：官方的示例为了简便，在setId方法里，直接给Model赋值了，但这有点误导，因为拦截器拦截到的方法，并不是setId()，而是show()/index()之类的方法，所以应该在show方法里，调用 model = xxx.getModel(id)，否则按原来的写法，如果getModel这里报错 -> setId()报错，但show()方法并没有出错，拦截器会认为没有异常发生。

    // GET /rest/orders/1
    public HttpHeaders show() {
        if (id != null) {
            // 如果id=x，演示拦截异常处理
            if (id.equals("x")) {
                testException();
            }
            this.model = ordersService.get(id);
        }
        return new DefaultHttpHeaders("show");
    }

    public void setId(String id) {
        this.id = id;
    }

三、返回XML节点的别名(alias)问题

默认情况下，返回的xml根节点为dto对应的完整package名，看上去很别扭

解决方法：

dto的class上，用@XStreamAlias指定别名

@XStreamAlias("order")
public class Order {}

然后再创建自己的XmlHandler，为了节省系统开销，下面的代码用了一个单例：

package com.cnblogs.yjmyzz.handler;

import com.thoughtworks.xstream.XStream;

public class XStreamFactory {

    private XStreamFactory() {
    }

    private static XStream xStream = null;

    public static XStream getInstance() {
        if (xStream == null) {
            xStream = new XStream();
            xStream.setMode(XStream.NO_REFERENCES);
        }
        return xStream;
    }

}

package com.cnblogs.yjmyzz.handler;

import java.io.IOException;
import java.io.Reader;
import java.io.Writer;

import org.apache.struts2.rest.handler.ContentTypeHandler;

import com.cnblogs.yjmyzz.dto.Order;
import com.cnblogs.yjmyzz.dto.OrderList;
import com.thoughtworks.xstream.XStream;

public class XStreamHandler implements ContentTypeHandler {

    public String fromObject(Object obj, String resultCode, Writer out)
            throws IOException {
        if (obj != null) {
            XStream xstream = XStreamFactory.getInstance();
            xstream.processAnnotations(obj.getClass());
            xstream.toXML(obj, out);
        }
        return null;
    }

    public void toObject(Reader in, Object target) {
        XStream xstream = XStreamFactory.getInstance();
        xstream.alias("data", OrderList.class);
        xstream.alias("order", Order.class);
        xstream.processAnnotations(target.getClass());
        xstream.fromXML(in, target);
    }

    public String getContentType() {
        return "application/xml";
    }

    public String getExtension() {
        return "xml";
    }

}

注：别名一定要在toObject方法里，明确指定，否则别名的注解不起作用。

最后在struts2.xml里，还要注册bean，参考前面完整的xml内容。

四、返回JSON的Date属性格式化的问题

默认情况下，如果model有日期型属性，返回的json格式十分长，看上去太臃肿，类似的，可以自己定义ContentTypeHandler来解决

package com.cnblogs.yjmyzz.handler;

import org.codehaus.jackson.map.ObjectMapper;

public class JacksonFactory {

    private JacksonFactory() {

    }

    private static ObjectMapper objectMapper = null;

    public static ObjectMapper getObjectMapper() {
        if (objectMapper == null) {
            objectMapper = new ObjectMapper();
        }
        return objectMapper;
    }

}

package com.cnblogs.yjmyzz.handler;

import java.io.IOException;
import java.io.Reader;
import java.io.Writer;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.apache.struts2.rest.handler.ContentTypeHandler;
import org.springframework.beans.BeanUtils;

public class JacksonHandler implements ContentTypeHandler {

    Logger logger = LogManager.getLogger(this.getClass());

    public String fromObject(Object obj, String resultCode, Writer out)
            throws IOException {
        if (obj != null) {
            JacksonFactory.getObjectMapper().writeValue(out, obj);
        }
        return null;
    }

    public void toObject(Reader in, Object target) {
        try {
            Object origin = JacksonFactory.getObjectMapper().readValue(in,
                    target.getClass());
            BeanUtils.copyProperties(origin, target);

        } catch (Exception e) {
            e.printStackTrace();
            logger.error(e);
        }

    }

    public String getContentType() {
        return "application/json;charset=UTF-8";
    }

    public String getExtension() {
        return "json";
    }

}

五、restful service 该返回哪种视图，xhtml? json? xml?

通常用rest-plugin，是为了开发rest-service，但是官网的示例返回的默认都是页面视图，这个显然不适合，最理想情况是，如果在页面上操作，操作完以后，应该返回页面视图（即: xxx.xhtml），如果是用xml参数进来的，应该返回xml视图(即： xxx.xml)，如果是ajax用json post过来的，应该返回到json视图（即：xxx.json）

解决办法：根据Request的Header来判断来源，然后做相应的分支处理

    // POST /orders
    public HttpHeaders create() throws IOException {
        ordersService.save(model);
        HttpServletResponse response = ServletActionContext.getResponse();
        HttpServletRequest request = ServletActionContext.getRequest();
        String accept = request.getHeader("Accept");
        if (accept.contains("text/html")) { // 页面视图过来的
            response.sendRedirect("orders/");
        } else if (accept.contains("text/xml")) { // 发送xml过来的
            response.sendRedirect("orders/" + model.getId() + ".xml");
        } else { // 其它的返回json视图
            response.sendRedirect("orders/" + model.getId() + ".json");
        }
        return null;
    }

六、json post到service，model取不到值的问题

这个问题最恶心，连官方默认提供的org.apache.struts2.rest.handler.JsonLibHandler都有问题，原因在json反序列化的机制，大家可以感受下这段代码：

    @Test
    public void testJson() {
        String test = "{"id":"3","clientName":"Bob","amount":33,"createTime":"1413947088717"}";
        Order order = new Order();

        System.out.println(order);
        System.out.println(order.hashCode());

        System.out.println("----");

        toObjectJson(test, order);

        System.out.println("----");

        System.out.println(order);
        System.out.println(order.hashCode());
    }

    public void toObjectJson(String in, Object target) {
        try {
            target = JacksonFactory.getObjectMapper().readValue(in,
                    target.getClass());        
            System.out.println(target);
            System.out.println(target.hashCode());

        } catch (Exception e) {
            e.printStackTrace();

        }
    }

输出结果：

id:null,clientName:null,amount:0,createTime:Wed Oct 22 15:05:12 CST 2014

29791
----
id:3,clientName:Bob,amount:33,createTime:Wed Oct 22 11:04:48 CST 2014
2137470
----
id:null,clientName:null,amount:0,createTime:Wed Oct 22 15:05:12 CST 2014
29791

虽然传递的参数是Object，因java只有值传递，这里传递的值即为对象的“指针地址值”，但是json内部反序列化时，入口并非这个指针值，而是xxx.getClass()，即类型指针，导致最后toObject执行完，原来的指针是啥还是啥，跟反序列过程中"新创建"出来的新Object instance，完全豪无关联。因此，不得不改造成

    public void toObject(Reader in, Object target) {
        try {
            Object origin = JacksonFactory.getObjectMapper().readValue(in,
                    target.getClass());
            BeanUtils.copyProperties(origin, target);

        } catch (Exception e) {
            e.printStackTrace();
            logger.error(e);
        }

    }

手动把新对象的属性，复制到target对象上，这样就保证了反序列后的结果，在toObject执行完以后，会反映到target上。

注：可能有朋友会问了，为什么只有json会这样，xml不会呢？再仔细看下XStreamHandler的toObject方法

    public void toObject(Reader in, Object target) {
        XStream xstream = XStreamFactory.getInstance();
        xstream.alias("data", OrderList.class);
        xstream.alias("order", Order.class);
        xstream.processAnnotations(target.getClass());
        xstream.fromXML(in, target);
    }

最后一行xstream.fromXML(in, target);这是开始xml->object的入口，这里传递的就是target的地址对应的值，而不是象json那样是xxx.getClass()。如果进一步看源码，最后会发现执行的是com.thoughtworks.xstream.core.TreeUnmarshaller类里的

    public TreeUnmarshaller(
        Object root, HierarchicalStreamReader reader, ConverterLookup converterLookup,
        Mapper mapper) {
        this.root = root;
        this.reader = reader;
        this.converterLookup = converterLookup;
        this.mapper = mapper;
    }

整个过程，都没有新对象实例创建，所以相应的变化，能一直保持到toObject调用完成后。

七、id参数太单一的问题

这个其实并不是大太的问题，GET方式下，url里本来就不适合传递过多参数，实在想用多个参数，做个约定，比如  /orders/show/a-b-c，即id值为"a-b-c"，然后拆解一下，a,b,c对应不同的含义即可

POST方式，更不成问题，直接post过来一段xml或json，最终映射成model，想要多少参数都不是问题

最后给出源码示例：struts-rest-ex-src.zip （基于官网的rest-showcase修改而来）