要定義一個嚴謹?shù)腞EST統(tǒng)一接口，就需要真正理解HTTP方法的安全性和冪等性骗灶。安全性代表安全的REST接口惨恭，是指外系統(tǒng)對該接口的訪問，不會使服務(wù)器端的資源的狀態(tài)發(fā)生改變矿卑，冪等性是指外系統(tǒng)對同一REST接口的多次訪問喉恋，得到的資源狀態(tài)是相同的。

一.HTTP 方法

GET 方法

HTTP的GET方法用于讀取資源母廷。GET方法是冪等性的轻黑，因為讀取同一個資源，總是得到相同的數(shù)據(jù)琴昆。GET方法也是安全性的氓鄙，因為讀取資源不會對其狀態(tài)做改動。JAX-RS 2.0指出了@GET注解對資源方法的定義业舍，使得該方法用于處理GET請求
HEAD抖拦，OPTIONS方法和GET方法相似，是安全和冪等的舷暮，使用@HEAD,@OPTIONS注解來定義相關(guān)資源的方法

PUT 方法

PUT方法冪等性的 即多次插入或者更新同一份數(shù)據(jù)态罪，在服務(wù)端對資源狀態(tài)所產(chǎn)生的改變是相同的，PUT方法不是安全的下面，有寫動作的方法都不是安全的复颈，因此對于更新操作使用PUT方法，式?jīng)]有疑問的

DELETE方法

DELETE 方法是冪等的沥割，即多次刪除同一份數(shù)據(jù)耗啦，在服務(wù)端產(chǎn)生的改變時相同的。DELETE 不是安全性的机杜。JAX-RS 2.0指出了@DELETE注解對資源方法的定義

POST方法

POST方法是一種寫操作的HTTP請求帜讲，POST方法既不冪等也不安全

二.REST資源定位

在設(shè)計REST式的web服務(wù)過程中，資源地址的設(shè)計是非常嚴謹?shù)慕忿郑绻O(shè)計不好似将，不僅REST接口的風(fēng)格無法統(tǒng)一获黔，是系統(tǒng)的易用性和擴展性降低，也很難使資源準(zhǔn)確地被定位玩郊。資源地址的設(shè)計是面向資源的肢执，資源名稱應(yīng)該是準(zhǔn)確描述資源的名稱

@QueryParam 注解
查詢條件決定了方法的作用域，查詢參數(shù)組成了查詢條件译红，JAX-RS 2.0定義了@QueryParam注解來定義查詢參數(shù)
（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注解來定義路徑參數(shù)-----每一個參數(shù)對應(yīng)一個子資源

1.@Path 注解
JAX-RS 2.0定義了@Path 注解來定義資源路徑预茄，@Path接收一個資源參數(shù)，來解析資源路徑地址侦厚，該參數(shù)也可使用動態(tài)的方式

    @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.路徑配合查詢
查詢參數(shù)和路徑參數(shù)在一個接口中配合使用耻陕，可以更快捷的完成資源定位

    @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.路徑區(qū)間
路徑區(qū)間是對資源地址更靈活的支持

    @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 注解來定義表單參數(shù)召庞，已處理表單請求

@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的技術(shù)標(biāo)準(zhǔn)
XML 類型是使用比較廣泛的數(shù)據(jù)類型。Jersey對XML類型的數(shù)據(jù)處理支持Java領(lǐng)域的兩大標(biāo)準(zhǔn)来破，即JAXP(Java API for XML Processing) 和JAXB(Java Architecture for XML Bingding)

JSON 格式
Jersey提供了四種處理Json數(shù)據(jù)的媒體包分別是：MOXy篮灼，JSON-P ，Jackson 徘禁，Jettison

四.REST響應(yīng)處理

1.返回類型

（1）.void
在返回值類型是void的響應(yīng)中诅诱，其響應(yīng)實體為空，HTTP狀態(tài)碼為204

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

（2）.Response
在返回值為Response的響應(yīng)中 響應(yīng)實體為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狀態(tài)碼HTTP定義了很多有意義的狀態(tài)碼送朱，你可以在你的API中使用娘荡。這些狀態(tài)碼可以幫助API消費者用來路由它們獲取到的響應(yīng)內(nèi)容。整理了一個你肯定會用到的狀態(tài)碼列表：

• 200 OK - 對成功的GET驶沼、PUT炮沐、PATCH或DELETE操作進行響應(yīng)。也可以被用在不創(chuàng)建新資源的POST操作上
• 201 Created - 對創(chuàng)建新資源的POST操作進行響應(yīng)回怜。應(yīng)該帶著指向新資源地址的Location header
• 204 No Content - 對不會返回響應(yīng)體的成功請求進行響應(yīng)（比如DELETE請求）
• 304 Not Modified - HTTP緩存header生效的時候用
• 400 Bad Request - 請求異常央拖，比如請求中的body無法解析
• 401 Unauthorized - 沒有進行認證或者認證非法。當(dāng)API通過瀏覽器訪問的時候鹉戚，可以用來彈出一個認證對話框
• 403 Forbidden - 當(dāng)認證成功，但是認證過的用戶沒有訪問資源的權(quán)限
• 404 Not Found - 當(dāng)一個不存在的資源被請求
• 405 Method Not Allowed - 所請求的HTTP方法不允許當(dāng)前認證用戶訪問
• 410 Gone - 表示當(dāng)前請求的資源不再可用专控。當(dāng)調(diào)用老版本API的時候很有用
• 415 Unsupported Media Type - 如果請求中的內(nèi)容類型是錯誤的
• 422 Unprocessable Entity - 用來表示校驗錯誤
• 429 Too Many Requests - 由于請求頻次達到上限而被拒絕訪問

除了Jersey 提供的標(biāo)準(zhǔn)異常外抹凳，我們也可以定義自己的異常：

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 為我們提供了更為通用的異常處理方式，通過實現(xiàn)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();
    }
}