笔记：REST API 设计

Evernote Export body, td { font-family: 微软雅黑 Light; font-size: 14pt; }

REST API 设计

创建时间：	04/07/2015 Saturday 15:50
更新时间：	04/07/2015 Saturday 17:48
作者：	liker.xu

• 掌握JAX-RS 2.0标准
• REST统一接口
• 资源定位
• 请求处理过程传输数据的格式
• 响应信息
• 内容协商的支持
• 资源地址信息的支持

---

• HTTP通用方法[GET+PUT+POST+DELETE+OPTION]
• • 安全性：对接口访问不会造成服务器端资源状态变化
  • 幂等性：对统一接口多次访问得到的状态表述是相同

• • @GET(只读)：幂等+安全
  • • 避免设计不良的API（不存在写操作）
    • 资源方法命名（单复数资源名词）
    • 接口层方法名称上的注解？注解写在接口方法上，实现类无需再定义，测试时注册实现类
  • @HEAD：安全+幂等
  • • 返回值不包括HTTP实体
  • @OPTIONS：安全+幂等
  • • 用于读取资源所支持（Allow）的所有HTTP方法
  • @PUT（写操作）：更新或添加资源：幂等，多次插入或者更新同一份数据，不安全
• • • 更新操作
  • • @Produces（服务器要生产的媒体类型-输出） target（“book”）.request(acceptMediaType)
    • @Consumes（服务器要消费的媒体类型-输入）Entity.entity(newBook,contentMediaTYPE)
    • javax.ws.rs.core.MediaType
• @POST：既不幂等也不安全
• • 创建资源（主键设置在服务器端）
  • REST-post（a）
  • RPC-post（p）：需要先解析出执行方法
• @DELETE：幂等
• • 返回值void
  • HTTP状态码：204
• WebDEV拓展方法（不遵从ROA（面向资源架构）的拓展接口）P77

---

• REST资源定位（URI及其参数）[可用性+可维护性+可拓展性]
• • 一个URI对映一个资源，但一个资源可以对映多个URI
• 资源路径概览：scheme://host:port/path?queryString1&queryString2
• • GET /books?start=0&size=10
  • 有次序（,）：GET /books/01,2002-12,2004
  • 无次序（;）：GET /books/restful;program=java;type=web
• 查询参数>>查询条件>>查询作用域
• • 分页查询列表数据：/query-resource/books?start=24&size=10
  • • public Books getBooks(@QueryParam(“start”) final int start,@QueryParam(“size”) final int size)
  • 排序并分页查询列表数据：/queryresource/sorted-books/limit=5%sort=pronouce
  • • public Books getBooks(@QueryParam(“limit”) final int limit,@QueryParam(“sort) final String name)
  • 查询单项数据：/query-resource/books?id=8
• @Path（“{参数名称1：正则表达式}-{参数名称2：正则表达式}”）
• public String getByCondition（@PathParam（“参数名称1”） final Integer a，@PathParam（“参数名称2”） final Integer b）
• • /path-resource/01,2012-12,2014
  • @Path(“{beginMonth:\d+},{beginYear:\d+}-{endMonth:\d+},{endYear:\d+}”)
• @Path与@PathParam配合使用
• • @Path（”user：[a-zA-Z][a-zA-Z_0-9]*“）
  • @Produces(MediaType.TEXT_PLAIN)
  • public StringgetUserInfo(@PathParam(“user”) final String user,@DefaultValue(“Shne Yang”@QueryParam(“hometown” final String hometown)))
• 路径区间PathSegment（使资源类的一个方法支持更广泛的资源地址的请求）
• • @Path（”{region：.+}/shenyang/{district:\w+}“）
  • 查询参数动态给定：将从哪胡说条件作为一个整体解析P85
  • • PathSegment.getMatrixParameters();
    • @Path{“q/{condition}”}
    • public String getSomething(@PathParam final PathSegment condition,@MatrixParam(“program”) final String program,@MatrixSegment(“type”) final String type)
    • @MatrixParam表达了可接受的参数名称与类型
• @FormParam：定义表单参数
• • Content-Type:application/x-www-form-urlencoed
  • @Path(“form-resource”)
  • public class FromResource(@DefaultValue(“liker”) @FormResource.USER final String user,@Encoded @FormParam(FormResourcep.PW) final String password,@Encoded @FormParam(FormResource.NPW) final String newpassword,@Enocded @FormParam(FormResource.VNPW) final String vertifictation) { ……
  • }
  • @Encode 禁用自动解码；@@DefaultValue 为客户端没有提供的参数值提供默认值
• @BeanParam：自定义参数组合（用简洁的参数设计完成接口设计）
• • public String getAddress（@BeanParam MyClass param）{……}
  • public class MyClass(){
  • • @HeaderParam(“accept”)
    • private String acceptParam;
    • @PathParam(“region”)
    • private String regionParam;
    • @PathParam(“district”)
    • private String stationParam;
    • @QueryParam(“station”)
    • private String stationParam;
    • @QueryParam(“vehicle”)
    • private String vehicleParam;
    • …….
  • }//定义了一系列REST方法会用到的参数类型
• @CookieParam：用以匹配Cookie中的键值对信息
• • public String getHeaderParams（@CookieParam（”longitude“）final String logitude，@CookieParam（”latitude“）final String latitude）{…..}
• @Context：解析上下文参数
• • public String getSomething（@Context final Application application,@Context final Request request,@Context final Providers providers）{…}
  • @Context final UriInfo uriInfo：路径信息上下文
  • @Context final HttpHeaders headers；