众包后台管理 RESTful 实践 V1.0.0

写在最前面

不是绝对，需在实践中，不断完善，进化。

目标：看到URL即可知道是什么资源，看到method 即可知道要干什么操作，看到status 即可知道结果。

RESTful 的核心思想就是，客户端发出的数据操作指令都是"动作 + 资源"的结构。比如，GET /tasks这个命令，GET是动作，/tasks 是资源(使用复数形式)。

动词通常就是五种 HTTP 方法，对应 CRUD 操作。

以工单查询为例

第一种方式
查询参数比较多，个人建议，也可以使用POST的方式。将众多查询条件放到body里面。可以特殊处理POST，/tasks/search

POST /tasks HTTP/1.1
Host: abc.com
Content-Type: application/json
{
   "carId": ""
}

第二种方式
完全遵循REST 只要是获取数据都用GET方式。

第一种方式

GET /tasks?taskNo=JYGdsdfsdflskdjfl HTTP/1.1
Host: abc.com
Content-Type: application/json

第二种方式

GET /tasks/JYGddsfsfsdfsdf HTTP/1.1
Host: abc.com
Content-Type: application/json

POST /tasks HTTP/1.1
Host: abc.com
Content-Type: application/json
{
"taskNo":"lklksdfjlskdfjlskdf",
"plateNum":"川A12345"
}

PUT /tasks HTTP/1.1
Host: carserviceexport.shouqiev.com
Content-Type: application/json
{
"taskNo":"lklksdfjlskdfjlskdf",
"plateNum":"川A12345"
}

第一种方式

DELETE/tasks?taskNo=JYGdsdfsdflskdjfl HTTP/1.1
Host: abc.com
Content-Type: application/json

第二种方式

DELETE /tasks/JYGddsfsfsdfsdf HTTP/1.1
Host: abc.com
Content-Type: application/json

GET /users/123123123/tasks HTTP/1.1
Host: carserviceexport.shouqiev.com
Content-Type: application/json

比如运维操作

预约对于客户端来说，是创建运维记录。
URL定义为：/users/123123123/works
Request Method：为POST

取车对于客户端来说，是对运维记录的修改。
URL定义为：/users/123123123/works
Request Method：为PUT

结束运维对于客户端来说，是对运维记录的修改。
URL定义为：/users/123123123/works
Request Method：为PUT

上面取车，和结束运维都是对资源的修改，但是业务逻辑极其复杂，单纯的http-method 已经不能满足描述。
第一种方式：可以使用在后面加上业务动作。(推荐)
取车：/users/123123123/works/pick-car
第二种方式：或者在body里面机上对应你的参数来表示当前的业务。

{
    "action":"pickCar"
    ....
}

在生产级别的应用版本控制是很严格的。尤其是对于app端。版本，渠道（即应用市场）比较繁琐。
不同渠道，尤其是安卓，不同应用市场，不同审核周期，而且还会面临被驳回，再重新修改的情况。
苹果的App Store 审核严苛，一个应用刚开始，基本上都会被驳回几次。

应用审核这段期间，server端肯定是要上线的，那么怎么，让c端不同版本的兼容，即使一个大问题了。

推荐如下方式，来做请求的路由。

在url中增加版本号。

/v1/users/123123123/works/pick-car

或者在header里面加上版本号字段
当然后台的管理系统不需要这么严格。

作者：GoFun成都技术中心-何刚

最后编辑于：2019.07.01 13:11:03