你有沒(méi)有遇到過(guò)：

• 前端代碼剛寫(xiě)完，后端的接口又變了。
• 接口文檔永遠(yuǎn)都是不對(duì)的。
• 測(cè)試工作永遠(yuǎn)只能臨近上線(xiàn)才能開(kāi)始。

為什么前后端分離了，你比從前更痛苦?

前后端分離早已經(jīng)不是新聞，當(dāng)真正分離之后確遇到了更多問(wèn)題。要想解決現(xiàn)在的痛，就要知道痛的原因：

為什么接口會(huì)頻繁變動(dòng)?

設(shè)計(jì)之初沒(méi)有想好。 這需要提高需求的理解能力和接口設(shè)計(jì)能力。

變動(dòng)的成本較低。

德國(guó)有句諺語(yǔ)：“朝湯里吐口水。” 只有這樣，才能讓人們放棄那碗湯，停止不合理的行為。前后端同學(xué)坐在一起工作的時(shí)候效率會(huì)有提升，當(dāng)后端同學(xué)接口變化時(shí)，只需要口頭上通知一下即可，我們沒(méi)有文檔，我們很敏捷啊。沒(méi)錯(cuò)，我們需要承認(rèn)這樣配合開(kāi)發(fā)的效率會(huì)很高，但是頻繁的變動(dòng)會(huì)導(dǎo)致不斷返工，造成了另一種浪費(fèi)，這種浪費(fèi)是可以被減少，甚至是被消除的。

為什么接口文檔永遠(yuǎn)都是不對(duì)的?

接口文檔在定接口時(shí)起到一定作用，寫(xiě)完接口就沒(méi)有用了。后面接口的頻繁變化，文檔必定會(huì)永遠(yuǎn)落后于實(shí)際接口，維護(hù)文檔的帶來(lái)了一定的成本卻沒(méi)能帶來(lái)價(jià)值。除非對(duì)外提供的接口，否則文檔誰(shuí)來(lái)看呢?沒(méi)人看，用處又在哪?

有些公司干脆丟掉接口文檔，說(shuō)我們要擁抱敏捷。

所以接口文檔落后的原因在于沒(méi)有給我們帶來(lái)價(jià)值。

為什么測(cè)試工作永遠(yuǎn)只能臨近上線(xiàn)才能開(kāi)始?

一個(gè)需求，后端開(kāi)發(fā) 4 天，前端開(kāi)發(fā) 4 天，聯(lián)調(diào) 4 天，留給測(cè)試同學(xué)只有2天時(shí)間甚至更少，測(cè)不完只能帶 bug 上線(xiàn)。

在開(kāi)發(fā)階段測(cè)試同學(xué)無(wú)法介入，接口在變，前端也在變， “提測(cè)” 之前只能喝茶，“提測(cè)” 之后又忙的要命。

自動(dòng)化?想都別想，空有一身好本領(lǐng)，在 “擁抱變化” 之后只能手工測(cè)試。偶爾還要拉上前臺(tái)美眉客串一下測(cè)試小妹。手工測(cè)試枯燥乏味，乏味的工作就容易出錯(cuò)，而且還不能快速重復(fù)，無(wú)法對(duì)測(cè)試過(guò)的功能快速回歸。

怎么破?

解決以上問(wèn)題要讓接口文檔發(fā)揮價(jià)值，提高變動(dòng)接口的成本，測(cè)試盡早介入。

接口文檔發(fā)揮出價(jià)值，就要賦予契約的意義，就如同簽字畫(huà)押誰(shuí)也不許變，來(lái)約束我們只認(rèn)契約不認(rèn)人。

契約應(yīng)該由前端同學(xué)來(lái)驅(qū)動(dòng)，前后端共同協(xié)商。由于前端同學(xué)與 UX 接觸比較緊密，更了解頁(yè)面所需的數(shù)據(jù)以及整體的 User Journey，前端同學(xué)驅(qū)動(dòng)會(huì)更加合理。

契約敲定之后要幫助我們生成 Mock Server(后面我們會(huì)介紹一個(gè)工具)，前后端同學(xué)就要依照契約各自開(kāi)發(fā)。Mock Server 可暫時(shí)替代后臺(tái)服務(wù)，幫組前端開(kāi)發(fā)，同時(shí)，測(cè)試同學(xué)也可以依照契約文檔來(lái)編寫(xiě)測(cè)試腳本，使用 Mock Server 進(jìn)行腳本驗(yàn)證。

當(dāng)后端接口發(fā)生變化除了口頭通知以外必須修改契約，前端同學(xué)和測(cè)試同學(xué)才能各自修改。如此一來(lái)修改契約的成本變高，人們?cè)诙ㄆ跫s時(shí)則會(huì)更加慎重，也會(huì)促使我們提高接口的設(shè)計(jì)能力。

看到圖中沒(méi)有 “聯(lián)調(diào)” 的環(huán)節(jié)，并不是畫(huà)錯(cuò)了，而是 “聯(lián)調(diào)“ 不再是一項(xiàng)工作，在部署后只需要更改代理的配置即可。甚至使用現(xiàn)代前端框架(如，Vue 或者 React)只要在開(kāi)發(fā)時(shí)配置一下，之后都不需要調(diào)整任何代碼。

“提測(cè)” 呢?測(cè)試一直都在進(jìn)行，也就不再有一個(gè) ”提測(cè)“ 的環(huán)節(jié)，無(wú)論前后端任意一方完成開(kāi)發(fā)，測(cè)試同學(xué)都可以進(jìn)行測(cè)試。

理論終于扯完了，說(shuō)起來(lái)容易做起來(lái)難啊，需要工具來(lái)幫助我們。接口描述的工具有很多，比較知名的 Swagger 和 Raml，我個(gè)人更傾向于 Raml 。

描述工具生成文檔還不夠，還要生成 Mock Server，如果描述工具和 Mock Server 是分離又帶來(lái)了額外的工作，好在有她——raml-mocker。

raml-mocker

raml-mocker 是一個(gè)基于 Raml 使用 Nodejs 開(kāi)發(fā)的 Mock Server 工具，使用 Raml 描述接口中設(shè)置 response 的 example 指令即可，raml-mocker 會(huì)解析 Raml 文件，并啟動(dòng)一個(gè) Mock Server，將 example 的內(nèi)容返回給瀏覽器。

開(kāi)始

初始化項(xiàng)目

git clone https://github.com/xbl/raml-mocker-starter.git raml-api 
cd raml-api 
git remote rm origin 

安裝

yarn 
# or 
npm install 

啟動(dòng) mock server

yarn start 
# or 
npm start 

測(cè)試

curl -i http://localhost:3000/api/v1/users/1/books/ 
# or 
curl -i http://localhost:3000/api/v1/users/1/books/1 

生成 API 可視化文檔

yarn run build 
# or 
npm run build 

此功能使用了raml2html。

配置 .raml-config.json

{ 
  "controller": "./controller", 
  "raml": "./raml", 
  "main": "api.raml", 
  "port": 3000, 
  "plugins": [] 
} 

• controller: controller 目錄路徑，在高級(jí)篇中會(huì)有更詳細(xì)說(shuō)明
• raml: raml 文件目錄
• main: raml 目錄下的入口文件
• port: mock server 服務(wù)端口號(hào)
• plugins: 插件

入門(mén)篇：Mock Server

raml-mocker 只需要在response 添加 example:

/books: 
  /:id: 
    post: 
      body: 
        application/json: 
          type: abc 
      responses: 
        200: 
          body: 
            application/json: 
              type: song 
              # 返回的 Mock 數(shù)據(jù) 
              example: !include ./books_200.json 

books_200.json

{ 
  "code": 200, 
  "data": [ 
    { 
      "id": 1, 
      "title": "books title", 
      "description": "books desccription1" 
    }, 
    { 
      "id": 2, 
      "title": "books title", 
      "description": "books desccription2" 
    } 
  ] 
} 

通過(guò) curl 請(qǐng)求：

curl -i http://localhost:3000/api/v1/users/1/books 

就會(huì)得到 example 的數(shù)據(jù)，唯一不足是無(wú)法根據(jù)參數(shù)動(dòng)態(tài)返回不同數(shù)據(jù)。別急，請(qǐng)往下看。

高級(jí)篇：動(dòng)態(tài) Server

如果靜態(tài)的 Mock 數(shù)據(jù)不能滿(mǎn)足你的需求，Raml-mocker 還提供了動(dòng)態(tài)的功能。

在 raml 文檔中添加 (controller) 指令，即可添加動(dòng)態(tài)的 Server，如：

/books: 
  type: 
    resourceList: 
  get: 
    description: 獲取用戶(hù)的書(shū)籍 
    (controller): user#getBook 
    responses: 
      200: 
        body: 
          type: song[] 
          example: !include ./books_200.json 

在文檔中 (controller) 表示 controller 目錄下 user.js 中 getBook 函數(shù)。

controller/user.js

exports.getBook = (req, res, webApi) => { 
  console.log(webApi); 
  res.send('Hello World!'); 
} 

Raml-mocker 是在 expressjs 基礎(chǔ)上進(jìn)行開(kāi)發(fā)，req、res 可以參考 express 文檔。

webApi 會(huì)返回文檔中的配置：

{ 
  "absoluteUri": "/api/:version/users/:user_id/books", 
  "method": "get", 
  "controller": "user#getBook", 
  "responses": [ 
    { 
      "code": "200", 
      "body": "... example ...", 
      "mimeType": "application/json" 
    } 
  ] 
} 

如此，raml-mocker 提供了更多可擴(kuò)展空間，我們甚至可以在 controller 中實(shí)現(xiàn)一定的邏輯。

插件

Raml-mocker 提供了插件機(jī)制，允許我們?cè)诓皇褂?controller 指令的時(shí)候?qū)?response 的內(nèi)容進(jìn)行處理，例如使用 Mockjs。

.raml-config.json

{ 
  "controller": "./controller", 
  "raml": "./raml", 
  "main": "api.raml", 
  "port": 3000, 
  "plugins": ["./plugins/mock.js"] 
} 

./plugins/mock.js

var { mock } = require('mockjs'); 
 
module.exports = (body) => { 
  try { 
    return mock(JSON.parse(body)); 
  } catch(e) {} 
  return body; 
} 

總結(jié)

前后端分離可以讓我們的職責(zé)更清晰，打破前端發(fā)揮的局限，工作解耦之后能更好的提高開(kāi)發(fā)效率。然而因?yàn)闆](méi)有規(guī)劃好開(kāi)發(fā)流程，導(dǎo)致了我們沒(méi)有發(fā)揮出其應(yīng)有的價(jià)值，造成了更多的浪費(fèi)。

raml-mocker 能夠幫助我們?cè)诠ぞ呱辖鉀Q一定的問(wèn)題，更重要的是持續(xù)改進(jìn)的思想，只有團(tuán)隊(duì)的思想是統(tǒng)一的才有可能達(dá)到快速交付。

希望能對(duì)你有所幫助，謝謝!