rest service

选型

   REST还是遵循JAX-RS规范，选型就只在Sun Jersey, Apache CXF 和 JBoss RESTEasy中展开。 JBoss的项目习惯性忽略，而CXF的JSON输出，List/Map输出总是做不好(JAXB的顽疾)，最后用了Jersey。

   但无论Jersey 还是 CXF，JSON输出都是先要绕一圈JAXB，所以用了号称JSON最快的Jackson的JAX-RS provider。

In SpringSide3

1. 应用集成

• 与Web应用集成：在web.xml里面划一个/services/* 归Jersey管即可。
• 与Spring集成: 添加jersey-spring.jar在classpath里，然后就爱干嘛干嘛了。

2. 参数输入

• @PathParam用来表示Restful风格下在URL中的id等标识。（见mini-service getUser)
• @QueryParameter可以转换任何有以String为参数的构造函数类，还可以设定defaultValue, 当参数为空时可以自动抛异常(见showcase searchUser)
• @POST+ @Consumes 以POST方式传递XML或JSON编码的Java对象 (见mini-service createUser)
• @Context UriInfo， @Context HttpHeaders, @Context HttpServletRequest 获取灵活的，不固定的参数. 可以从原版HttpServletRequest中获取,也可以用封装好的更方便的UriInfo和HttpHeaders.(见showcase searchUserByFlexibleParameter)

3. 结果输出

• 直接返回对象，用@Produces控制输出的格式为Html/Xml/JSON等。
• 返回Response对象，一般用于返回304 无更新，或者create对象之后返回对象uri标识。(见mini-service createUser)
• 返回Response对象，用于要根据不同的输入参数，决定返回Html或Xml/JSON, 而且Html与JSon返回的内容又不一样的时候。(showcase searchUser)

4. 异常输出

• 要抛一个干净的500错误，throw new WebApplicationException(); 即可。
• 要自定义错误返回码和错误信息的话：
  1.使用标准返回码： new WebApplicationException(Response.status(status).entity(message).type("text/plain").build());
  2.使用非标准返回码：new WebApplicationException(Response.status(status).entity(message).type("text/plain").build());

5. 客户端

      JAX-RS规范并没有对客户端进行定义，基本上大家各显神通了。

5.1 客户端输入参数

• 输入URL Query参数 client.path("/users/search").queryParam("name", name)
• 输入JSON编码的对象 client.path("/users").entity(user, MediaType.APPLICATION_JSON)

5.2 客户端返回定义

• String.class, 直接取得返回的字符串，自己进行处理。
• UserDTO.class, 让Jersey帮忙将编码字符串转成对应的Java对象。
• new GenericType<List<UserDTO>>() } 专门用于根对象是List, Map这些JAXB最头痛的对象。
• ClientResponse.class, 可以用来取得返回值，已创建对象URI等

5.3 HttpBasic安全控制

        自行对用户名密码进行HttpBasic编码后放入Http Header即可.(见showcase的getAllUser)

6. Jackson JSON Provider

       在META-INF/services中放入javax.ws.rs.ext.MessageBodyReader/Writer文件，里面指定使用 Jackson，就可以远离CXF和Jersey基于JAXB的，即使做了N多配置还是不让人满意的JSON实现了。