api设计规范

前言

说到restful，其实我们并不完全遵循restful规范。我们会参考restful的设计理念，并且结合我们自己的一些实践来对web api进行设计。

我们一起来看看RESTFul API有哪些特点：

1. 基于“资源”，数据也好、服务也好，在RESTFul设计里一切都是资源。GET：查询，POST：新增，PUT：更新，DELETE：删除
2. 无状态。一次调用一般就会返回结果，不存在类似于“打开连接-访问数据-关闭连接”这种依赖于上一次调用的情况。
3. URL中通常不出现动词，只有名词
4. URL语义清晰、明确，使用HTTP的GET、POST、DELETE、PUT来表示对于资源的增删改查

5. 返回结果使用JSON不使用XML

   网站：/get_user?id=100
   RESTFul: GET /user/100 (GET是HTTP类型)

我们通常的GET和POST同RESTFul中的GET、POST是不一样的。通常使用GET、POST的选择点在于，简单的用GET、复杂对象用POST，并没有动作的含义，例如我也可以使用get来执行添加的动作，如果参数很多，我也可以使用POST来执行查询操作；但在REST里，GET对应的是查询一个资源，而POST对应的是新增一个资源，意义是决然不同的。理解这一点非常重要。

规范

1. api 接口必须加版本号，初始版本 【v1】
2. 不使用rest的PUT和DELETE，因为很多浏览器不支持，很多框架也不支持
3. POST在需要传输大量数据的时候使用，其余使用GET就可以了；
   

   这里GET和POST没有明确的含义，GET也可以新增

4. 所有路径path全部小写，以下划线分隔，所有参数，包括POST里面的body，以及header。例如：http://127.0.0.1/v1/wechat/mch_info/list_mch_info?page=2&per_page=100
5. 我们返回一般统一使用json格式返回
6. 在url上必须包含行为
7. 使用Token令牌来做用户身份的校验与权限分级，而不是Cookie
8. 暴露外部请求一定使用SSL

Path具体的实现

path = /{版本}/{具体的业务功能}/{表名}/{行为}

1. 
   
2. {版本}：开始时全部为V1，
3. {具体的业务功能}：
   

App的setting，数据库命名为 app_setting
那么，具体的业务功能=setting
架构组的wechat，数据库命名为arch_wechat
那么，具体的业务功能=wechat

• {表名}:就是数据的表名
• {行为}：一般就是方法名
• ?limit=10：指定返回记录的数量
• ?offset=10：指定返回记录的开始位置。
• ?page=2&per_page=100：指定第几页，以及每页的记录数。
• ?sort_by=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

• http协议	方法	行为path	说明
  POST	add(POJO)	/add	添加一个对象，接收json信息
  GET	insert(param …)	/insert?param1=?&param1=?	插入一个对象，多个参数的方式，作用和add一样，只是传参数方式不同
  GET	deleteById(long)	/delete_by_id?id=?	数据库不删除，但是业务上有删除的语意
  POST	update(POJO)	/update
  GET	updateById(long)	/update_by_id?id=?	{表名}中已经具体指明了实体，所有这里可以不用update_pojo_by_id
  GET	getById(long)	/get_by_id?id=?	{表名}中已经具体指明了实体，所有这里可以不用get_pojo_by_id
  GET	listByParam(Object)	/list_by_param?param=?&page=2&per_page=100	list查询多个，默认全部,可以带上limit，offset，page，sort_by，order等参数

参考数据库设计 
【推荐】表的命名最好是加上“业务名称_表的作用”。       
正例: user / trade_config
【推荐】库名与应用名称尽量一致，{业务项目}_{功能},业务项目和功能怎么写参考

Response

1. 采用JSON，不要使用XML
2. 默认情况下要支持gzip
3. 格式统一：

{
      "code" : 0,
      "msg" : "Something bad happened",
      "data" : {

      }
    }

• code: 0为成功，非0为失败。可以自定义code，代表不同的错误码
• msg: 当code为非0时，获取错误信息。当code为0时，msg一般为”success”。如果有需要也可以另外作规定
• data: 当code为0时，获取结果，全部以json方式表示。当code为非0时，data没有数据

错误处理

不要直接将异常抛给客户端处理，一般需要一个统一的异常处理类，并且以统一格式将异常信息返回前端，统一格式参照“# Response”