每一個產品經理都該懂點技術（二）——接口文檔的做用

兩年前寫了每一個產品經理都該懂點技術的第一篇。我覺得我能堅持寫個七八篇這個系列的文章，結果兩年過去了第二篇都沒寫完。其實並非沒寫，而是本身對產品和技術之間的關係的理解確實淺薄。今天發表這篇主要是由於我沒預料到第一篇能有將近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都要有相應版本的文檔。這樣當項目須要回滾的時候咱們能夠立刻知道上個版本的需求。

總結

本篇沒有從教科書的層面去說項目文檔的做用，我是結合了本身的開發經驗來講一下本身對文檔的體會。跟上篇同樣，我也是從開發者的角度去理解產品經理的思惟。但願我本身的體會能讓產品經理更瞭解開發者的思路。