兩年前寫了每個產品經理都該懂點技術的第一篇。我以為我能堅持寫個七八篇這個系列的文章，結果兩年過去了第二篇都沒寫完。其實並不是沒寫，而是自己對產品和技術之間的關系的理解確實淺薄。今天發表這篇主要是因為我沒預料到第一篇能有將近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都要有相應版本的文檔。這樣當項目需要回滾的時候我們可以馬上知道上個版本的需求。
總結
本篇沒有從教科書的層面去說項目文檔的作用，我是結合了自己的開發經驗來說一下自己對文檔的體會。跟上篇一樣，我也是從開發者的角度去理解產品經理的思維。希望我自己的體會能讓產品經理更了解開發者的思路。