RESTful

1.RESTful

REST是Roy Thomas Fielding博士在2000年提出,Representational State Transfer的缩写.

表象化状态转变或者表述性状态转移,REST是Web服务的一种架构风格,使用HTTP,URI等广泛流行的标准和协议,轻量级,跨平台,跨语言的架构设计.

REST是一种设计风格.它不是一种标准,也不是一种软件,而是一种思想.

REST通常基于使用HTTP,URI和XML,JSON以及HTML这些现有的广泛流行的协议和标准.

1.1 RESTful

RESTful对应的中文是REST式的.

RESTful Web Service是一种常见的REST的应用,是遵守了REST风格的Web服务.

REST式的Web服务式一种ROA(面向资源的架构)

1.2 REST架构的主要原则

网络上的所有事物都可以被抽象为资源(Resource)

每个资源都有一个唯一的资源标识符(Resource Identifier)

同一资源具有多种表现形式(xml,json等)

对资源的各种操作不会改变资源标识符

所有的操作都是无状态的(Stateless)

符合REST原则的架构方式即可称为RESTful

1.3 正确理解 访问请求、URI、URL、请求参数 四者的区别

一个完整的请求路径：http://www.test.com/user/03235267/view?username=zhangsan&age=20

请求URL （requestURL）= http://www.test.com/user/03235267/view

请求URI （requestURI）= /user/03235267/view

请求参数（queryString）= username=zhangsan&age=20

URL?请求参数=请求路径

URL：(Uniform/Universal Resource Locator 的缩写，统一资源定位符)。

URI：(Uniform Resource Identifier 的缩写，统一资源标识符)（代表一种标准）。

1）Java类库里有两个对应的类java.net.URL和java.net.URI，官方的定义分别如下：

（URL）A Uniform Resource Locator thatidentifies the location of an Internet resource as specified by RFC 1738.（统一资源定位符用于标示网络资源的位置）

（URI，统一资源标识符）A Uniform Resource Identifier that identifies an abstract or physical resource, as specified by RFC 2396.（统一资源标识符用于标示一个抽象或者物理资源）

2）也就是说URI是以一种抽象的，高层次概念定义统一资源标识，而URL则是具体的资源标识的方式。URL是一种URI。

3）URL，URI具体定义方式（来自android官方文档）

URL的格式一般由下列三部分组成:

第一部分是协议(或称为服务方式);

第二部分是存有该资源的主机IP地址(有时也包括端口号);

第三部分是主机资源的具体地址。

URI一般由三部分组成:

访问资源的命名机制。

存放资源的主机名。

资源自身的名称，由路径表示。

4）在Java的URI中，一个URI实例可以代表绝对的，也可以是相对的，只要它符合URI的语法规则。而URL类则不仅符合语义，还包含了定位该资源的信息，因此它不能是相对的，schema（protocol）必须被指定。

1.4 无状态性

无状态性使得客户端和服务器端不必保存对方的详细信息,服务器只需要处理当前Request,而不必了解前面Request的历史.从而可以更容易地释放资源,让服务器充分利用Pool技术来提高稳定性和性能.

1.5 资源操作

http://example.com/users/

　　--GET:获取一个资源

　　--POST:创建一个新的资源

　　--PUT:修改一个资源的状态

　　--DELETE:删除一个资源

资源展现:

--XML

--JSON

 

之前的操作：

http://127.0.0.1/user/query/1  GET  根据用户id查询用户数据

http://127.0.0.1/user/save      POST 新增用户

http://127.0.0.1/user/update  POST 修改用户信息

http://127.0.0.1/user/delete   GET/POST 删除用户信息

RESTful用法：

http://127.0.0.1/user/1  GET  根据用户id查询用户数据

http://127.0.0.1/user     POST 新增用户

http://127.0.0.1/user     PUT 修改用户信息

http://127.0.0.1/user     DELETE 删除用户信息

1.6 REST

1.REST接口设计

URL的组成

　　--网络协议(http,https)

　　--服务器地址

　　--接口名称

　　--?参数列表

URL定义限定

　　--不要使用大写字母

　　--使用中线-代替下划线_

　　--参数列表应该被encode过

2.响应设计

Content body仅仅用来传输数据,数据要做到拿来就可用的原则,不需要"拆箱"的过程,用来描述数据或者请求的元数据放Header中,例如X-Result-Fields. 

3.响应示例

错误的做法:

{
　　"status":200,
　　"data":{
　　　　"trade_id":1234,
　　　　"trade_name":"hello"
　　}
}

正确的做法:

    Response:Headers;
　　    "status":200,
     Response Body:       
    {
　　　　"trade_id":1234,
　　　　"trade_name":"hello"
　　}        

4.指定响应的属性字段

无状态服务器应该允许客户端对数据按需提取.在请求头使用X-Result-Fields指定数据返回的字段集合.

例如:trade有trade_id,trade_name,created_at三个属性,客户端只需其中的trade_id,trade_name属性:

Request Header

　　X-Result-Fields:trade_id,trade_name

 

2.HTTP响应状态码

1xx（临时响应） 
表示临时响应并需要请求者继续执行操作的状态代码。


代码   说明 
100   （继续） 请求者应当继续提出请求。 服务器返回此代码表示已收到请求的第一部分，正在等待其余部分。  
101   （切换协议） 请求者已要求服务器切换协议，服务器已确认并准备切换。


2xx （成功） 
表示成功处理了请求的状态代码。


代码   说明 
200   （成功）  服务器已成功处理了请求。 通常，这表示服务器提供了请求的网页。 
201   （已创建）  请求成功并且服务器创建了新的资源。 
202   （已接受）  服务器已接受请求，但尚未处理。 
203   （非授权信息）  服务器已成功处理了请求，但返回的信息可能来自另一来源。 
204   （无内容）  服务器成功处理了请求，但没有返回任何内容。 
205   （重置内容） 服务器成功处理了请求，但没有返回任何内容。 
206   （部分内容）  服务器成功处理了部分 GET 请求。


3xx （重定向） 
表示要完成请求，需要进一步操作。 通常，这些状态代码用来重定向。


代码   说明 
300   （多种选择）  针对请求，服务器可执行多种操作。 服务器可根据请求者 (user agent) 选择一项操作，或提供操作列表供请求者选择。 
301   （永久移动）  请求的网页已永久移动到新位置。 服务器返回此响应（对 GET 或 HEAD 请求的响应）时，会自动将请求者转到新位置。 
302   （临时移动）  服务器目前从不同位置的网页响应请求，但请求者应继续使用原有位置来进行以后的请求。 
303   （查看其他位置） 请求者应当对不同的位置使用单独的 GET 请求来检索响应时，服务器返回此代码。 
304   （未修改） 自从上次请求后，请求的网页未修改过。 服务器返回此响应时，不会返回网页内容。 
305   （使用代理） 请求者只能使用代理访问请求的网页。 如果服务器返回此响应，还表示请求者应使用代理。 
307   （临时重定向）  服务器目前从不同位置的网页响应请求，但请求者应继续使用原有位置来进行以后的请求。


4xx（请求错误） 
这些状态代码表示请求可能出错，妨碍了服务器的处理。


代码   说明 
400   （错误请求） 服务器不理解请求的语法。 
401   （未授权） 请求要求身份验证。 对于需要登录的网页，服务器可能返回此响应。 
403   （禁止） 服务器拒绝请求。 
404   （未找到） 服务器找不到请求的网页。 
405   （方法禁用） 禁用请求中指定的方法。 
406   （不接受） 无法使用请求的内容特性响应请求的网页。 
407   （需要代理授权） 此状态代码与 401（未授权）类似，但指定请求者应当授权使用代理。 
408   （请求超时）  服务器等候请求时发生超时。 
409   （冲突）  服务器在完成请求时发生冲突。 服务器必须在响应中包含有关冲突的信息。 
410   （已删除）  如果请求的资源已永久删除，服务器就会返回此响应。 
411   （需要有效长度） 服务器不接受不含有效内容长度标头字段的请求。 
412   （未满足前提条件） 服务器未满足请求者在请求中设置的其中一个前提条件。 
413   （请求实体过大） 服务器无法处理请求，因为请求实体过大，超出服务器的处理能力。 
414   （请求的 URI 过长） 请求的 URI（通常为网址）过长，服务器无法处理。 
415   （不支持的媒体类型） 请求的格式不受请求页面的支持。 
416   （请求范围不符合要求） 如果页面无法提供请求的范围，则服务器会返回此状态代码。 
417   （未满足期望值） 服务器未满足”期望”请求标头字段的要求。


5xx（服务器错误） 
这些状态代码表示服务器在尝试处理请求时发生内部错误。 这些错误可能是服务器本身的错误，而不是请求出错。


代码   说明 
500   （服务器内部错误）  服务器遇到错误，无法完成请求。 
501   （尚未实施） 服务器不具备完成请求的功能。 例如，服务器无法识别请求方法时可能会返回此代码。 
502   （错误网关） 服务器作为网关或代理，从上游服务器收到无效响应。 
503   （服务不可用） 服务器目前无法使用（由于超载或停机维护）。 通常，这只是暂时状态。 
504   （网关超时）  服务器作为网关或代理，但是没有及时从上游服务器收到请求。 
505   （HTTP 版本不受支持） 服务器不支持请求中所用的 HTTP 协议版本。

 

RFC 6585 最近刚刚发布，该文档描述了 4 个新的 HTTP 状态码。

428 Precondition Required (要求先决条件)

429 Too Many Requests (太多请求)

431 Request Header Fields Too Large (请求头字段太大)

511 Network Authentication Required (要求网络认证)

(https://blog.csdn.net/bcbobo21cn/article/details/51029300)

3.SpringMVC实现RESTful服务

SpringMVC原生态的支持了REST风格的架构设计.所涉及注解@RequestMapping,@PathVariable,@ResponseBody...

1.查询资源

在NewUserController中创建根据uid查询用户的方法

在UserService中编写findUserById方法： 

在UserServiceImpl中实现findUserById方法：

@Override
    public User findUserById(Integer uid) {
        return userMapper.selectByPrimaryKey(uid);
    }

测试：

2.新增资源

在NewUserController中编写保存用户的方法：

在UserService中编写保存用户的方法： 

在UserServiceImpl中实现saveUser方法：

@Override
    public Boolean saveUser(User user) {
        user.setStatus("N");
        user.setCode(UuidUtil.getUuid());
        return userMapper.insert(user) > 0;
    }

测试：

3.更新资源

在NewUserController中编写更新用户的方法：

在UserService中编写更新用户的方法：

在UserServiceImpl中实现updateUser方法：

@Override
    public Boolean updateUser(User user) {
        return userMapper.updateByPrimaryKeySelective(user) > 0;
    }

测试：

默认情况下，PUT请求是无法提交表单数据的，需要在web.xml中添加过滤器解决：

<!-- 解决PUT请求无法提交表单数据的问题 -->
    <filter>
        <filter-name>HttpMethodFilter</filter-name>
        <filter-class>org.springframework.web.filter.HttpPutFormContentFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>HttpMethodFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

4.删除资源

在NewUserController中编写根据uid删除用户的方法：

@Controller
@RequestMapping("rest/user")
public class NewUserController {
    
    @Autowired
    private UserService userService;
    
    /**
     * 根据uid查询用户对象
     * @param uid
     * @return
     */
    @GetMapping("{uid}")
    public ResponseEntity<User> findUserById(@PathVariable("uid")Integer uid){
        try {
            if(uid == null || uid <= 0){
                //参数列表错误：400
                return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(null);
            }
            User user = userService.findUserById(uid);
            if(user == null){
                //资源找不到：404
                return ResponseEntity.status(HttpStatus.NOT_FOUND).body(null);
            }
            //查询成功：200
//            return ResponseEntity.status(HttpStatus.OK).body(user);
            return ResponseEntity.ok(user);
        } catch (Exception e) {
            e.printStackTrace();
        }
        //服务器错误：500
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
    }
    
    /**
     * 保存用户
     * @param user
     * @return
     */
    @PostMapping
    public ResponseEntity<Void> saveUser(User user){
        try {
            if(StringUtils.isEmpty(user.getUsername()) || StringUtils.isEmpty(user.getPassword())){
                //参数列表错误：400
                return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
            }
            Boolean flag = userService.saveUser(user);
            if(flag){
                //保存成功：201
                return ResponseEntity.status(HttpStatus.CREATED).build();
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
        //服务器错误：500
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
    }
    
    /**
     * 更新用户
     * @param user
     * @return
     */
    @PutMapping
    public ResponseEntity<Void> updateUser(User user){
        try {
            if(user.getUid() == null || user.getUid() <= 0){
                //参数列表错误：400
                return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
            }
            Boolean flag = userService.updateUser(user);
            if(flag){
                //更新成功：204
                return ResponseEntity.status(HttpStatus.NO_CONTENT).build();
            }else{
                //资源找不到：404
                return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
        //服务器错误：500
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
    }
    
    /**
     * 根据uid删除用户
     * @param uid
     * @return
     */
    @DeleteMapping
    public ResponseEntity<Void> deleteUser(@RequestParam("uid")Integer uid){
        try {
            if(uid == null || uid <= 0){
                //参数列表错误：400
                return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
            }
            Boolean flag = userService.deleteUser(uid);
            if(flag){
                //删除成功：204
                return ResponseEntity.status(HttpStatus.NO_CONTENT).build();
            }else{
                //资源找不到：404
                return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
        //服务器错误：500
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
    }
    
}

在UserService中编写根据uid删除用户的方法：

public interface UserService {

    /**
     * 用户注册
     * @param user
     * @return
     * @throws Exception 
     */
    boolean register(User user) throws Exception;

    /**
     * 用户激活
     * @param code
     * @return
     */
    boolean active(String code);

    /**
     * 用户登陆
     * @param username
     * @param password
     * @return
     * @throws Exception 
     */
    User login(String username, String password) throws Exception;

    /**
     * 根据uid查询用户
     * @param id
     * @return
     */
    User findUserById(Integer uid);

    /**
     * 保存用户
     * @param user
     * @return
     */
    Boolean saveUser(User user);

    /**
     * 更新用户
     * @param user
     * @return
     */
    Boolean updateUser(User user);

    /**
     * 删除用户
     * @param uid
     * @return
     */
    Boolean deleteUser(Integer uid);

}

在UserServiceImpl中实现deleteUser方法：

@Override
    public Boolean deleteUser(Integer uid) {
        return userMapper.deleteByPrimaryKey(uid) > 0;
    }

测试：

 

 

需要在web.xml中添加过滤器解决DELETE请求无法提交表单数据的问题：

<!-- 将POST请求转化为PUT或DELETE请求，要用_method参数来指定真正的请求方式-->
    <filter>
        <filter-name>HiddenHttpMethodFilter</filter-name>
        <filter-class>org.springframework.web.filter.HiddenHttpMethodFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>HiddenHttpMethodFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

再次测试，需要在请求中添加_method参数，指定请求方式为DELETE请求：