koa-restql 已經(jīng)在 github 開源并在 npm 發(fā)布。感興趣的同學(xué)可以前往圍觀一下。歡迎 Pull Request，同時熱烈歡迎 Star。

在現(xiàn)代的業(yè)務(wù)系統(tǒng)中，后端開發(fā)工作基本上可以被拆分為三項(xiàng)：

• 接口鑒權(quán)。例如判斷是不是當(dāng)前系統(tǒng)的用戶，以及該用戶是否有權(quán)限訪問接口。
• 與其他系統(tǒng)的交互。例如調(diào)用第三方的服務(wù)，或內(nèi)部搭建的其他服務(wù)。
• 數(shù)據(jù)操作。基本上所有需要持久化存儲的系統(tǒng)都會在這項(xiàng)工作上耗費(fèi)大量時間。

本文將介紹如何利用 RestQL 來非常有效地減少「數(shù)據(jù)操作」相關(guān)的工作量。

現(xiàn)狀與挑戰(zhàn)

我們先來做個假設(shè)。

• 假設(shè)系統(tǒng)中有 60 張表，每張表對應(yīng)的接口都要有四種 CRUD 的 API。那么就需要后端工程師寫60 * 4 = 240個API。
• 假設(shè)上述 60 張表中，40 張表存的是資源類的數(shù)據(jù)，其余 20 張表為關(guān)系類的數(shù)據(jù)，也就是說每張表和 20 張表都要進(jìn)行關(guān)聯(lián)，每個關(guān)聯(lián)也需要四種 CRUD 操作，那么又要增加40 * 20 * 4 = 3200個API。

所以在上述假設(shè)場景中，后端工程師要編寫 3200 + 240 = 3440 個 API。而且這還不是全部，假如后端代碼需要 100% 的測試覆蓋，那么工程師們就要寫至少 3440 個測試！

60 張表 = 3440 個 API + 3440 個單元測試

眾所周知，數(shù)據(jù)操作 API 的實(shí)現(xiàn)過程基本上是重復(fù)的，有的同學(xué)甚至認(rèn)為這是低端的，體現(xiàn)不出工程師價值的工作，純粹的「體力活」。但是卻沒有一個能真正解放生產(chǎn)力的方案。

解決思路

盡管我們把數(shù)據(jù)庫抽象成了「關(guān)系型」數(shù)據(jù)庫，把操作數(shù)據(jù)的命令抽象成了 SQL ，同時我們也有了 MySQL 客戶端，甚至是 sequelize 這種非常方便的庫，也有「RESTful」API 命名規(guī)則，但是接口的實(shí)現(xiàn)從來都是需要工程師們自己用手敲出來的。

如果說我看得比別人遠(yuǎn)，那是因?yàn)槲艺驹诰奕说募绨蛏稀?/p>

所以我們在現(xiàn)有的技術(shù)基礎(chǔ)上再抽象，把已有的東西重新組合起來，拼裝成一個新的工具，幫助工程師從「體力活」中解脫出來，解放生產(chǎn)力。

什么樣的工具

最開始的時候，我們最先需要明確的問題就是：「我們需要什么樣的工具？」或者說「這種工具要幫我們解決什么問題？」。

實(shí)際上我們從剛才的假設(shè)中，已經(jīng)可以得出結(jié)論：我們希望有一個工具可以讓工程師免于編寫數(shù)據(jù)操作 API，把數(shù)據(jù)庫操作直接映射到 HTTP RESTful API 上。

調(diào)用方式

如何請求

為了解釋「如何請求」，我們先從一些公認(rèn)的規(guī)則出發(fā)，舉一個例子，然后再從例子中抽象出一些規(guī)則。

注意：為了更便于理解，我們把所有的命名從客戶端一直穿透到數(shù)據(jù)庫，所以請不要糾結(jié)于我們在定義一個 API 時名詞單復(fù)數(shù)的問題。

基本用例

幾乎所有的系統(tǒng)都會有一個用戶表（user）。根據(jù) RESTful 規(guī)則的約定，我們應(yīng)該把訪問 user 表的 API 路徑定義為 /user，并把 CRUD 的訪問方法映射到 HTTP 協(xié)議中的四種方法：GET、POST、PUT、DELETE。

比如：

• GET /user：獲取用戶列表，應(yīng)該返回一個數(shù)組。
• GET /user/:id：獲取指定的用戶，應(yīng)該返回一個對象。
• POST /user：創(chuàng)建一個用戶，應(yīng)該返回被存儲的對象，狀態(tài)碼應(yīng)該為 201(Created)。
• PUT /user：修改一個用戶的信息，應(yīng)該返回修改后的對象。
• DELETE /user/:id：刪除一個用戶，狀態(tài)碼應(yīng)該為 204(No Content)。

如果 user 表有一個關(guān)系表 feed，那么我們的路徑就會再復(fù)雜一點(diǎn)：

• GET /user/:id/feed 或 GET /feed?user_id=:id：獲取某個用戶的帖子，應(yīng)該返回一個數(shù)組。
• GET /user/:id/feed/:feed_id 或 GET /feed/:id：獲取指定的帖子，應(yīng)該返回一個對象。

上述的例子中還會衍生出其他的數(shù)據(jù)操作，不僅僅只有 GET，這里不一一列舉了。

抽象出規(guī)則

上一節(jié)中，列舉了要提供一個表的數(shù)據(jù)訪問 API，大概要實(shí)現(xiàn)哪些路由。從這些枚舉中，可以找出其中的規(guī)律，總結(jié)出一套規(guī)則。最終我們在「把能實(shí)現(xiàn)的路由，全部實(shí)現(xiàn)」的原則基礎(chǔ)上，開發(fā)了 RestQL 的 koa 版本。

支持的 HTTP 方法：

HTTP verbCRUD

GET	Read
POST	Create
PUT	Create/Update
DELETE	Delete

支持的帶有 body 的 HTTP 方法：

HTTP verbListSingle

POST	Array/Object	×
PUT	Array/Object	Object

說明：

• List 路徑為返回值為數(shù)組的路徑，包括：
  • /resource
  • /resource/:id/association, association 為 1:n 關(guān)系
  • /resource/:id/association, association 為 n:m 關(guān)系
• Single 路徑為返回值為單個對象的路徑，包括：
  • /resource/:id
  • /resource/:id/association, association 為 1:1 關(guān)系
  • /resource/:id/association/:id, association 為 1:n 關(guān)系
  • /resource/:id/association/:id, association 為 n:m 關(guān)系

如何使用

我們已經(jīng)開源了 koa-restql，koa 應(yīng)用開發(fā)者可以通過 npm 安裝它：

npm install koa-restql

然后在 koa 應(yīng)用的代碼中引用 RestQL：

const koa = require('koa') const RestQL = require('koa-restql')let app = koa() // Build APIs from `sequelize.models` let restql = new RestQL(sequelize.models) app.use(restql.routes())

常見問題

修改參數(shù)

用戶可以通過querystring來修改參數(shù)。強(qiáng)烈建議使用qs對 querystring 進(jìn)行解析，例如：

qs.stringify({a: 1, b:2}) // => a=1&b=2

RestQL 中的querystring僅有 3 條規(guī)則：

• 所有不以_開頭的鍵，都會被放進(jìn)sequelize#query()的where參數(shù)中。例如：

  // query {name: "Li Xin" } // option for sequelize {where: {name: "Li Xin"} }

• 所有以_開頭的鍵，都會被放進(jìn)sequelize#query()的參數(shù)中，和where保持平級。例如：

  // query {_limit: 10 } // option for sequelize {limit: 10 }

• 當(dāng)需要使用關(guān)系時，可以用關(guān)系名稱的字符串代替關(guān)系對象傳入。例如需要使用include時：

  // query {_include: ['friends'] } // option for sequelize {include: [models.user.association.friends] }

訪問控制

通常來說，我們有兩種方法實(shí)現(xiàn)訪問控制：

通過中間件

在 koa 應(yīng)用掛載 RestQL 的 router 之前，可以實(shí)現(xiàn)一個鑒權(quán)中間件，控制用戶的訪問權(quán)限：

app.use(authorizeMiddleware) app.use(restql.routes())

通過 restql 參數(shù)

在使用sequelize定義關(guān)聯(lián)時，我們可以設(shè)定restql參數(shù)，實(shí)現(xiàn)訪問控制。例如：

• 禁止通過restql訪問關(guān)聯(lián)：

  models.user.hasOne(models.privacy,{restql: {ignore: true}} )

• 禁止通過restql使用指定的 HTTP 方法訪問關(guān)聯(lián)

  models.user.hasOne(models.privacy,{restql: {ignore: ['get']}} )

其他語言/框架

目前我們僅實(shí)現(xiàn)了基于node和koa的版本，還沒有其他語言/框架的實(shí)現(xiàn)版本。歡迎開發(fā)者提交其他語言/框架的實(shí)現(xiàn)到 RestQL 組。

參考鏈接

• GitHub, https://github.com/koajs/koa
• GitHub, https://github.com/sequelize/sequelize
• GitHub, [meituan-dianping/koa-restql][https://github.com/Meituan-Dianping/koa-restql]

總結(jié)

以上是生活随笔為你收集整理的RestQL：现代化的 API 开发方式的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。