笔记 | 产品经理必懂的技术（二）

上一篇提到，前后端合作开发的时候需要用到接口文档。那么本篇就说说接口文档在产品中究竟有什么作用。

约束

假如你的项目中有若干前端和若干后端。你现在需要开发一个登陆接口，通常情况下这个功能一个前端和一个后端开发就足够了。有些公司的后端很强势，因此可能出现后端写好接口之后告诉前端去开发页面。也可能前端很强势，因此前端写好页面之后让后端去写接口。

这两种情况都不是我们希望见到的。这是因为如果我们自由开发一个接口，后端开发人员通常会选择最符合后端直觉的方式去写接口。反过来，对于前端开发人员来说，他们一定会选择最容易展示的方式去写页面。这两种直觉之间是会有差异的，因此这样的一方主导开发的情况很容易出现各种各样的意外情况。

所以为了避免这样的情况，我们需要接口文档来约束前后端的协同开发。

规范

我的职位是Java后端开发，不过实际工作中也会写很多前端页面。虽然技术上是前后端分离的，但是对于我来说，其实是一起开发的。既然自己开发前后端，肯定会了解前后端各自的特点，那么就不会因为开发思路的差异而导致出现意外。那么对于我来说，是不是接口文档就没必要存在了呢？
答案显然是否定的。接口文档的另一个重要作用就是规范。
项目需求变动是很常见的情况，举个例子，我们现在有一个学生表。页面上需要用一个表格展示所有的学生，可以分页操作。
假设现在的接口文档是这样的：

名称	                                  内容
API	                               /student
返回内容	         student:[{id:'',name:'',addredd:''}]
参数1	                    currentPage 当前页
参数2	                       pageSize 页大小

然后需求变动了，我们需要把学生表展示为教师表。
这两个接口从后台逻辑来说应该是完全一致的。唯一的差别是我们需要查不同的表。从前台逻辑来说，这两个除了接口不一样，其他的分页字段应该是一致的。理想情况下如果一个前端开发接手这个页面之后，完全可以不看文档直接改API地址，然后修改页面的填充数据就可以了。

现实是，很多接口的规范做的不好。这就导致了，逻辑相同的两个接口，他们的查询参数可能是不一样的。这样就会出现下面的情况：

名称	                     内容
API	                   /teacher
返回内容      teacher:[{id:'',name:'',addredd:''}]
参数1	            page 当前页
参数2	             size 页大小

返回内容的更改是没问题的，但是因为两个接口没有规范，这就导致其他开发人员接手的时候不仅需要改数据的格式，也需要更改参数名。这在无形中就降低了开发效率。

另一方面，文档健全肯定是好的。但是毫无规律，随意编写的文档却会降低开发效率。因此健全的文档必须要配合良好的文档规范，这样才可以让开发人员可以预估API返回的数据格式和请求参数。

版本回溯

基本上每个App都有一个版本号。这个版本号是代码的版本，表示这个版本的代码有相应的功能。同样的道理，文档也需要通过版本进行管理。每个版本的App都要有相应版本的文档。这样当项目需要回滚的时候我们可以马上知道上个版本的需求。