接口规范接口规范

1. URI规范

不用大写
用 "-" 不用 "_"
参数列表要encode
资源集合,用复数形式表示
在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词（特殊情况可以使用动词），而且所用的名词往往与数据库的表格名对应
避免层级过深的URI,在url中表达层级，用于按实体关联关系进行对象导航，一般根据id导航。
应该将API的版本号放入到URI中,https://api.example.com/v1/zoos

2. Request HTTP方法
通过标准HTTP方法对资源CRUD：
GET：查询（从服务器取出资源一项或多项）
GET /zoos
GET /zoos/1
GET/zoos/1/employees
POST：创建单个新资源。 POST一般向“资源集合”型uri发起
POST/animals //新增动物
POST/zoos/1/employees //为id为1的动物园雇佣员工
3. 状态码服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。
§200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
§201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
§202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
§204 NO CONTENT - [DELETE]：用户删除数据成功。
§400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
§401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
§403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
§404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
§406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
§410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
§422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
§500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
URI失效
随着系统发展，总有一些API失效或者迁移，对失效的API，返回404 not found 或 410 gone；对迁移的API，返回 301重定向
在Controller层使用统一的异常拦截器：

设置 HTTP响应状态码：对业务类异常，用它指定的 HTTPcode；对非业务类异常，统一500；
Response Body的错误码：异常类名
Response Body的错误描述：对业务类异常，用它指定的错误文本；对非业务类异常，线上可以统一文案如“服务器端错误，请稍后再试”，开发或测试环境中用异常的 stacktrace，服务器端提供该行为的开关。

常用的http状态码及使用场景：
状态码
使用场景
400 bad request
常用在参数校验
401 unauthorized
未经验证的用户，常见于未登录。如果经过验证后依然没权限，应该 403（即 authentication和 authorization的区别）。
403 forbidden
无权限
404 not found
资源不存在
500 internal server error
非业务类异常
503 service unavaliable
由容器抛出，自己的代码不要抛这个异常,服务器返回的数据格式，应该尽量使用JSON，避免使用XML
过滤信息
如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

下面是一些常见的参数。 ?limit=10：指定返回记录的数量 ?offset=10：指定返回记录的开始位置。 ?page=2&per_page=100：指定第几页，以及每页的记录数。 ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。 ?producy_type=1：指定筛选条件

API 传入参数
参入参数分为4种类型：

地址栏参数 * restful 地址栏参数 /api/v1/product/122 122为产品编号，获取产品为122的信息 * get方式的查询字串见过滤信息小节请求body数据 cookie request header

cookie和header 一般都是用于OAuth认证的2种途径
返回数据
只要api接口成功接到请求，就不能返回200以外的HTTP状态。
为了保障前后端的数据交互的顺畅，建议规范数据的返回，并采用固定的数据格式封装。
接口返回模板：

{ status:0, data:{}||[], msg:’’ }

status: 接口的执行的状态

=0表示成功 <0 表示有异常=""

Data 接口的主数据

，可以根据实际返回数组或JSON对象

Msg

当status!=0 都应该有错误信息

4. 非Restful Api的需求由于实际业务开展过程中，可能会出现各种的api不是简单的restful 规范能实现的，因此，需要有一些api突破restful规范原则。特别是移动互联网的api设计，更需要有一些特定的api来优化数据请求的交互。
页面级的api
把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据
举例
api/v1/get-home-data 返回首页用到的所有数据

这类API有一个非常不好的地址，只要业务需求变动，这个api就需要跟着变更。

自定义组合api

把当前用户需要在第一时间内容加载的多个接口合并成一个请求发送到服务端，服务端根据请求内容，一次性把所有数据合并返回,相比于页面级api，具备更高的灵活性，同时又能很容易的实现页面级的api功能。

规范
地址：api/v1/batApi
传入参数：

data:[ {url:'api1',type:'get',data:{...}}, {url:'api2',type:'get',data:{...}}, {url:'api3',type:'get',data:{...}}, {url:'api4',type:'get',data:{...}} ] 返回数据{status:0,msg:'', data:[ {status:0,msg:'',data:[]}, {status:-1,msg:'',data:{}}, {status:1,msg:'',data:{}}, {status:0,msg:'',data:[]}, ] }

【接口规范】Api共建平台