写一个restful后台你需要什么

基础知识

• HTTP 协议
• oauth2 协议
• 一定的数据库设计使用能力
• json

协议设计

作为后台服务，需要一个比较符合程序员直觉的设计感觉，最基本几个要求：

1. url应该包含版本号，方便多个版本的前台使用
2. 语义化url,url中不要包含动词，前后url应该包含结构间应该包含明显的包含关系
3. 语义化动作,目前的情形下只需要包含get(查询),post(新增),put(修改),delete(删除)即可
4. 输入和输出采用json
5. 使用http state code 表示结果状态

url设计

• 包含版本号，方便迭代，多个版本api同时使用
• url中的名词需要注意单复数形式，对单个资源的操作用单数，对多个资源的操作用复数
• 名词化资源:url中的每个部分应该包含明比较明显的从属关系，设计上比较符合数据库中er模型的实体，注意名词的单复数对于ge
  • 获取用户 get /v1/user
  • 获取所有用户 get /v1/users
  • 获取某个用户 get /v1/user/1
  • 修改某个用户信息 put /v1/user/1
  • 获取某个用户的所有电话 get /v1/user/2/phone_nums
  • 有时可以省去指定某个特定 /1 ，作为当前用户，返回当前用户的电话 get /v1/user/phone_nums

语义化动作

使用http的几个标准方法来操作资源
目前主流支持的http方法有:

• get 获取资源
• post 创建资源
• put 、patch 更新资源
• delete 删除资源

使用这些方法配合url定位资源基本可以完成大部分操作

实际使用过程中可能有很多请求不是这样的动词语义，但基本都可以映射到这几种方法上来

鉴权Authentication

因为restful 的无状态特点，鉴权提供了如何识别一个请求发出者

目前业界普遍使用的是oauth2.0协议，目前我们使用的是一个它的简化版本，在http header 中增加一个字段
Access_token 作为用户鉴权标准。

需要注意的是，为了增加安全性，这个token应该增加自动过期，然而为了体验，目前没有设置

输入和输出

输入和输出根据方法的不同，正确结果不同有所差异。

查询操作

get 中可以使用查询字符串作为输入 比如 get /v1/user?username=a

而查询需要发送的参数的作用一般在于进行几个后续操作，有分页，过滤，搜索，排序

*分页:
目前采用的使用page参数作为页码进行操作

v1/users?page=1

但是新的标准中使用的是link header作为翻页的标准，使用link header的API应该返回一系列组合好了的url而不是让用户自己再去拼。这点在基于游标的分页中尤为重要。例如下面，来自github的文档

Link: <https://api.github.com/user/repos?page=3&per_page=100>; rel="next", 
<https://api.github.com/user/repos?page=50&per_page=100>; rel="last"

根据目前情况，仍然将使用一段时间page 作为分页游标

• 过滤 ，过滤结果。目前没有这样的操作
• 搜索，使用?q=asd 查询字符传来查询，所有的搜索都是使用模糊搜索
• 排序，使用?sort_by=asd 查询字符串来进行排序

输出，根据文档而定，一般而言根据结果可以分为正确返回和错误返回

需要注意的是单复数返回结果的不一致
返回某个用户信息 get /v1/user/2

    {
        "id": 1,
        "username":"asd",
        "phone":"132xxxx2222"
    }

获取全部用户信息 get /v1/users

    {
        "users":[
            {
                "id":1,
                "username":"asd",
                "phone":"132xxxx2222"
            },
            ...
        ]
    }

新增操作

post方法使用json object 获取传入参数

比如创建用户 则可以向 /v1/user 发送post 请求，请求body是json字符串

{
    "username":"coco",
    "password":"test"
}

post,put 方法房返回 创建、修改的id，比如之前创建用户的操作返回json

{
    "id":123
}

更新操作

put 方法使用json object 获取传入参数,传入的数据大体相当于post方法。但是这边为了方便使用，混淆了put和patch 方法，所有put 方法的参数都是可选的，只修改发来的参数部分

删除操作## Heading

delete 方法不接受参数，对某个资源的操作需要包含在
delete 方法返回操作结果，一般是

    {
        "state":"ok"
    }

标准化过程

一般的restful操作基本可以分为这么几步

restful过程

其中出现了几个错误，用几个http状态码确定错误类型
所有错误返回体是
{ "state":"error", "code":123, "reason":"呵呵"}

下一篇将 python的tornado 框架具体实现一个这样标准的模板~~~~

全文禁止转载！！！！