前后端分离，如何提供一套优秀的接口

本文内容：

1、提供接口前，要有哪些准备工作？

2、提供什么形式的接口文档？

3、接口文档应该包含哪些内容？

4、还有哪些“看不见”的坑？

之前一直负责中后端的服务，写的接口也都是RPC接口。不过最近做的几个需求，都涉及到了和用户直接交互的WEB接口。

我们团队采用的是前后端分离的开发模式，为了提升开发效率、质量，减少扯皮，一份清晰明了的接口文档是必不可少的。

提供接口前，要有哪些准备工作？

最近做的需求是钱包统一的需求，做的过程中发现和支付宝的资产管理有点相似，为了便于理解，就拿支付宝来举例吧。

如上图所示，就是把原来需要从多个入口才能查看到所有资产（左侧），合并成一个入口（右侧）。减少用户操作，提升用户体验。

下面就总结一下提供接口前的准备工作。

聊，确保大家对需求理解一致

这个阶段需要明确本次要做什么？

是新做还是改造？

新功能是直接复用老的数据换个展示形式，还是底层的数据也要改动？

是所有端都改造，还是只是app端改造？

......

这些问题一定要聊明白，否则出现理解偏差，后期的详设、工作量评估都会受到影响。聊的过程中有争议、待确认、已确认的点，一定要落实到文字上。前期沟通有争议的点可能会很多，如不记录跟进，难免会有遗漏，就白白浪费时间了。

一份合格的需求文档也是很有必要的。

明确功能模块

把要做的功能简单划分一下，比如图中可以划分成三个功能模块：总资产模块、保险模块、借贷模块。

模块划分完之后，需要确定哪些功能能实现，哪些实现不了？

比如 “保险模块”最近好像比较忙，而且和本次需求的主要功能关联也不是很密切，是让负责人去协调人力，还是这部分功能先不做？

各个模块所需的数据都能在一个系统获取到吗，还是需要从多个系统获取？

在讨论的过程中，也可以对交互、展示提出看法。并不是UI、UE给出的方案就是完美的，大家都可以提出自己的见解，我们都是为了同一个目的 -- 做出好用的产品。

比如，我觉得“我的额度”放在“我的保障”上面比较合理。

划分清前后端职责

前端是只负责展示？还是要包含一部分业务逻辑？

比如总资产模块所需的数据，是后端返回一个所有资产的List，页面自己计算总和、总收益，还是后端计算？

需要脱敏的数据，是后端脱敏还是页面脱敏？

......

我们的原则：页面需要处理的东西越少越好，把FE当做自己的客户，给客户提供一个好用的接口。

所以我们的方案是，把所有需要计算的数据都在后端处理好，返回给页面直接展示。

确定接口

上面的聊明白之后，就需要确定一下都需要提供哪些接口。

3个功能模块，是提供3个接口，页面依次调用？还是提供1个接口一次返回所需数据？

我们的原则：在各模块耗时可控、数据量不大的情况下，尽可能减少请求的次数，相比每次请求的耗时，多传输一些内容的耗时完全可以忽略。

这里突然想起smartisan OS的“一步”功能，人生苦短，能1步完成的就不要3步4步了！

提供什么形式的接口文档？

文件形式

最常见的文件形式就是 Word、Excel了。估计绝大多数团队现在都不使用这种形式了，一听就是上个世纪的工作模式。这种形式弊端太多了：

• 定好的模板，经过几个需求之后就各成一派了

• 软件、版本兼容的问题，有用WPS的，有用微软的，有高版本的，有低版本的

• 文件损坏、丢失问题，由于是本地编辑，做不到实时保存上传，机器突然重启，可能几个小时就白写了

• 不太适合给前端使用，返回给页面的数据结构如果复杂一些，这种形式不够直观，前端也不能直接拿来开发调试

当初在银行基本都采用这种形式，不过Excel的行、列拖动真是太好用了，调整参数的顺序一拖即可，这是在其他接口管理软件中做不到的。

wiki 形式

就是一个在线版的文档，重点是可以多人协作，方便项目管理，能够解决文件弊端的第2,3条。但它又严重依赖服务器的稳定，服务一挂，整个公司都受影响，经历过的同学都有体会。

我们团队日常文档及RPC接口用的是confluence，其他都还好，就是表格使用体验太差了。如果用到复杂的表格，我都是先在Excel中编辑好粘过去。

这种形式同样也不太适合前端。

REST API 管理平台

这种形式是当下比较流行的，网上也可以找到很多开源的，感觉它就是为前后端分离而诞生的。这种形式比较灵活，可以按多种维度对接口进行管理，集接口管理、测试于一体，也支持多种形式的导入导出。

我们团队使用的是YApi，目前没发现什么缺点，用着很顺手。还在使用上面2种形式的同学可以尝试一下。

关于接口文档，一直有个痛点。不管采用什么形式，接口改动一两次之后，文档和代码就永远对不上了。借口无非就是排期紧，先实现功能，后期再更新文档。我们甚至专门花时间去重新整理接口文档，但效果还是不好。

大家如果有好的解决方案，欢迎留言交流。

接口文档应该包含哪些内容？

基本信息

• 各环境的信息，开发、测试、沙箱、线上的域名

• 接口的名称、描述

• 使用场景

• 协议类型，http还是https

• URL

• 方法类型，GET还是POST

• cookie、header 信息，文件上传的必须要写明

• 如果耗时长的话，最好也标明接口的耗时，页面可能要加载很多接口

使用场景 要强调一下，可能功能相同的两个接口，一个是给app端使用，一个是给PC端使用，入参和出参可能会有差异，所以要标明使用场景。我的习惯是把截图放上去，接口返回的数据在截图中单独标记出来。

就拿总资产首页的接口来说，除了文字描述之外，我还会附上一张截图。

红框里的数据是后端接口返回的（必要的话也可以加个虚线框标识一组数据），其他内容的页面自己写死。

入参

入参一般包含属性名、是否必填、数据类型等信息。

如果感觉自己的模板不好用，可以参考微信、支付宝提供的API文档。

微信：

https://pay.weixin.qq.com/wiki/doc/api/app/app.php?chapter=9_1

支付宝：https://opendocs.alipay.com/apis/api_1

这里就贴一个微信的API截图

（图片来源于微信开发文档）

关于数据类型的选择，我们的原则是：尽量使用String，尤其在处理超15位的数字、金额、日期时要格外小心，吃过亏的同学都知道。

可能被攻击的接口，参数的长度、内容的合法性，后端要做校验控制。

特殊场景必填，主要是指某个字段在特殊场景必填，比如微信环境必填，其他默认0，或者多选一必填（常见于查询接口）一定要在备注里写清楚所有情况，不要等着出问题了再告诉前端，你这个场景应该这样这样...... 

出参

不管是REST还是RPC接口，只要是对外提供的，业内通用的习惯是包装一层，永远不要返回一个不负责任的null。

出参的所有字段也要有详细的描述，还是拿支付宝的总资产来举例：

有几类数据需要强调一下：

金额：精度要统一，还要考虑业务场景，比如收益金额可能为负数，没有就是没有，一定不能给个默认值 0.00。

错误信息：不要把系统内部的异常返回给页面，展示给用户的错误信息一定要经过包装，既要让客户看明白，又要方便开发人员定位问题，所以最好开发和产品共同制定提示文案。

二级页面数据：需要评估绝大多数的操作习惯，还有二级页面的数据量，大概率会点进去或者数据量小，就从一级页面带过去，否则就在跳转的时候再查询一次。

动态模板：比如我们的需求里有个工资单的页面，具体要展示哪些条目，这些条目的顺序，是由后端维护一个模板，可以动态的调整，如果变动频繁就做成配置化的。这类数据的逻辑如果由页面来实现，页面就和业务耦合太严重，也太臃肿了。往往这些数据的改动都是由后端发起的，放在后端维护，后期只需后端修改即可。

数据结构

数据结构现在一般都选用json，大家都非常熟悉了。后端也有各种成熟的JSON工具包，但并不是说后端直接把 toJSONString(object) 的结果给前端就可以了。如果包含Map数据，需要考虑一下返回给页面的是否好用。

比如返回城市列表，下面两种格式的使用成本是完全不一样的。

总之，接口文档一定要简单、易懂。

多站在用户角度考虑，你就把它当做一个产品的使用说明书，要做到让用户一看便懂。

还有哪些“看不见”的坑？

重复请求

这里说的重复请求，主要是指浏览器内部原因，自动发起的重试或者一次发了2个请求。尤其是像“出金”这种重要的接口，最好从前面就开始控制，该加锁加锁，该做幂等就做幂等。

异常数据

前后端可能会因异常数据相互坑。

比如，输入框没做控制，用户输入了类似表情之类的特殊字符，后端如果不支持，就直接抛异常了，就算入库成功，也有可能在展示的时候出现各种怪相，所以后端要加上相应的校验。

再比如，后端返回的某个属性值很长，超出了预估，把页面挤变形了。所以后端在提供数据时，一定要看一下库里的最长、最短数据的边界值，告知前端。

粗心挖的坑

还是举两个不起眼的小例子：

一不小心就会把 "null" 返回给页面。

说好的 "code":"1001", "message":"参数不能为空" 并没有出现。

遇到类似情况，前端就会有很多个问号了。

总结

入参：能少传就少传，能不传就不传，不要相信页面，必要的校验一个不能少

出参：数据尽量都在服务端处理好，页面只负责展示

接口：数量能少就少，同一页面或者二级关联页面的数据，能一次返回就一次返回。

不能只停留在接口层面，每一个字段的值从输入，到入库，再到展示给页面，来龙去脉都要清清楚楚。

拆开看，每一点都没什么技术难度，但是要想提供一个一次定型的接口，需要考虑的东西确实很多。