要定义一个严谨的REST统一接口，就需要真正理解HTTP方法的安全性和幂等性。安全性代表安全的REST接口，是指外系统对该接口的访问，不会使服务器端的资源的状态发生改变，幂等性是指外系统对同一REST接口的多次访问，得到的资源状态是相同的。

一.HTTP 方法

GET 方法

HTTP的GET方法用于读取资源。GET方法是幂等性的，因为读取同一个资源，总是得到相同的数据。GET方法也是安全性的，因为读取资源不会对其状态做改动。JAX-RS 2.0指出了@GET注解对资源方法的定义，使得该方法用于处理GET请求
HEAD，OPTIONS方法和GET方法相似，是安全和幂等的，使用@HEAD,@OPTIONS注解来定义相关资源的方法

PUT 方法

PUT方法幂等性的 即多次插入或者更新同一份数据，在服务端对资源状态所产生的改变是相同的，PUT方法不是安全的，有写动作的方法都不是安全的，因此对于更新操作使用PUT方法，式没有疑问的

DELETE方法

DELETE 方法是幂等的，即多次删除同一份数据，在服务端产生的改变时相同的。DELETE 不是安全性的。JAX-RS 2.0指出了@DELETE注解对资源方法的定义

POST方法

POST方法是一种写操作的HTTP请求，POST方法既不幂等也不安全

二.REST资源定位

在设计REST式的web服务过程中，资源地址的设计是非常严谨的，如果设计不好，不仅REST接口的风格无法统一，是系统的易用性和扩展性降低，也很难使资源准确地被定位。资源地址的设计是面向资源的，资源名称应该是准确描述资源的名称

@QueryParam 注解
查询条件决定了方法的作用域，查询参数组成了查询条件，JAX-RS 2.0定义了@QueryParam注解来定义查询参数
（1）分页查询

@Path("yijings")
    @GET
    @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
    public Yijings getByPaging(@QueryParam("start") final int start, @QueryParam("size") final int size) {
        final Yijings result = new Yijings();
        final List<Link> links = new ArrayList<>();
        final List<Yijing> yijings = new ArrayList<>();
        final UriBuilder ub = uriInfo.getAbsolutePathBuilder().replacePath("query-resource/yijing");
        ArrayList<Yijing> globalList = ParamCache.LIST;
        int listSize = globalList.size();
        final int max = size > listSize ? listSize : size;
        for (int i = 0; i < max; i++) {
            final Yijing yijing = globalList.get(start + i);
            final URI location = ub.clone().queryParam("id", yijing.getSequence()).build();
            final Link link = new Link("detail", location.toASCIIString(), MediaType.APPLICATION_XML);
            links.add(link);
            yijings.add(yijing);
        }
        result.setLinks(links);
        result.setGuas(yijings);
        QueryResource.LOGGER.debug(result);
        return result;
    }

（2）.单项查询

    @Path("yijing")
    @GET
    @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
    public Yijing getByQuery(@QueryParam("id") final int seqId) {
        return ParamCache.find("" + seqId);
    }

@PathParam
JAX-RS 2.0定义了@QueryParam注解来定义路径参数-----每一个参数对应一个子资源

1.@Path 注解
JAX-RS 2.0定义了@Path 注解来定义资源路径，@Path接收一个资源参数，来解析资源路径地址，该参数也可使用动态的方式

    @GET
    @Path("{from:\\d+}-{to:\\d+}")
    @Produces(MediaType.TEXT_PLAIN)
    public String getByCondition(@PathParam("from") final Integer from, @PathParam("to") final Integer to) {
        return "from=" + from + ":to=" + to;
    }

2.正则表达式

    @GET
    @Path("{user: [a-zA-Z][a-zA-Z_0-9]*}")
    @Produces(MediaType.TEXT_PLAIN)
    public String getUserInfo(@PathParam("user") final String user, @DefaultValue("Shen Yang") @QueryParam("hometown") final String hometown) {
        return user + ":" + hometown;
    }

3.路径配合查询
查询参数和路径参数在一个接口中配合使用，可以更快捷的完成资源定位

    @GET
    @Path("{user: [a-zA-Z][a-zA-Z_0-9]*}")
    @Produces(MediaType.TEXT_PLAIN)
    public String getUserInfo(@PathParam("user") final String user, @DefaultValue("Shen Yang") @QueryParam("hometown") final String hometown) {
        return user + ":" + hometown;
    }

以资源地址：/path-resource/Eric/hometown=chengdu,为例，REST容器会将该请求匹配到getUserInfo()方法，其中Eric是路径变量user 的值，chengdu作为查询变量hometown的值

4.路径区间
路径区间是对资源地址更灵活的支持

    @GET
    @Path("{region:.+}/shenyang/{district:\\w+}")
    @Produces(MediaType.TEXT_PLAIN)
    public String getByAddress(@PathParam("region") final List<PathSegment> region, @PathParam("district") final String district) {
        final StringBuilder result = new StringBuilder();
        for (final PathSegment pathSegment : region) {
            result.append(pathSegment.getPath()).append("-");
        }
        result.append("shenyang-").append(district);
        final String r = result.toString();
        PathResource.LOGGER.debug(r);
        return r;
    }

PathSegment 是路径片段，子资源的集合，测试该方法：

public void testRegion() {
        String result;
        final WebTarget pathTarget = target(path).path("Asia").path("China").path("northeast").path("liaoning").path("shenyang").path("huangu");
        result = pathTarget.request().get().readEntity(String.class);
        PathTest.LOGGER.debug(result);
        Assert.assertEquals("Asia-China-northeast-liaoning-shenyang-huangu", result);
    }

5.@MatrixParam 注解

    @GET
    @Path("q2/{condition}")
    @Produces(MediaType.TEXT_PLAIN)
    public String getByCondition4(@PathParam("condition") final PathSegment condition, @MatrixParam("program") final String program,
                                  @MatrixParam("type") final String type) {
        return condition.getPath() + " program=[" + program + "] type=[" + type + "]";
    }

测试该方法：

    @Test
    public void testQ() {
        String result;
        result = target(path).path("q2").path("restful;program=java;type=web").request().get().readEntity(String.class);
        PathTest.LOGGER.debug(result);
        Assert.assertEquals("restful program=[java] type=[web]", result);
    }

@FormParam注解
JAX-RS 2.0定义了@FormParam 注解来定义表单参数，已处理表单请求

@Path("form-resource")
public class FormResource {
    public static final String USER = "user";
    public static final String PW = "password";
    public static final String NPW = "newPassword";
    public static final String VNPW = "verification";

    @POST
    public String newPassword(
            @DefaultValue("feuyeux") @FormParam(FormResource.USER) final String user,
            @Encoded @FormParam(FormResource.PW) final String password,
            @Encoded @FormParam(FormResource.NPW) final String newPassword,
            @FormParam(FormResource.VNPW) final String verification) {
        return user + ":" + password + ":" + newPassword + ":" + verification;
    }
}

@Encoded 表示禁用自动解码

@CookieParam注解
JAX-RS 2.0定义了@CookieParam注解来定义匹配Cookie中的键值对信息

@Path("kuky-resource")
public class CookieResource {
    @GET
    public String getHeaderParams(@CookieParam("longitude") final String longitude,
                                  @CookieParam("latitude") final String latitude,
                                  @CookieParam("population") final double population,
                                  @CookieParam("area") final int area) {
        return longitude + "," + latitude + " population=" + population + ",area=" + area;
    }
}

@Context注解
JAX-RS 2.0定义了@Context注解来解析上下文

@Path("ctx-resource")
public class ContextResource {
    @GET
    @Path("{region:.+}/shenyang/{district:\\w+}")
    @Produces(MediaType.TEXT_PLAIN)
    public String getByAddress(
            @Context final Application application,
            @Context final Request request,
            @Context final javax.ws.rs.ext.Providers provider,
            @Context final UriInfo uriInfo,
            @Context final HttpHeaders headers) {
        final StringBuilder buf = new StringBuilder();
        final String path = uriInfo.getPath();
        buf.append("PATH=").append(path).append("\n");

        final MultivaluedMap<String, String> pathMap = uriInfo.getPathParameters();
        buf.append("PATH_PARAMETERS:\n");
        iterating(buf, pathMap);

        final MultivaluedMap<String, String> queryMap = uriInfo.getQueryParameters();
        buf.append("QUERY_PARAMETERS:\n");
        iterating(buf, queryMap);

        final List<PathSegment> segmentList = uriInfo.getPathSegments();
        buf.append("PATH_SEGMENTS:\n");
        for (final PathSegment pathSegment : segmentList) {
            final MultivaluedMap<String, String> matrix = pathSegment.getMatrixParameters();
            final String segmentPath = pathSegment.getPath();
            buf.append(matrix);
            buf.append(segmentPath);
        }
        buf.append("\nHEAD:\n");
        final MultivaluedMap<String, String> headerMap = headers.getRequestHeaders();
        iterating(buf, headerMap);
        buf.append("COOKIE:\n");
        final Map<String, Cookie> kukyMap = headers.getCookies();
        final Iterator<Entry<String, Cookie>> i = kukyMap.entrySet().iterator();
        while (i.hasNext()) {
            final Entry<String, Cookie> e = i.next();
            final String k = e.getKey();
            buf.append("key=").append(k).append(",value=");
            final Cookie cookie = e.getValue();
            buf.append(cookie.getValue()).append(" ");
            buf.append("\n");
        }
        return buf.toString();
    }

    private void iterating(final StringBuilder buf, final MultivaluedMap<String, String> pathMap) {
        final Iterator<Entry<String, List<String>>> i = pathMap.entrySet().iterator();
        while (i.hasNext()) {
            final Entry<String, List<String>> e = i.next();
            final String k = e.getKey();
            buf.append("key=").append(k).append(",value=");
            final List<String> vList = e.getValue();
            for (final String v : vList) {
                buf.append(v).append(" ");
            }
            buf.append("\n");
        }
    }
}

三.REST传输格式

REST主要以XML和JSON为传输格式

XML格式
JAXP包含了DOM,SAX和StAx 三种解析XML的技术标准
XML 类型是使用比较广泛的数据类型。Jersey对XML类型的数据处理支持Java领域的两大标准，即JAXP(Java API for XML Processing) 和JAXB(Java Architecture for XML Bingding)

JSON 格式
Jersey提供了四种处理Json数据的媒体包分别是：MOXy，JSON-P ，Jackson ，Jettison

四.REST响应处理

1.返回类型

（1）.void
在返回值类型是void的响应中，其响应实体为空，HTTP状态码为204

    @DELETE
    @Path("{s}")
    public void delete(@PathParam("s") final String s) {
        LOGGER.debug(s);
    }

（2）.Response
在返回值为Response的响应中 响应实体为Response类的entity()方法定义的实体类实例

    @POST
    @Path("c")
    public Response postString(final String s) {
        LOGGER.debug(s);
        //Response.noContent().build();
        return Response.ok().entity("char[]:" + s).build();
    }

（3）.GenericEntity

@POST
@Path("b")
public GenericEntity<String> get(final byte[] bs) {
        for (final byte b : bs) {
            LOGGER.debug(b);
        }
        return new GenericEntity<String>("byte[]:" + new String(bs), String.class);
    }

（4）.自定义类型

2.处理异常

HTTP状态码HTTP定义了很多有意义的状态码，你可以在你的API中使用。这些状态码可以帮助API消费者用来路由它们获取到的响应内容。整理了一个你肯定会用到的状态码列表：

• 200 OK - 对成功的GET、PUT、PATCH或DELETE操作进行响应。也可以被用在不创建新资源的POST操作上
• 201 Created - 对创建新资源的POST操作进行响应。应该带着指向新资源地址的Location header
• 204 No Content - 对不会返回响应体的成功请求进行响应（比如DELETE请求）
• 304 Not Modified - HTTP缓存header生效的时候用
• 400 Bad Request - 请求异常，比如请求中的body无法解析
• 401 Unauthorized - 没有进行认证或者认证非法。当API通过浏览器访问的时候，可以用来弹出一个认证对话框
• 403 Forbidden - 当认证成功，但是认证过的用户没有访问资源的权限
• 404 Not Found - 当一个不存在的资源被请求
• 405 Method Not Allowed - 所请求的HTTP方法不允许当前认证用户访问
• 410 Gone - 表示当前请求的资源不再可用。当调用老版本API的时候很有用
• 415 Unsupported Media Type - 如果请求中的内容类型是错误的
• 422 Unprocessable Entity - 用来表示校验错误
• 429 Too Many Requests - 由于请求频次达到上限而被拒绝访问

除了Jersey 提供的标准异常外，我们也可以定义自己的异常：

package com.example.exception;

import javax.ws.rs.WebApplicationException;
import javax.ws.rs.core.Response;

public class Jaxrs2GuideNotFoundException extends WebApplicationException{
    public Jaxrs2GuideNotFoundException() {
        super(Response.Status.NOT_FOUND);
    }

    public Jaxrs2GuideNotFoundException(String message) {
        super(message);
    }
}

ExceptionMapper接口

Jersey 为我们提供了更为通用的异常处理方式，通过实现ExceptionMapper接口并使用@Provider注解将其定义为一个Provider

package com.example.response;

import com.example.exception.Jaxrs2GuideNotFoundException;

import javax.ws.rs.core.Response;
import javax.ws.rs.ext.ExceptionMapper;
import javax.ws.rs.ext.Provider;

@Provider
public class EntityNotFoundMapper implements ExceptionMapper<Jaxrs2GuideNotFoundException> {

    @Override
    public Response toResponse(final Jaxrs2GuideNotFoundException ex) {
        return Response.status(404).entity(ex.getMessage()).type("text/plain").build();
    }
}