每个产品经理都该懂点技术（二）：接口文档的作用

两年前写了每个产品经理都该懂点技术的第一篇。我以为我能坚持写个七八篇这个系列的文章，结果两年过去了第二篇都没写完。其实并不是没写，而是自己对产品和技术之间的关系的理解确实浅薄。今天发表这篇主要是因为我没预料到第一篇能有将近5000的阅读（考虑到很多我认真写的技术文章阅读不过百，5000阅读数已经是我的人生巅峰了），其次是今年三月份有个读者评论让我续写。所以我就把之前写的这篇加上这两年的思考重新整理了一下。望各位喜欢。

---

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

约束

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

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

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

规范

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

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

学生表

然后需求变动了，我们需要把学生表展示为教师表。

image.png

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

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

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

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

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

版本回溯

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

总结

本篇没有从教科书的层面去说项目文档的作用，我是结合了自己的开发经验来说一下自己对文档的体会。跟上篇一样，我也是从开发者的角度去理解产品经理的思维。希望我自己的体会能让产品经理更了解开发者的思路。