Rest Ful 设计规范

目录

什么是Rest？

设计原则

规范统一的接口

HTTP请求规范

 参数命名规范

状态码

 统一返回数据格式

总结

---

什么是Rest？

REST与技术无关，它代表的是一种软件架构风格，REST它是 Representational State Transfer的简称，中文的含义是: "表征状态转移" 或 "表现层状态转化"。它是基于HTTP、URI、XML、JSON等标准和协议，支持轻量级、跨平台、跨语言的架构设计。

设计原则

1. 每一个URI代表一种资源;
2. 同一种资源有多种表现形式(xml/json);
3. 所有的操作都是无状态的。
4. 规范统一接口。
5. 返回一致的数据格式。
6. 可缓存(客户端可以缓存响应的内容)。

符合上述Rest原则的架构方式被称作为 RestFul 规范。

http请求本身是无状态的，它是基于 client-server 架构的，客户端向服务器端发的每一次请求都必须带有充分的信息能够让服务器端识别到，请求的一些信息通常会包含在URL的查询参数中或header中，服务器端能够根据请求的各种参数, 不需要保存客户端的状态, 直接将数据返回给客户端。无状态的优点是：可以大大提高服务器端的健状性和可扩展性。

规范统一的接口

Rest接口约束定义为: 资源识别；请求动作；响应信息; 它表示通过uri表示出要操作的资源，通过请求动作(http method)标识要执行的操作，通过返回的状态码来表示这次请求的执行结果。

传统URL请求格式：

url	请求方式	作用
http://127.0.0.1/api/getUser	GET	获取用户数据
http://127.0.0.1/api/saveUser	POST	新增用户
http://127.0.0.1/api/updateUser	POST	修改用户信息
http://127.0.0.1/api/delUser	GET/POST	删除用户信息

RestFul请求格式:

url	请求方式	作用
http://127.0.0.1/api/user	GET	获取用户数据
http://127.0.0.1/api/user	POST	新增用户
http://127.0.0.1/api/user	PUT	修改用户信息
http://127.0.0.1/api/user	DELETE	删除用户信息

如上可以看到，增删改成都是使用同一个api接口，只是请求的方式 GET(查询)、POST(新增)、DELETE(删除)、PUT(更新)来代表的是增删改查操作的方式。然后开发获取到该请求的header头部信息，就可以知道是什么方式来请求数据的了。

HTTP请求规范

GET (SELECT): 查询；从服务器取出资源.
POST(CREATE): 新增; 在服务器上新建一个资源。
PUT(UPDATE): 更新; 在服务器上更新资源(客户端提供改变后的完整资源)。
PATCH(UPDATE): 更新；在服务器上更新部分资源(客户端提供改变的属性)。
DELETE(DELETE): 删除; 从服务器上删除资源。

 参数命名规范

参数推荐采用如下方式：

//其中“1”是传入的id
http://127.0.0.1/api/user/1

状态码

客户端的每一次请求, 服务器端必须给出回应，回应一般包括HTTP状态码和数据两部分。

 统一返回数据格式

RestFul规范中的请求应该返回统一的数据格式。对于返回的数据，一般会包含如下字段:

code：状态码

status: 文本, 如：'success'(成功), 'fail'(失败), 'error'(异常) 

当status的值为 'fail' 或 'error'时，需要添加 message 字段，用于显示错误信息。

data: 当请求成功的时候, 返回的数据信息。但是当状态值为 'fail' 或 'error' 时，data仅仅包含错误原因或异常信息等。

返回成功的JSON格式如下：

{
    "code": 200,
    "status": "success",
    "data": [{
        "username": "wsljy",
        "password": "123456"
    }]
}

返回失败的JSON格式如下：

{
    "code": 404,
    "status": "error",
    "message": '没有找到其资源',
    "data": null
}

总结

RestFul风格可以设定其请求方式，做到相同的地址访问不同的方法，请求的方式有5种为：GET、POST、PUL、PATCH、DELETE，返回的结果一般包括：状态码、文本和相应数据，RestFul风格可以过滤资源使得结构清晰，配合请求方式后会增加可读性，隐藏参数使它更加安全。