RESTFul API设计

作者: zlb | 来源:发表于2017-10-15 21:35 被阅读134次

RESTful API 使用解读
HttpMessageConverter是这样转换数据的
python(12)实践Django-Restful API
RESTful API 最佳实践
SSM开发大众点评
【Spring Boot】构建RESTful API——（二）
什么是Restful API
RESTful api接口安全优雅设计
RESTful API 设计指南
Flask使用合集

要定义一个严谨的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();
    }
}

RESTful API 使用解读
理解 RESTFul 架构 RESTful API 设计指南
HttpMessageConverter是这样转换数据的
Java Web 人员经常要设计 RESTful API（如何设计好的RESTful API），通过 json 数...
python(12)实践Django-Restful API
关于Restful API，可阅读理解RESTful架构和RESTful API 设计指南。在Django中要实...
RESTful API 最佳实践
RESTful API 介绍 Github API 是设计优良的一套 RESTful API，业内知名度很高，以下...
SSM开发大众点评
HTTP API和RESTFul API RESTFul API 这一种设计风格依据情况，灵活处理前端介绍前...
【Spring Boot】构建RESTful API——（二）
一、RESTful API设计规范参考知乎上的《RESTful API最佳实践》一文，总结的RESTful AP...
什么是Restful API
Restful API与传统API设计区别： 1、不使用url参数：传统API设计：/api/list?pageI...
RESTful api接口安全优雅设计
RESTful api接口安全优雅设计 ...
RESTful API 设计指南
阮一峰：RESTful API 设计指南
Flask使用合集
使用 Python 和 Flask 设计 RESTful API