第三方接口设计注意要点

实际工作中，我们会遇到与三方系统对接的情形，比如对接短信服务、支付服务、地图服务、以及一些外部业务系统的调用和回调等等，不论是我们调用第三方接口还是我们为其他系统提供接口服务，调用过程中会遇到一些大大小小的问题和吐槽的地方，比如接口不通对方可能有白名单限制、接口返回字段与文档不一致、接口不稳定等等，本文总结了一些在设计第三方接口过程中要考虑的到的点。

一、接口设计

1.URL和请求方式

• 请求方式可以使用GET和POST，不推荐使用PUT和DELETE，由于其复杂性和兼容性问题，在实际开发中少用。
• 一个对外提供的接口，随着业务的变化，很大的概率会发生更新，一般来说增加字段不会影响原有接口调用，但当进行一些大业务逻辑变动或者字段必须要修改时，就需要使用新的url来处理新的业务逻辑，这个时候我们可以将接口的版本号放入URL。如：https://xxx.xxx.com/v1/products获取v1版本下的所有产品，版本号可以是整数型和浮点型。

2.请求参数

• 明确请求参数的类型、必填项和默认值，便于调用者理解和使用
• 一般用于认证的参数的公共参数放在header，其余的一般在请求body体和url参数中
• 参数校验，如果外部用户传入了一些异常值，有可能我们服务会报错，参数校验是必要的，比如邮箱格式、非空判断等

3.响应参数

• 统一接口的响应数据格式，一般为JSON
• 响应数据一般必包含三个属性：状态码code、执行结果消息message、响应数据data
  • { code: 200, data: { ... }, message: '成功' }
• 列表类接口若返回数据条数很多，应提供分页返回以及其他条件筛选参数
• 异常统一处理，避免把服务内部的异常栈直接返回，当出现异常时通过code和message来统一处理，这样做好处是便于第三方了解问题原因，避免系统敏感信息（比如数据库表、代码类等）泄露。如：{ "code":500, "message":"服务器内部错误", "data":null }

二、安全性

设计一个接口，我们往往习惯优先考虑功能性和可用性，接口安全容易被忽略，而安全性从来都是外部接口设计