使用Spring MVC 搭建Rest服务

http://blog.sina.com.cn/s/blog_616e189f0100snfg.html

使用Spring MVC 搭建Rest服务 (2011-06-24 21:48:28)转载▼标签： restfulspringmvcit 分类： java高级编程与虚拟计算平台 
使用Spring MVC 搭建Rest服务

本文由大关总结整理所得，不保证内容的正确性，转载请标明出处！

    Rest（Representational State Transfer，表述状态转移），是一种基于Http协议的，能够快速开发网络服务程序，并且提高网络服务系统伸展性的设计和开发方式。Rest的两端可以是不同构的编程和程序运行环境，Rest通过Http协议将通信的两端进行连接，在服务两端通过对Http协议的使用，最终完成数据的翻译和转换。

    Rest有几个重要的特点，使得Rest能够在服务搭建上占有一定的优势。首先，Rest以一切皆资源的方式来看待所有的web提供的服务（包括web服务本身，以及web服务中某个具体的服务应用），所有的资源都采用URI进行定位。其次，Rest通过对Http中相应字段属性设置，确定客户端和服务端的缓存策略，在一定程度上，可以缓解服务器和客户端的压力（Rest服务被认为是无状态的web服务），最后，Rest通过对Http消息体中（MIME）Content-Type的内容不同，可以采用不同处理策略对消息分解，获取需要的信息，此外Rest还有很多优势，具体可以参考：Architectural Styles and the Design of Network-based Software Architectures这篇论文，文中详细描述了Rest服务的推导过程。

    要想使用Rest必须要了解Http服务中定义的几个关键的方法。GET，用于从服务端获取信息，但并不更改服务端的任何状态；POST，用于提交创建的信息，一般更改服务端的数据状态，并且返回新创建对象的ID（一般来说，为了保证ID的唯一性，ID的值需要由服务端来确定，因此在创建结束后会将新分配的ID反馈给客户端）；PUT，用于更改服务端某个对象的状态（一般被认为是Update），服务端状态受到影响，不需要返回影响后的结果；DELETE,删除服务端的对象，服务端的状态发生改变，可以返回删除后的对象，也可以不返回。（Http还有其他的方法，但在Rest中不是很常用，可以查看RFC2616）。这些方法仅是意义上这样说，但是并不是一定要这用，具体的方法对应的动作完全是服务两端确定的。

    在JAVA中搭建Rest服务有很多种，其中JAX-RS是JAVA定义的Rest服务的API，可以使用Apache实现的jersy搭建Rest服务。在Spring MVC中也提供了搭建Rest服务的方法，下文主要探讨如何使用Spring MVC搭建Rest服务。

    下面的内容需要您对如下内容有所了解：

（1）  会使用Spring框架，理解依赖注入原理，理解Spring的基本配置。

（2）  使用过Java相关的Web容器（例如，Tomcat或Apache等，这里使用的是Jetty，原理相同）

（3）  会使用一款OXM框架（例如：Castor或JAXB，这里使用的是JAXB2）

（4）  对什么是Http服务和什么是Rest服务略有了解

如果您完全满足上面的条件，那么理解下面的内容就根本不成问题，如果您对有些内容不是很清楚，可以先看整个服务的流程，具体细节可以略看。

1.  Rest功能说明

下面我们将开始使用Spring MVC的方法搭建一个Rest服务，在这个服务中，服务器端维护了一个关于Student的集合，客户端可以通过连接到服务端，向服务端添加、删除、查找和更新学生信息等操作。

2.  学生数据结构（bean）

通过对Rest功能的分析，可以看出，服务端有两个关键的数据结构，一个是用来表示学生信息的Student类，另外一个是用来表示学生集合的StudentList类。下面我们通过schema定义这两个数据结构。

StudentLists.xsd

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

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <xsd:complexType name="student">

       <xsd:sequence>

              <xsd:element name="name" type="xsd:string" minOccurs="1"/>

              <xsd:element name="age" type="xsd:int"/>

           </xsd:sequence>

           <xsd:attribute name="id" type="xsd:string" use="required"/>

    </xsd:complexType>

  

 







    <xsd:element name="studentList">

       <xsd:complexType>

           <xsd:sequence>

              <xsd:element name="students" type="student"  maxOccurs="unbounded"/>

           </xsd:sequence>

       </xsd:complexType>

    </xsd:element>

</xsd:schema>

可以看出，schema中定义了两个结构，一个是学生类型，一个是学生集合类型。学生类型包括两个元素（分别是name和age）和一个属性（id）。学生集合类型中仅包含一个元素（students，是一个学生类型的集合）。

通过使用xjc生成java类，xjc命令如下：

I:\programs\eclipse\SpringMVCRestTest\src>xjc -p com.upc.upcgrid.guan.springMvcR

estTest.bean.student StudentLists.xsd

xjc（xml to java compiler），可以将schema转换成java类，-p后面的两个参数分别是转换后的包名，以及需要转换的schema文件名字。此时，你刷新你的服务，可以看到xjc已经生成了Student类和StudentLists类，此外还生成了一个ObjectFactory类，这里我们不需要ObjectFactory类，因此直接将这个类删除，之后在Student类的声明前增加一条语句，使得Student类声明部分如下：

@XmlType(name = "student", propOrder = {

    "name",

    "age"

})

@XmlRootElement(name="student")

public class Student {

3.  学生管理类

学生的基本结构已经搭建完成，现在需要提供一个管理类，用于来管理学生集合（注意，正常情况下，应当将学生数据存入数据库，这里为了简化，仅将这些信息出入一个Map中进行管理）。学生管理类维护这学生集合，以及基于集合之上的操作。

StudentManager.java



@Component

public class StudentManager {

    Map<String, Student> students = new ConcurrentHashMap<String, Student>();

  

    public synchronized void addStudent(Student student){

       if(students.containsKey(student.getId()))

           return;

       students.put(student.getId(), student);

    }

  

    public synchronized void deleteStudent(String id){

       if(students.containsKey(id))

           students.remove(id);

    }

  

    public synchronized void updateStudent(String id,Student student){

       deleteStudent(id);

       if(student.getId()==null || student.getId().equals(""))

           student.setId(id);

       addStudent(student);

    }

  

    public synchronized Student getStudent(String id){

       return students.get(id);

    }



    public synchronized StudentList getStudent() {

       StudentList sl = new StudentList();

       for(String key : students.keySet())

       {

           sl.getStudents().add(students.get(key));

       }

       return sl;

    }

  

}

可以看出，我们将StudentManager标记成component，以便Spring能够将这个类的实例注入到使用它的类中（注意，这个类必须是一个单例模式，因为这个类中维护着学生的集合）。此外，StudentManager中的所有方法都标记成了同步方法，并且Map集合也是一个同步集合。StudentManager提供了对学生集合Map的基本操作。

4.  Rest服务实现

下面提供了使用Spring MVC实现Rest服务的方法。



@Controller

@RequestMapping(value="/students")

public class StudentServer {

    private StudentManager manager;

     

    @RequestMapping(method=RequestMethod.POST)

    @ResponseBody

    public String createStudent(@RequestBody Student student){

       manager.addStudent(student);

       return student.getId();

    }

  

    @RequestMapping(value="/{id}",method=RequestMethod.GET)

    @ResponseBody

    public Student getStudent(@PathVariable String id){

       return manager.getStudent(id);

    }

  

    @RequestMapping(method=RequestMethod.GET)

    @ResponseBody

    public StudentList getStudent(){

       return manager.getStudent();

    }

  

    @RequestMapping(value="/{id}",method=RequestMethod.PUT)

    @ResponseBody

    public void updateStudent(@RequestBody Student student,@PathVariable String id){

       manager.updateStudent(id, student);

    }

  

    @RequestMapping(value="/{id}",method=RequestMethod.DELETE)

    @ResponseBody

    public void deleteStudent(@PathVariable String id){

       manager.deleteStudent(id);

    }



    @Autowired

    public void setManager(StudentManager manager) {

       this.manager = manager;

    }

}

用Control标记，Spring会认为这是一个Web服务，使用RequestMapping指明了服务映射的URI内容和映射的Http请求的方法。使用PathVariable可以从URI中获取参数，使用RequestBody，Spring会将Http消息体内部的数据使用配置策略转换成一个对象（参考5. Spring的配置），使用ResponseBody，Spring会将返回值转换成消息体需要的格式（参考5.Spring的配置）。

5.  Spring的配置

现在，我们需要对Spring进行基本的配置，以便Spring能够使用正确的方式对接收到（发送出）的Http请求（相应）使用正确的方法处理（生成）消息体。我们的基本策略是，如果接收到的是XML文档（即Content-type是***/xml类型），则使用JAXB2将消息体转换成对象，否则将消息体作为普通文本进行处理；如果要发送的消息是复杂对象（不是简单类型，例如：String、Integer、void等），则将消息使用JAXB2进行编组，否则仅生成文本消息。

Spring的配置如下：

SpringConfig.java

@Configuration

public class SpringConfig {

    private Jaxb2Marshaller marshaller;

  

    public @Bean Jaxb2Marshaller jaxb2Marshaller()//配置JAXB2Context

    { 

       Jaxb2Marshaller marshaller = new Jaxb2Marshaller();//创建JAXB上下文环境

       marshaller.setClassesToBeBound(Student.class,StudentList.class);//映射的xml类放入JAXB环境中   

       this.marshaller = marshaller;

       return marshaller;

    }

  

    public @Bean AnnotationMethodHandlerAdapter annotationMethodHandlerAdapter()

    {

       AnnotationMethodHandlerAdapter adapter = new AnnotationMethodHandlerAdapter();//创建消息体转换器

       HttpMessageConverter<?>[] converters = new HttpMessageConverter<?>[2];//创建转换数组

       StringHttpMessageConverter stringConverter = new StringHttpMessageConverter();//创建字符转换器

       MarshallingHttpMessageConverter marshallerConverter = new MarshallingHttpMessageConverter();//创建xom转换器

       marshallerConverter.setMarshaller(marshaller);//设置marshaller

       marshallerConverter.setUnmarshaller(marshaller);//设置unmarshaller

       //将两个转换器放入列表

       converters[0] = (stringConverter);

       converters[1] = (marshallerConverter);

       //将转换器列表赋值给消息体转换器

       adapter.setMessageConverters(converters);

       return adapter;   //返回消息体转换器 

    }

}

SpringConfig中先配置了JAXB2，在JAXB2中需要指定在2学生数据结构中生成的两个类，因此JAXB环境会知道如何将Student和StudentList编组和解组。

SpringConfig中还配置了一个Adapter，这个转换器是Spring用来转换消息体时使用的，在这里，我们为Adapter配置了两个Converter，一个使用来处理XML的Marshaller的Converter，一个是用来处理普通类型String的Converter。因此Spring会根据情况，选择正确的Converter处理消息体。（注意，只要你提供了一个Adapter，Spring就会使用你提供的这个Adapter处理消息体，如果你没有提供，Spring将会使用默认的Adapter处理消息体，由于对于XML类型（或者JSON类型）的数据必须手动提供Converter，所以这里不能使用默认的Converter）。

之后是Spring的配置文件：

rest-servlet.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:context="http://www.springframework.org/schema/context"

       xmlns:tx="http://www.springframework.org/schema/tx"

       xmlns:aop="http://www.springframework.org/schema/aop"

     

       xsi:schemaLocation="http://www.springframework.org/schema/beans

           http://www.springframework.org/schema/beans/spring-beans-2.5.xsd

           http://www.springframework.org/schema/aop

           http://www.springframework.org/schema/aop/spring-aop-2.5.xsd

           http://www.springframework.org/schema/tx

           http://www.springframework.org/schema/tx/spring-tx-2.5.xsd

           http://www.springframework.org/schema/context

           http://www.springframework.org/schema/context/spring-context-2.5.xsd">

           <context:annotation-config/>

           <context:component-scan base-package="com.upc.upcgrid.guan"/>               

</beans>

Spring的配置文档中，仅让Spring环境扫描标有标记类的包。

web.xml

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

<web-app version="2.5"

    xmlns="http://java.sun.com/xml/ns/javaee"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee

    http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

  

    <servlet>

       <servlet-name>rest</servlet-name>

       <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>

       <init-param>

           <param-name>contextConfigLocation</param-name>

           <param-value>/conf/rest-servlet.xml</param-value>

       </init-param>

       <load-on-startup>1</load-on-startup>

    </servlet>

  

    <servlet-mapping>

       <servlet-name>rest</servlet-name>

       <url-pattern>/rest/*</url-pattern>

    </servlet-mapping> 

</web-app>

Spring使用DispatcherServlet完成URI任务的匹配和分发，在创建DispatcherServlet的时候，提供了Spring配置文件的路径。

6.  Jetty服务器的配置和启动

我们这里使用较轻量级的Jetty服务器，以嵌入式的方式启动Spring服务。Jetty服务要比Tomcat小的多，并且无需安装，可以嵌入到程序中执行。下面给出Jetty的启动过程。

JettyServerStart.java

public class JettyServerStart {

    public static void main(String[] args) {

     

        Server server= new Server();//创建jetty web容器（这与tomcat容器类似）

       server.setStopAtShutdown(true);//在退出程序是关闭服务

     

       //创建连接器，每个连接器都是由IP地址和端口号组成，连接到连接器的连接将会被jetty处理

       //第一个连接器的连接方式为http://202.194.158.128:8586

       Connector connector = new SelectChannelConnector();//创建一个连接器

       connector.setPort(8586);//连接的端口号，(tomcat下)一般是8080，这里根据服务需求进行设置

       connector.setHost("202.194.158.128");//ip地址

       server.addConnector(connector);//添加连接

     

       //创建本地连接器，连接方式为http://localhost:8585

       Connector connectorLocal = new SelectChannelConnector();

       connectorLocal.setPort(8585);

       connectorLocal.setHost("localhost");

       server.addConnector(connectorLocal);

     

       //配置rest服务

       WebAppContext context = new WebAppContext();//创建服务上下文

       context.setContextPath("/SpringMVCRestTest");//访问服务路径 http://{ip}:8568/SpringMVCRestTest

       context.setConfigurationDiscovered(true);

    context.setDescriptor(System.getProperty("user.dir")+File.separator+"conf"+File.separator+"web.xml");//指明服务描述文件，就是web.xml

       context.setResourceBase(System.getProperty("user.dir"));//指定服务的资源根路径，配置文件的相对路径与服务根路径有关

       server.setHandler(context);//添加处理

     

       try {

           server.start();//开启服务

           server.join();

       } catch (Exception e) {

           e.printStackTrace();

           System.exit(1);

       }//开启服务

    }

现在，我们执行main方法，会的到如下输出：

2011-06-24 21:22:07.609:INFO::jetty-7.3.0.v20110203

2011-06-24 21:22:07.796:INFO::NO JSP Support for /SpringMVCRestTest, did not find org.apache.jasper.servlet.JspServlet

2011-06-24 21:22:07.921:INFO::started o.e.j.w.WebAppContext{/SpringMVCRestTest,file:/I:/programs/eclipse/SpringMVCRestTest/}

2011-06-24 21:22:08.093:INFO:/SpringMVCRestTest:Initializing Spring FrameworkServlet 'rest'

2011-6-24 21:22:08 org.springframework.web.servlet.FrameworkServlet initServletBean

信息: FrameworkServlet 'rest': initialization started

2011-6-24 21:22:08 org.springframework.context.support.AbstractApplicationContext prepareRefresh

信息: Refreshing WebApplicationContext for namespace 'rest-servlet': startup date [Fri Jun 24 21:22:08 CST 2011]; root of context hierarchy

2011-6-24 21:22:08 org.springframework.beans.factory.xml.XmlBeanDefinitionReader loadBeanDefinitions

信息: Loading XML bean definitions from ServletContext resource [/conf/rest-servlet.xml]

2011-6-24 21:22:08 org.springframework.beans.factory.support.DefaultListableBeanFactory preInstantiateSingletons

信息: Pre-instantiating singletons in org.springframework.beans.factory.support.DefaultListableBeanFactory@7736bd: defining beans [org.springframework.context.annotation.internalConfigurationAnnotationProcessor,org.springframework.context.annotation.internalAutowiredAnnotationProcessor,org.springframework.context.annotation.internalRequiredAnnotationProcessor,org.springframework.context.annotation.internalCommonAnnotationProcessor,springConfig,studentManager,studentServer,jaxb2Marshaller,annotationMethodHandlerAdapter]; root of factory hierarchy

2011-6-24 21:22:08 org.springframework.oxm.jaxb.Jaxb2Marshaller createJaxbContextFromClasses

信息: Creating JAXBContext with classes to be bound [class com.upc.upcgrid.guan.springMvcRestTest.bean.student.Student,class com.upc.upcgrid.guan.springMvcRestTest.bean.student.StudentList]

2011-6-24 21:22:09 org.springframework.web.servlet.handler.AbstractUrlHandlerMapping registerHandler

信息: Mapped URL path [/students/{id}] onto handler [com.upc.upcgrid.guan.springMvcRestTest.spring.StudentServer@497904]

2011-6-24 21:22:09 org.springframework.web.servlet.handler.AbstractUrlHandlerMapping registerHandler

信息: Mapped URL path [/students/{id}.*] onto handler [com.upc.upcgrid.guan.springMvcRestTest.spring.StudentServer@497904]

2011-6-24 21:22:09 org.springframework.web.servlet.handler.AbstractUrlHandlerMapping registerHandler

信息: Mapped URL path [/students/{id}/] onto handler [com.upc.upcgrid.guan.springMvcRestTest.spring.StudentServer@497904]

2011-6-24 21:22:09 org.springframework.web.servlet.handler.AbstractUrlHandlerMapping registerHandler

信息: Mapped URL path [/students] onto handler [com.upc.upcgrid.guan.springMvcRestTest.spring.StudentServer@497904]

2011-6-24 21:22:09 org.springframework.web.servlet.handler.AbstractUrlHandlerMapping registerHandler

信息: Mapped URL path [/students.*] onto handler [com.upc.upcgrid.guan.springMvcRestTest.spring.StudentServer@497904]

2011-6-24 21:22:09 org.springframework.web.servlet.handler.AbstractUrlHandlerMapping registerHandler

信息: Mapped URL path [/students/] onto handler [com.upc.upcgrid.guan.springMvcRestTest.spring.StudentServer@497904]

2011-6-24 21:22:09 org.springframework.web.servlet.FrameworkServlet initServletBean

信息: FrameworkServlet 'rest': initialization completed in 969 ms

2011-06-24 21:22:09.125:INFO::Started SelectChannelConnector@202.194.158.128:8586

2011-06-24 21:22:09.125:INFO::Started SelectChannelConnector@localhost:8585

从输出的内容可以看出，Spring服务已经正常启动，并且Jetty将会在本地的8586和8585两个端口进行监听。

7.  编写客户端测试程序

Rest的客户端可以使用Spring的RestTemplate进行编写。为了给使用这屏蔽掉我们后台与服务器进行通信的复杂操作，我们编写了一个RestUtility，这个类主要完成与服务器的通信。

RestUtility.java

public class RestUtility {

    private static String url = "http://202.194.158.128:8586/SpringMVCRestTest/rest/students/";  

    private static RestTemplate restTemplate;

    static {

       createRestTemplate();

    }

  

    public static RestTemplate getRestTemplate(){  

       return restTemplate;

    }



    private static void createRestTemplate() {

       restTemplate = new RestTemplate();

       List<HttpMessageConverter<?>> converters = new ArrayList<HttpMessageConverter<?>>();//消息体转换器列表

       MarshallingHttpMessageConverter marshalConverter = new MarshallingHttpMessageConverter();//xom类型的消息体转换器

       Jaxb2Marshaller marshaller = new Jaxb2Marshaller();//创建JAXB2类型的xom环境

       marshaller.setClassesToBeBound(Student.class,StudentList.class);//将类绑定到JAXB2

       marshalConverter.setMarshaller(marshaller);//设置编组器

       marshalConverter.setUnmarshaller(marshaller);//设置解组器

       converters.add(marshalConverter);//将xom消息体转换器添加到列表

       converters.add(new StringHttpMessageConverter());

       restTemplate.setMessageConverters(converters);//将转换器列表放入RestTemplate

    }

  

    public static void addStudent(Student student) throws RestClientException, URISyntaxException{

       System.out.println(restTemplate.postForObject(new URI(url), student,String.class));

    }

  

    public static Student getStudent(String id){

       return restTemplate.getForObject(url+"{id}", Student.class, id);

    }

  

    public static void updateStudent(String id,Student student){

       restTemplate.put(url+"{id}", student, id);

    }

  

    public static void deleteStudent(String id){

       restTemplate.delete(url+"{id}", id);

    }

  

    public static StudentList getAllStudents() throws RestClientException, URISyntaxException{



       return restTemplate.getForObject(new URI(url),StudentList.class);

    }

}

这个类主要使用RestTemplate对服务器进行通信的。

最后给出一个测试程序，并给出结果.



public class RestClient {

    public static void main(String[] args) throws RestClientException, URISyntaxException {

       Student student = new Student();

       student.setAge(20);

       student.setName("Mary");

       student.setId("05080416");

     

       RestUtility.addStudent(student);     

       student.setAge(21);

       student.setName("Lucy");

       student.setId("05080411");

       RestUtility.addStudent(student);



     

       student = RestUtility.getStudent("05080416");

       System.err.println(student.getName());

     

       StudentList sl = RestUtility.getAllStudents();

       for(Student s : sl.getStudents())

       {

           System.err.println(s.getName());

       }

}

在测试程序中，我们先创建了两个学生，并将两个学生添加到远程，之后从远程查询了一个学生，并输出信息，然后查询了所有学生，输出信息。整个过程没有对错误进行处理。

执行输出：

2011-6-24 21:36:55 org.springframework.oxm.jaxb.Jaxb2Marshaller createJaxbContextFromClasses

信息: Creating JAXBContext with classes to be bound [class com.upc.upcgrid.guan.springMvcRestTest.bean.student.Student,class com.upc.upcgrid.guan.springMvcRestTest.bean.student.StudentList]

05080416

05080411

Mary

Lucy

Mary

8.  程序结构
参考：

    Spring3.0官方文档

    Spring MVC与JAX-RS对比：http://www.infoq.com/articles/springmvc_jsx-rs

    教材：Restful Java with JAX-RS

    论文：Architectural Styles and the Design of Network-based Software Architectures

    Jetty：http://blog.sina.com.cn/s/blog_616e189f0100r1fs.html

    JAXB：http://blog.sina.com.cn/s/blog_616e189f0100slij.html



源码下载：http://guanxinquan.download.csdn.net/