前言

调用第三方接口在很多系统中都很常见，不管是调用本公司其他业务平台的接口，还是调用三方公司的接口，都需要一定的规范，否则系统容错性会较差，而且出问题的时候不利于问题排查，也可能会造成双方互相推卸责任的情况，大公司很容易出现这种扯皮的问题。为避免相应的麻烦，需要制定相应的规范，以下规范可做参考。

注意事项通讯标准确定协议 Http/Https确定参数传输格式 json/x-www-form-urlencoded/...具体接口参数的数据类型（弱类型对接强类型语言时容易踩坑）确定身份校验方式token参数签名：单一Key、交换公钥证书校验确定响应结构（统一成功响应码等等）

调用第三方平台接口需要进行系统间的通信，目前常用的协议是http和https；简单理解https是http的加密版，可以将用户到服务端请求的信息进行加密，避免因明文传输被截获而获知用户信息。

基于http协议的接口具有轻量级、跨平台、和跨语言的特点，为了适应不同的开发者，目前各个第三方平台都会提供基于各种常用语言的接口形式，因此大多采用http或https协议。

请求方式

了解接口的请求方式有助于了解用户端和服务端间的交互方式，基于http协议的常用请求方式是post和get；两者的主要区别如下：

（1）直观区别：get请求方式是将请求参数放到url中，post是将参数放到requst body中，所带来的的直接影响是get的请求参数存在长度限制，post无限制；其次是get将参数放到url中安全性弱于post；

（2）深度区别：get请求方式用户端和服务端只产生一次交互，post请求方式用户端会和服务端产生两次交互。

安全

常用的安全认证机制有Basic Auth、JWT、Oauth2。

Basic Auth

Basic Auth是一种较为简单的认证方式，客户端通过明文（Base64编码格式）传输用户名和密码到服务端进行认证。通过在 Header 中添加key为 Authorization，值为 Basic 相应token的base64编码。

优点：

简单，被广泛支持。

缺点：

安全性较低，需要配合HTTPS来保证信息传输的安全。无法防止 「重放攻击」 与 「中间人攻击」。

JWT

JWT是为了在网络应用环境间传递声明而执行的一种基于JSON的开放标准，可实现无状态、分布式的Web应用授权。

优点：

可扩展性好：应用程序分布式部署的情况下，session需要做多机数据共享，通常可以存在数据库或者redis里面。而jwt不需要。无状态：jwt不在服务端存储任何状态。RESTful API的原则之一是无状态，发出请求时，总会返回带有参数的响应，不会产生附加影响。用户的认证状态引入这种附加影响，这破坏了这一原则。另外jwt的载荷中可以存储一些常用信息，用于交换信息，有效地使用 JWT，可以降低服务器查询数据库的次数。有效避免了CSRF 攻击适合移动端应用单点登录友好

缺点：

安全性：由于jwt的payload是使用base64编码的，并没有加密，因此jwt中不能存储敏感数据。而session的信息是存在服务端的，相对来说更安全。性能：jwt太长。由于是无状态使用JWT，所有的数据都被放到JWT里，如果还要进行一些数据交换，那载荷会更大，经过编码之后导致jwt非常长，cookie的限制大小一般是4k，cookie很可能放不下，所以jwt一般放在local storage里面。并且用户在系统中的每一次http请求都会把jwt携带在Header里面，http请求的Header可能比Body还要大。而sessionId只是很短的一个字符串，因此使用jwt的http请求比使用session的开销大得多。一次性：无状态是jwt的特点，但也导致了这个问题，jwt是一次性的。想修改里面的内容，就必须签发一个新的jwt。

Oauth2

基于Oauth2的动态签名，在每次接口调用时都需要传输以下参数：

「app_id」 应用id「time」 当前时间戳「nonce」 随机数「sign」 签名

其中sign签名的生成方式为：使用参数中的 app_id + time + nonce 在最后追加 app_secrect 的字符串进行md5加密，并全部转换成大写。

如果需要实现参数的防篡改，只需把接口所有的请求参数都作为签名的生成参数即可

优点：

安全性最高

服务端使用相同的方式生成签名进行对比认证，无需在网络上传输 app_secrect。可以防止 「中间人攻击」。通过 time 参数判断请求的时间差是否在合理范围内，可防止 「重放攻击」。通过 nonce 参数进行幂等性判断。

缺点：

不适用于前端应用使用，js源码会暴露签名的方式与app_secrect

针对上述三种接口认证方式，我们需要给出合理的安全评估，确认接口的安全性，避免因为安全问题导致的一些特殊事件。

入参/出参

在开发三方接口调用之前，要仔细阅读接口文档，和接口提供方明确接口的参数校验，以避免在调用过程中发生错误异常。

对于一个接口的返回值的多种情况要考虑清楚，如若多种类型但是其他方只返回一种情况，双方的产品要及时沟通并确定结果给开发人员，否则会严重导致整个业务流程走不下去。

超时设置

超时设置主要有两个参数：连接超时(ConnectionTimeout)、读取超时(ReadTimeout)。

需要合理的设置超时参数，不能无限等待，如果设置超时时间过长，在高并发场景下容易导致线程挂起，CPU负载飙高，超时时间太短容易出现超时异常。

针对超时异常，需要通过try/catch进行降级处理，用户侧并给出友好提示。

针对接口响应时间长的接口，可以和接口提供方协商改为异步接口，通过回调通知结果。

限流

接口限流也是为了保障系统的安全性，因为有时业务方因为业务扩展导致调用量激增，容易引起服务端宕机；限流就类似于电闸的保险丝保证请求量超过接口上限时系统可以拒绝请求或排队，以此保证系统的安全性；

技术人员给出合理评估量，如TPS（每秒处理的请求量）；这样既不会造成系统资源的浪费，也保证业务正常运行。

幂等重试

针对幂等问题，首先要和接口提供方确认接口是否能够保证幂等性，在保证幂等的情况下，根据错误码进行重试。

通常以下三种情况下，可以进行重试：

1.报文丢失，真的丢了，server没收到，所以业务实际没执行

2.报文响应丢失，报文到达server，server也处理了。但是response后，client未收到

3.报文响应，返回可重试错误码

以上1,2情况通常是网络闪断导致，这3种情况应该处理的方式是不一样的，client进行重试请求。

也就是说client无法区分到底发生了第一种错误还是第二种错误。自然也就无法判断目前是那种情况，自己应该采用何中应对之策。而且第二种处理，对不同类型消息，查询到的响应信息是不同的，也就是说各接口需要独立实现额外的查询功能，有较大开发量。

解决方案：对所有请求的唯一标志，requestId建立独立日志表，记录request、requestId和response。

如果新报文的requestId存在如下情况：

01.不在表中，说明全新请求，正常执行业务逻辑即可。

02.在表中，但是response为空，说明这个请求正在处理中，返回约定错误码，让其稍后再试。

03.在表中，且response不为空，说明这个请求已经处理过，且响应过报文，直接将上次的response再返回一次即可。

在这种方案下，如果对方未收到response，重试即可。

幂等核心防止业务数据重复保存，要有唯一识别的编号用于标识相同的业务数据，相同业务数据可以重复调用，返回相同处理结果。

日志

针对请求参数和响应结果，需要记录日志，并进行持久化保存，日志记录里需要有明确的唯一requestId，接口要方便调式追踪，记录好输入和输出信息，方便查找问题。

接口环境

要和接口提供方，明确有哪些环境，是否提供灰度环境，通常会有开发、测试、预发布、生产环境，要和接口提供方明确有哪些环境，进行相关的配置。

线上业务如果依赖于第三方服务，而且线上线下使用的不是同一个账号/环境，一定要在模拟环境测试通过后，再在模拟环境用依赖的正式账号走一遍，确认依赖的正式账号/资源可用，以及配置正确。

不要等到第一次上线的时候 ，再配置依赖的正式账号/环境。有可能外部资源时间配置会比较长，最终导致当天上线不成功/延期。

监控与告警

遵循的原则其实是『 对任何第三方应当保持不可信原则 』，在很多经典书都能看到这番话的，最简单的第三方超时进而导致业务执行失败，通过异常捕获和转换，让业务更清晰。

接口异常要记录，尽可能地保存业务信息，方便还原信息，错误达到阈值要报警，还有另外一种情况，对方接口升级存在不兼容的情况，也需要进行异常告警。

同时需要将接口的响应时间进行监控，针对响应时间慢的接口需要和接口提供方沟通是否有优化空间。

最佳实践

1. 需要通过第三方接口获取数据的服务，禁止直接调用第三方接口，必须通过旁路系统进行调用。旁路系统可以是一个后端程序，如java程序。

2. 需要通过第三方接口获取数据的服务，必须做容错性处理。在第三方数据出错的情况下程序必须保证稳定性。当数据出错时可以进行友好的提示。

3. 把控第三方接口数据的旁路系统，在第三方接口异常、数据出错时必须记录相应日志。方便紧急相应人员根据日志排查定位问题。

收录于合集 #技术总结

5个

下一篇万字长文：深入解读混沌工程