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

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

---

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

约束

假如你的项目中有若干前端和若干后端。你如今须要开发一个登录接口，一般状况下这个功能一个前端和一个后端开发就足够了。有些公司的后端很强势，所以可能出现后端写好接口以后告诉前端去开发页面。也可能前端很强势，所以前端写好页面以后让后端去写接口。

这两种状况都不是咱们但愿见到的。这是由于若是咱们自由开发一个接口，后端开发人员一般会选择最符合后端直觉的方式去写接口。反过来，对于前端开发人员来讲，他们必定会选择最容易展现的方式去写页面。这两种直觉之间是会有差别的，所以这样的一方主导开发的状况很容易出现各类各样的意外状况。

因此为了不这样的状况，咱们须要接口文档来约束先后端的协同开发。

规范

个人职位是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都要有相应版本的文档。这样当项目须要回滚的时候咱们能够立刻知道上个版本的需求。

总结

本篇没有从教科书的层面去说项目文档的做用，我是结合了本身的开发经验来讲一下本身对文档的体会。跟上篇同样，我也是从开发者的角度去理解产品经理的思惟。但愿我本身的体会能让产品经理更了解开发者的思路。