# JAVA RESTful WebService实战笔记(一)

PUT方法

PUT方法是一种写操作的HTTP请求,REST使用HTTP的PUT方法更新或添加资源

1、更新资源

REST知识风格,不是技术规范或者标准,所以有些实现REST的细节明确的定义,这对实践而言,不可避免会产生某些误解,比如在创建和更新某个资源的时候,开发者比较迷茫的是何时该用HTTP的PUT方法,何时使用POST方法,为了解决这一问题,我们首先应该知道PUT方法的特性,PUT方法是幂等的,即多次插入或者更新同一份数据,在服务器端对资源状态所产生的改变是相同的,PUT方法是不安全的,有些动作的HTTP方法都不是安全的。我们知道,由于使用同一份数据向服务器请求更新某一资源,得到的结果应该总是相同的,因此对于更新操作,使用PUT是没有疑问的。

2、添加资源

创建操作通常每次得到的结果是不同的,因为服务器端的业务层逻辑通常要求数据的主键字段要么来自于业务平台自增一个逻辑值,要么来自于数据库中的主键自增,因此,相同的数据每一次提交到服务器端,都会为数据添加一个新的主键值,也就是创建一个主键值不同的新资源（如果没有业务或者外键冲突）。所以,创建操作通常应当设计为POST方法的API,唯有一种场景应当使用PUT方法来设计API,即客户端在发起创建请求时候,在同一份数据中总可以提供唯一的主键值,服务器不会对其进行修改,这样的创建请求确保了幂等性,不应该在使用PUT请求

---

资源地址设计

资源地址的设计对整个REST式的Web服务至关重要,设计系统的可用性和可扩展性等诸多方面的表现

1、资源路径概览

资源地址的路径变量使用来表达逻辑上的层次结构的,资源和子资源的高兴事是自左向右、斜杠分隔的名词。他们的关系可以是从整体到局部,比如学校到班级,城市到乡村.可以是从一般到具体,比如一个生物的“门”、“纲”、“目”、“科”等。。。的资源路径,资源地址具体的可以分为5个部分,以sehema://host:port/path?queryString为例,如下表格

元素	描述
sehema	协议名称,通常是HTTP或者HTTPS
host	(DNS)主机名称或者IP地址
port	服务端口
path	资源地址,使用"/"符号来分隔逻辑上的层次结构
?	用来分隔资源地址和查询字符串符号
queryString	查询字符串,方法作用域信息 使用“&”符号来分隔查询条件 使用都好分隔有次序的作用域信息 使用分号分隔无次序的作用域信息

一个典型的URI如上表所示,包括协议名称、主机名称、服务端口、资源地址和查询字符串5个部分,其中资源地址部分,根据具体部署的不同或有差别 http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/book?id=1

• requestURL
  • http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/book?id=1
• ContextPath
  • simple-service-webapp-spring-jpa-jquery
• ServletPath
  • webapi
• PahtInfo
  • books/book

通常使用ContextPath、ServletPaht和PathInfo来细分资源地址。

• ContextPath: 上下文名称,通常和部署服务器的配置或者REST服务的web.xml配置有关。
• ServletPath: 是Servlet的名称,与REST服务中定义的@ApplicationPath注解或者web.xml的而配置有关

JAX-RS2定义了@Path注解来定义资源地址

• PathInfo：资源路径信息,与资源类、子类及勒种的方法蒂尼的@Path注解有关

2、资源地址和作用域

在路径变量里面可以使用标点符号以辅助增强逻辑清晰性。如下表所示

功能	资源地址
添加/创建	POST/books PUT/books/{id}
删除	DELETE/books/{id}
修改/更新	PUT/books/{id}
查询全部	GET/books HTTP1.1
主键查询	GET/books/{id} HTTP1.1 GET /books?id=12334
分页作用域查询	GET/books/{id} HTTP1.1 GET /books/01,2002-12,2014 GET /books/restful;program=java;type=web GET /books?limit=100&sort=bookname

• 问号(?) 是用来分隔资源路径地址和查询字符串,与符号(&)是用来分隔查询条件的参数,示例代码如下

GET /books?start=0&size=19
复制代码

代码解释：开始行参数为0,查询的条目是19,及从第0行开始查询去19条数据

• 逗号(,)是用来分隔有次序的作用域信息,需要注意的是逗号分隔符的逻辑上的顺序信息,这种顺序可以是约定俗成的,比如先写经度然后纬度;也可以是系统约定的,比如年、月、日、时等。 举例来说：按时间区域查询图书,日期信息在资源地址中是采用月、年顺序,代码如下

GET /books/01,2002-12,2014
复制代码

代码解释:查询2002年1月到2014年12月的这个时间段的图书,这个例子中还使用到了连字符(-),有时候也可以使用下划线(_)来做逻辑上的辅助分隔。

• 分号(;)是用来分隔无次序的作用域信息,通常这些信息是逻辑上并列存在的,比如并列的查询条件,示例代码如下

GET /books/restful;program=java;type=web
复制代码

代码解释:查询满足图书内容为restful的,石宏的编程语言是java的讲述的类型是web的图书列表。

---