api接口详解大全（看这篇就足以了）

接口多了,对应函数名和参数就多了,前端在请求api接口时难找.容易出现重复的接口

RESTful: 翻译成中文: 资源状态转换.(表征性状态转移)

把服务端提供的所有的数据/文件都看成资源， 那么通过api接口请求数据的操作，本质上来说就是对资源的操作了.因此，Restful中要求，我们把当前接口对外提供哪种资源进行操作，就把资源的名称写在url地址。

web开发中操作资源，最常见的最通用的无非就是增删查改，所以restful要求在地址栏中声明要操作的资源是什么。然后通过http请求动词来说明对该资源进行哪一种操作。POST http://www.xxx.com/api/students/ 添加学生数据GET http://www.xxx.com/api/students/ 获取所有学生DELETE http://www.xxx.com/api/students// 删除id=pk的一个学生PUT http://www.xxx.com/api/students// 修改一个学生的全部信息 [id,name,sex,age,]PATCH http://www.xxx.com/api/students// 修改一个学生的部分信息[age]

也就是说，我们仅需要通过url地址上的资源名称结合HTTP请求动作，就可以说明当前api接口的功能是什么了。

Restful是以资源为主的api接口规范，体现在地址上就是资源就是以名词表达。RPC则以动作为主的api接口规范，体现在接口名称上往往附带操作数据的动作。

为了在团队内部形成共识、防止个人习惯差异引起的混乱，我们都需要找到一种大家都觉得很好的接口实现规范，而且这种规范能够让后端写的接口，用途一目了然，减少客户端和服务端双方之间的合作成本。由于接口所包含的内容比较细，在项目中常常需要使用接口文档。研发人员可以根据接口文档进行开发、协作，测试人员可以根据接口文档进行测试，系统也需要参照接口文档进行维护等。

API与客户端用户的通信协议，推荐使用http协议，同时兼容HTTP，以确保交互数据的传输安全。

应该尽量将API部署在专用域名之下。http://api.xxx.com

如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。http://www.xxx.com/api/

推荐将API的版本号放入URL。

http://api.xxx.com/app/v1.0/foohttp://api.xxx.com/app/v1.1/foohttp://api.xxx.com/app/v2.0/foo

另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。

版本号规范：1）采用多版本并存，增量发布的方式。2）版本号可以分为整型和浮点型整型：大功能版本，如v1、v2、v3 ...浮点型：补充功能版本，如v1.1、v1.2、v2.1、v2.2 ...

关于版本兼容性，小版本变化向下兼容的，只要大版本不变化。3）对于一个API或服务，应在生产中最多保留3个最详细的版本

路径又称"终点"（endpoint），表示API的具体网址，每个网址代表一种资源（resource）

接口命名应该是一个动宾结构，由动词 名词组成，采取驼峰式命名规范，例如：

product/v1.0/getProducts 获取产品order/v1.1/saveOrder 保存订单

接口命名常见通用动词可以参考如下：

公共参数是每个接口都要携带的参数，描述每个接口的基本信息，用于统计或其他用途，放在Header或url参数中。

Queryurl?后面的参数，存放请求接口的参数数据。

Header请求头，存放以下公共参数、APP端公共参数等，也可以存放一些特殊加密字段。

BodyBody体，存放请求接口的参数数据。

APP端请求参数除了上述公共参数外，还需要以下额外公共参数：

若记录数量很多，服务器不可能返回全部记录给用户。API应该提供分页参数及其它筛选参数，过滤返回结果。

参数示例如下limit=10：指定返回记录的数量offset=10：指定返回记录的开始位置。page=2&per_page=100：指定第几页，以及每页的记录数。sort_by=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

1）上传/下载上传/下载，参数增加文件md5，用于完整性校验（传输过程可能丢失数据）。2）避免精度丢失缩小单位保存数据，如：钱以分为单位、距离以米为单位。

为了方便给客户端响应，响应数据会包含三个属性，状态码（code）,信息描述（message）,响应数据（data）。客户端根据状态码及信息描述可快速知道接口，如果状态码返回成功，再开始处理数据。array类型数据。通过list字段，保证data的Object结构。

返回示例：

分页类型数据。返回总条数，用于判断是否可以加载更多。返回示例：

响应状态码code统一使用英文组合字符串，多层分级使用“.”分隔，例如：PARAMETER.ILLEGALL

PARAMETER.ILLEGALL代表参数错误，不推荐使用数字，数字错误码可读性太差。

注意：1）返回属性名命名时，建议使用驼峰命名，首字母小写。2）返回属性值为空时，严格按类型返回默认值。3）返回金额类型/时间日期类型的属性值，如果仅用来显示，建议后端返回可以显示的字符串。4）返回业务逻辑的状态码和对应的文案，建议后端两者都返回，中间添加“|”分隔，例如“SUCCESS|成功”，SUCCESS表示接口状态成功，显示给客户表示“成功”。5）调用方不需要的属性，不要返回。

一般调用接口最常用的两种方式就是GET和POST。两者的区别也很明显，GET请求会将参数暴露在浏览器URL中，而且对长度也有限制。为了更高的安全性，所有接口都采用POST方式请求。另外不推荐使用rest的PUT和DELETE，因为很多浏览器不支持，很多框架也不支持。

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

返回响应数据采用JSON，不推荐使用XML，XML是W3C为了替换HTML研发出来的，但是现在很明显失败了。默认情况下要支持gzip

获取token一般会涉及到几个参数app_id，app_key，timestamp，request_id，sign。我们通过以上几个参数来获取调用系统的凭证。

token作为系统调用的唯一凭证，token可以设置一次有效，也可以设置时效性，这里推荐设置时效性。如果一次有效的话这个接口的请求频率可能会很高。token推荐加到请求头上，这样可以跟业务参数完全区分开来。

这里面主要涉及到sign签名设计规范和token生成规范，需要遵守如上规范，能够保证API接口的安全性和幂等性。

ip白名单是指将接口的访问权限对部分ip进行开放。这样就能避免其他ip进行访问，设置ip白名单比较麻烦的一点就是当你的客户端进行迁移后，就需要重新联系服务提供者添加新的ip白名单。设置ip白名单的方式很多，除了传统的防火墙之外，spring cloud alibaba提供的组件sentinel也支持白名单设置。为了降低api的复杂度，推荐使用防火墙规则进行白名单设置或者在API网关层面设置IP白名单，比如shenyu网关支持IP白名单设置。

限流是为了更好的维护系统稳定性。使用redis进行接口调用次数统计，ip 接口地址作为key，访问次数作为value，每次请求value 1，设置过期时长来限制接口的调用频率。不过这里还是推荐在网关层面进行设置，比如shenyu网关支持IP限流。

参数安全：登录密码、支付密码，需加密后传输，建议使用非对称加密

响应结果：用户手机号、用户邮箱、身份证号、支付账号、邮寄地址等要进行脱敏，部分数据加 * 号处理。

在接口调用过程中数据通常需要脱敏安全处理，最常用的方式就是加密。加密方式使用安全性比较高的RSA非对称加密。非对称加密算法有两个密钥，这两个密钥完全不同但又完全匹配。只有使用匹配的一对公钥和私钥，才能完成对明文的加密和解密过程。

幂等性是指任意多次请求的执行结果和一次请求的执行结果所产生的影响相同。说的直白一点就是查询操作无论查询多少次都不会影响数据本身，因此查询操作本身就是幂等的。但是新增操作，每执行一次数据库就会发生变化，所以它是非幂等的。

我们无法保证接口的每一次调用都是有返回结果的，要考虑到出现网络异常的情况。举个例子，订单创建时，我们需要去减库存，这时接口发生了超时，调用方进行了重试，这时是否会多扣一次库存？

对于一些重要的操作需要防止客户端重复提交的(如非幂等性重要操作)，具体办法是当请求第一次提交时将request_id作为key保存到redis，相应的返回结果集作为value存储到redis，并设置超时时间。当同一个请求第二次访问时会先检测redis是否存在该request_id，如果存在则证明重复提交了，接口直接返回不再继续调用了。

1.接口调用方(客户端)向接口提供方(服务器)申请接口调用账号，申请成功后，接口提供方会给接口调用方一个app_id和app_key

2.客户端携带参数app_id、timestamp、request_id、sign去调用服务器端的API token，其中sign=加密(app_id timestamp request_id app_key)

3.使用参数app_id，timestamp，request_id，sign来获取token，token作为系统调用的唯一凭证

4.客户端拿着token 去访问相应的接口

5.如果token过期需要获取刷新token

sign的作用是防止参数被篡改，客户端调用服务端时需要传递sign参数，服务器响应客户端时也可以返回一个sign用于客户端校验返回的值是否被非法篡改了。

1、尽量采用自动化接口文档，可以做到在线测试，同步更新,推荐使用swagger、yapi。2、应包含：接口BASE地址、接口版本、接口模块分类等。3、每个接口应包含：接口地址：不包含接口BASE地址。请求方式: GET、POST。请求参数：数据格式【默认JSON、可选form data】、数据类型、是否必填、中文描述。响应参数：类型、中文描述。

关于限流设计、熔断设计、降级设计，目前主流网关都有相关功能（比如shenyu网关），可以不在API实现中开发这些功能。

另外推荐把API相关日志存储到日志平台，日志平台有利于故障定位和日志统计分析以及接口监控。日志平台的搭建可以使用的是ELK组件，使用Logstash进行收集日志文件，使用Elasticsearch引擎进行搜索分析，最终在Kibana平台展示出来。