API设计注意事项

当我们在API设计的时候我们应该注意什么？那些需要前端处理？那些需要后端处理？是通用接口还是专用接口？用什么工具可以让前后端协同效率更高？接口实现和接口设计不一致怎么办？这些问题都值得我们思考。以下问题笔者觉得API设计要注意的一些事项：

精度丢失问题

小程序展示的时候，long类型精度会丢失。其他浮点型计算可能导致精度丢失，为了避免，可以缩小单位进行存储。

良好的结构

比如说一个接口里面是一个实体的id和name，我们应该标注到底是什么id和name。Json数据保持良好结构(信息分类)。

{
    "userId"...
    "userName"...
    "userPhoto"...
    "orderId"...
    "orderType"...
    "addressId"...
    "addressName"...
    "addressDetail"...
}

命名

见名知意，客户端和服务端命名保持一致，要驼峰都驼峰，要下划线都下划线。下拉框的、列表、统计的命名方式统一。

瘦客户端

将业务重心交由后端，客户端保持逻辑简单。客户端尽量只负责展示逻辑，不处理业务逻辑。客户端不处理金额的计算。客户端少处理请求参数的校验与约束提示(手机号和固话)。接口单一职责。

扩展性

默认图片，特别是"xxx20分钟之内"，"xxx7天到期"这些带数字的文案，不可能永远不变的，即使和PM确认了打死不变，也最好通过常量配置接口进行下，尽量有后端下发。用flag替换boolean。

安全性

后端脱敏手机号，身份证号等，密码之类就不能传递。参数防篡改，可变token，参数签名匹配，接口加密(目前https)。对外的API对接的安全性保证（加密算法）。

兼容性

接口version，新老版本并行方案，新版体验等。

性能优化

合并接口，客户端请求完A去请求B，后端一次性把AB的接口返回给客户端。字段精简，减少流量消耗。

热点数据缓存，无需的字段清理，小图和缩略图、局部刷新、Wifi移动网路区别对待、数据压缩(gzip)、CDN。体检优化：时间戳(缓存)， 懒惰加载，预加载。

压测某些接口超过规定的响应时间，不允许发版。

专用or通用

通用接口可以为更多的调用方提供服务，调用方可以处理更多的业务逻辑，使用会灵活一些；专用接口一般只能为某些少数的业务场景提供服务，可以实现更多的业务逻辑，调用方用起来比较简单方便。

容错性

提升容错性。接口缓存击穿的时候存null合适吗？会不会造成空指针？还有Gson库在解析到某个非法字段时，会抛出各种异常，导致整个model的解析失败，自定义JsonDeserializer，提高容错性，规避脏数据引起的数据解析失败。

文档

大多数API设计工具里面的接口可能会和代码真实的接口不一致（入参、出参、校验、错误码）。文档和架构特别容易在项目的进化过程中腐朽， 如何保持统一标准， 非常难， 前后无法闭环，和最后出来的结构是否能够一致， 如何校对？ 抽取元数据去和apifox设计的接口对比。

第三方对接文档的话，把对方的开发者当成傻瓜的心态去做对接文档。参考之前的总结—《第三方对接》。

精进自省：做的任何选择都是为了你要成为一个什么样的人。乐观者往往成功，悲观者往往正确。开阔快乐的心态保持奋斗。