http接口调用时注意事项

哎呀呀，今天本来都准备上线了，结果发现了一个小bug（不影响主流程的那种），是由于三方接口返回不明确引起的。主要的问题就是http接口对方返回的是null，而我没有判空。当我判空后，又发现，妈的格式又和约定好的不一样，有个关键success字段居然是空的。。。(￣▽￣)||
然后针对今天的问题，老大叫我去讨论了下，并且传授了一份在调用http接口时常见的注意事项。

接口编程（请求方）

接口调用常见流程

• 请求参数合法校验
• 打印/记录请求报文（日志和数据库）
• 调用
• 网络相关异常处理
  网络连接异常
  网络超时/合理设置超时时间
  其它未知异常
• 打印/记录返回报文
• 报文格式校验
• 报文解析（解析也可以作为格式校验的一部分）
• 报文参数校验（格式、取值范围等）

接口调用切记

• 不打印/记录请求返回报文，给调试和排查问题带来很大麻烦
• 不处理网络相关异常，程序不够健壮
• try/catch大量代码，错误提示不友好、让后续维护的人没有安全感
• 请求和返回参数校验不充分，程序不够健壮
• 没有设计错误码/大量未知错误码
• 报文记录时：不能等获得返回报文时再和请求报文一起记录，需要分别开新事物记录到数据库中

一定要注意设置合理的超时时间！以前做过一个很坑的项目，一个接口需要我设置5分钟的超时时间，后来商量着让对方改为异步的了，后续回调通知结果。
以上是是针对请求方的，如果以后最为提供方的话。

注意点

• 接口文档一定要写详细，每个字段的类型，是否必传，枚举说明，字段的长度。
• 对于关键的返回值，比如状态字段，一定要约定好，不能随意增减。
• 接口地址一般前缀都会加上版本/v1/xxx之类的
• 接口升级时，请一定要注意对以往版本的兼容（/(ㄒoㄒ)/~~特别是新增字段这种，不要出现由于以往版本由于字段无法识别导致错误的情况）
• 接口要精简，不要传无用字段
• 对于处理时间很长的接口，采用回调通知结果的方式
• 一定要记录接口的调用（request，response）情况（同上）
• 对每个接口的调用方要以渠道号区分，每个渠道使用不同的密钥