前言
说到restful，其实我们并不完全遵循restful规范。我们会参考restful的设计理念，并且结合我们自己的一些实践来对web api进行设计。
我们一起来看看RESTFul API有哪些特点：
- 基于“资源”，数据也好、服务也好，在RESTFul设计里一切都是资源。GET：查询，POST：新增，PUT：更新，DELETE：删除
- 无状态。一次调用一般就会返回结果，不存在类似于“打开连接-访问数据-关闭连接”这种依赖于上一次调用的情况。
- URL中通常不出现动词，只有名词
- URL语义清晰、明确，使用HTTP的GET、POST、DELETE、PUT来表示对于资源的增删改查
- 返回结果使用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对应的是新增一个资源，意义是决然不同的。理解这一点非常重要。
规范
- api 接口必须加版本号，初始版本 【v1】
- 不使用rest的PUT和DELETE，因为很多浏览器不支持，很多框架也不支持
- POST在需要传输大量数据的时候使用，其余使用GET就可以了；
这里GET和POST没有明确的含义，GET也可以新增- 所有路径path全部小写，以下划线分隔，所有参数，包括POST里面的body，以及header。例如：http://127.0.0.1/v1/wechat/mch_info/list_mch_info?page=2&per_page=100
- 我们返回一般统一使用json格式返回
- 在url上必须包含行为
- 使用Token令牌来做用户身份的校验与权限分级，而不是Cookie
- 暴露外部请求一定使用SSL
Path具体的实现
path = /{版本}/{具体的业务功能}/{表名}/{行为}
1.{版本}：开始时全部为V1，
2.{具体的业务功能}：
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=?¶m1=? | 插入一个对象，多个参数的方式，作用和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等参数 |
1.参考数据库设计
2.【推荐】表的命名最好是加上“业务名称_表的作用”。
3.正例: user / trade_config
4.【推荐】库名与应用名称尽量一致，{业务项目}_{功能},业务项目和功能怎么写参考
Response
- 采用JSON，不要使用XML
- 默认情况下要支持gzip
- 格式统一：
{
"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”
