兩年前寫了每個(gè)產(chǎn)品經(jīng)理都該懂點(diǎn)技術(shù)的第一篇。我以為我能堅(jiān)持寫個(gè)七八篇這個(gè)系列的文章，結(jié)果兩年過去了第二篇都沒寫完。其實(shí)并不是沒寫，而是自己對產(chǎn)品和技術(shù)之間的關(guān)系的理解確實(shí)淺薄。今天發(fā)表這篇主要是因?yàn)槲覜]預(yù)料到第一篇能有將近5000的閱讀（考慮到很多我認(rèn)真寫的技術(shù)文章閱讀不過百，5000閱讀數(shù)已經(jīng)是我的人生巔峰了），其次是今年三月份有個(gè)讀者評論讓我續(xù)寫。所以我就把之前寫的這篇加上這兩年的思考重新整理了一下。望各位喜歡。

上一篇提到，前后端合作開發(fā)的時(shí)候需要用到接口文檔。那么本篇就說說接口文檔在產(chǎn)品中究竟有什么作用。

約束

假如你的項(xiàng)目中有若干前端和若干后端。你現(xiàn)在需要開發(fā)一個(gè)登陸接口，通常情況下這個(gè)功能一個(gè)前端和一個(gè)后端開發(fā)就足夠了。有些公司的后端很強(qiáng)勢，因此可能出現(xiàn)后端寫好接口之后告訴前端去開發(fā)頁面。也可能前端很強(qiáng)勢，因此前端寫好頁面之后讓后端去寫接口。

這兩種情況都不是我們希望見到的。這是因?yàn)槿绻覀冏杂砷_發(fā)一個(gè)接口，后端開發(fā)人員通常會(huì)選擇最符合后端直覺的方式去寫接口。反過來，對于前端開發(fā)人員來說，他們一定會(huì)選擇最容易展示的方式去寫頁面。這兩種直覺之間是會(huì)有差異的，因此這樣的一方主導(dǎo)開發(fā)的情況很容易出現(xiàn)各種各樣的意外情況。

所以為了避免這樣的情況，我們需要接口文檔來約束前后端的協(xié)同開發(fā)。

規(guī)范

我的職位是Java后端開發(fā)，不過實(shí)際工作中也會(huì)寫很多前端頁面。雖然技術(shù)上是前后端分離的，但是對于我來說，其實(shí)是一起開發(fā)的。既然自己開發(fā)前后端，肯定會(huì)了解前后端各自的特點(diǎn)，那么就不會(huì)因?yàn)殚_發(fā)思路的差異而導(dǎo)致出現(xiàn)意外。那么對于我來說，是不是接口文檔就沒必要存在了呢？
答案顯然是否定的。接口文檔的另一個(gè)重要作用就是規(guī)范。
項(xiàng)目需求變動(dòng)是很常見的情況，舉個(gè)例子，我們現(xiàn)在有一個(gè)學(xué)生表。頁面上需要用一個(gè)表格展示所有的學(xué)生，可以分頁操作。
假設(shè)現(xiàn)在的接口文檔是這樣的：

學(xué)生表

然后需求變動(dòng)了，我們需要把學(xué)生表展示為教師表。

image.png

這兩個(gè)接口從后臺(tái)邏輯來說應(yīng)該是完全一致的。唯一的差別是我們需要查不同的表。從前臺(tái)邏輯來說，這兩個(gè)除了接口不一樣，其他的分頁字段應(yīng)該是一致的。理想情況下如果一個(gè)前端開發(fā)接手這個(gè)頁面之后，完全可以不看文檔直接改API地址，然后修改頁面的填充數(shù)據(jù)就可以了。

現(xiàn)實(shí)是，很多接口的規(guī)范做的不好。這就導(dǎo)致了，邏輯相同的兩個(gè)接口，他們的查詢參數(shù)可能是不一樣的。這樣就會(huì)出現(xiàn)下面的情況：

返回內(nèi)容的更改是沒問題的，但是因?yàn)閮蓚€(gè)接口沒有規(guī)范，這就導(dǎo)致其他開發(fā)人員接手的時(shí)候不僅需要改數(shù)據(jù)的格式，也需要更改參數(shù)名。這在無形中就降低了開發(fā)效率。

另一方面，文檔健全肯定是好的。但是毫無規(guī)律，隨意編寫的文檔卻會(huì)降低開發(fā)效率。因此健全的文檔必須要配合良好的文檔規(guī)范，這樣才可以讓開發(fā)人員可以預(yù)估API返回的數(shù)據(jù)格式和請求參數(shù)。

版本回溯

基本上每個(gè)App都有一個(gè)版本號(hào)。這個(gè)版本號(hào)是代碼的版本，表示這個(gè)版本的代碼有相應(yīng)的功能。同樣的道理，文檔也需要通過版本進(jìn)行管理。每個(gè)版本的App都要有相應(yīng)版本的文檔。這樣當(dāng)項(xiàng)目需要回滾的時(shí)候我們可以馬上知道上個(gè)版本的需求。

總結(jié)

本篇沒有從教科書的層面去說項(xiàng)目文檔的作用，我是結(jié)合了自己的開發(fā)經(jīng)驗(yàn)來說一下自己對文檔的體會(huì)。跟上篇一樣，我也是從開發(fā)者的角度去理解產(chǎn)品經(jīng)理的思維。希望我自己的體會(huì)能讓產(chǎn)品經(jīng)理更了解開發(fā)者的思路。