原文位址： How to build an RPC based API with node.js

原文作者： Alloys Mila

譯文出自：阿裡雲翻譯小組

譯文連結： https://github.com/dawn-teams/translate/blob/master/articles/How-to-build-an-rpc-based-api-with-nodejs.md

譯者：牧曈

校對者：也樹，靈沼

如何使用 NodeJS 建構基于 RPC 的 API 系統

API 在它存在的很長時間内都不斷地侵蝕着我們的開發工作。無論是建構僅供其他微服務通路的微服務還是建構對外暴露的服務，你都需要開發 API。

目前，大多數 API 都基于 REST 規範，REST 規範通俗易懂，并且建立在 HTTP 協定之上。但是在很大程度上，REST 可能并不适合你。許多公司比如 Uber，facebook，Google，netflix 等都建構了自己的服務間内部通信協定，這裡的關鍵問題在于何時做，而不是應不應該做。

假設你想使用傳統的 RPC 方式，但是你仍然想通過 http 格式傳遞 json 資料，這時要怎麼通過 node.js 來實作呢？請繼續閱讀本文。

閱讀本教程前應確定以下兩點

你至少應該具備 Node.js 的實戰經驗
為了獲得 ES6 支援，需要安裝 Node.js v4.0.0 以上版本。

設計原則

在本教程中，我們将為 API 設定如下兩個限制：

保持簡單（沒有外部包裝和複雜的操作）
API 和接口文檔，應該一同編寫

現在開始

本教程的完整源代碼可以在

Github

上找到，是以你可以 clone 下來友善檢視。

首先，我們需要首先定義類型以及将對它們進行操作的方法（這些将是通過 API 調用的相同方法）。

建立一個新目錄，并在新目錄中建立兩個檔案，

types.js

和

methods.js

。如果你正在使用 linux 或 mac 終端，可以鍵入以下指令。

mkdir noderpc && cd noderpc
touch types.js methods.js

在

types.js

檔案中，輸入以下内容。

'use strict';

let types = {
    user: {
        description:'the details of the user',
        props: {
            name:['string', 'required'],
            age: ['number'],
            email: ['string', 'required'],
            password: ['string', 'required']
        }
    },
    task: {
        description:'a task entered by the user to do at a later time',
        props: {
            userid: ['number', 'required'],
            content: ['string', 'require'],
            expire: ['date', 'required']
        }
    }
}

module.exports = types;

乍一看很簡單，用一個

key-value

對象來儲存我們的類型，

key

是類型的名稱，

value

是它的定義。該定義包括描述（是一段可讀文本，主要用于生成文檔），在 props 中描述了各個屬性，這樣設計主要用于文檔生成和驗證，最後通過

module.exports

暴露出來。

methods.js

有以下内容。

'use strict';

let db = require('./db');

let methods = {
    createUser: {
        description: `creates a new user, and returns the details of the new user`,
        params: ['user:the user object'],
        returns: ['user'],
        exec(userObj) {
            return new Promise((resolve) => {
                if (typeof (userObj) !== 'object') {
                    throw new Error('was expecting an object!');
                }
                // you would usually do some validations here
                // and check for required fields

                // attach an id the save to db
                let _userObj = JSON.parse(JSON.stringify(userObj));
                _userObj.id = (Math.random() * 10000000) | 0; // binary or, converts the number into a 32 bit integer
                resolve(db.users.save(userObj));
            });
        }
    },

    fetchUser: {
        description: `fetches the user of the given id`,
        params: ['id:the id of the user were looking for'],
        returns: ['user'],
        exec(userObj) {
            return new Promise((resolve) => {
                if (typeof (userObj) !== 'object') {
                    throw new Error('was expecting an object!');
                }
                // you would usually do some validations here
                // and check for required fields

                // fetch
                resolve(db.users.fetch(userObj.id) || {});
            });
        }
    },

     fetchAllUsers: {
        released:false;
        description: `fetches the entire list of users`,
        params: [],
        returns: ['userscollection'],
        exec() {
            return new Promise((resolve) => {
                // fetch
                resolve(db.users.fetchAll() || {});
            });
        }
    },

};

module.exports = methods;

可以看到，它和類型子產品的設計非常類似，但主要差別在于每個方法定義中都包含一個名為

exec

的函數，它傳回一個

Promise

。這個函數暴露了這個方法的功能，雖然其他屬性也暴露給了使用者，但這必須通過 API 抽象。

db.js

我們的 API 需要在某處存儲資料，但是在本教程中，我們不希望通過不必要的

npm install

使教程複雜化，我們建立一個非常簡單、原生的記憶體中鍵值存儲，因為它的資料結構由你自己設計，是以你可以随時改變資料的存儲方式。

db.js

中包含以下内容。

'use strict';

let users = {};
let tasks = {};

// we are saving everything inmemory for now
let db = {
    users: proc(users),
    tasks: proc(tasks)
}

function clone(obj) {
    // a simple way to deep clone an object in javascript
    return JSON.parse(JSON.stringify(obj));
}

// a generalised function to handle CRUD operations
function proc(container) {
    return {
        save(obj) {
            // in JS, objects are passed by reference
            // so to avoid interfering with the original data
            // we deep clone the object, to get our own reference
            let _obj = clone(obj);

            if (!_obj.id) {
                // assign a random number as ID if none exists
                _obj.id = (Math.random() * 10000000) | 0;
            }

            container[_obj.id.toString()] = _obj;
            return clone(_obj);
        },
        fetch(id) {
            // deep clone this so that nobody modifies the db by mistake from outside
            return clone(container[id.toString()]);
        },
        fetchAll() {
            let _bunch = [];
            for (let item in container) {
                _bunch.push(clone(container[item]));
            }
            return _bunch;
        },
        unset(id) {
            delete container[id];
        }
    }
}

module.exports = db;

其中比較重要是

proc

函數。通過擷取一個對象，并将其包裝在一個帶有一組函數的閉包中，友善在該對象上添加，編輯和删除值。如果你對閉包不夠了解，應該提前閱讀關于

JavaScript

閉包的内容。

是以，我們現在基本上已經完成了程式功能，我們可以存儲和檢索資料，并且可以實作對這些資料進行操作，我們現在需要做的是通過網絡公開這個功能。是以，最後一部分是實作 HTTP 服務。

這是我們大多數人希望使用express的地方，但我們不希望這樣，是以我們将使用随節點一起提供的http子產品，并圍繞它實作一個非常簡單的路由表。

正如預期的那樣，我們繼續建立

server.js

檔案。在這個檔案中我們把所有内容關聯在一起，如下所示。

'use strict';

let http = require('http');
let url = require('url');
let methods = require('./methods');
let types = require('./types');

let server = http.createServer(requestListener);
const PORT = process.env.PORT || 9090;

檔案的開頭部分引入我們所需要的内容，使用

http.createServer

來建立一個 HTTP 服務。

requestListener

是一個回調函數，我們稍後定義它。并且我們确定下來伺服器将偵聽的端口。

在這段代碼之後我們來定義路由表，它規定了我們的應用程式将響應的不同 URL 路徑。

// we'll use a very very very simple routing mechanism
// don't do something like this in production, ok technically you can...
// probably could even be faster than using a routing library :-D

let routes = {
    // this is the rpc endpoint
    // every operation request will come through here
    '/rpc': function (body) {
        return new Promise((resolve, reject) => {
            if (!body) {
                throw new (`rpc request was expecting some data...!`);
            }
            let _json = JSON.parse(body); // might throw error
            let keys = Object.keys(_json);
            let promiseArr = [];

            for (let key of keys) {
                if (methods[key] && typeof (methods[key].exec) === 'function') {
                    let execPromise = methods[key].exec.call(null, _json[key]);
                    if (!(execPromise instanceof Promise)) {
                        throw new Error(`exec on ${key} did not return a promise`);
                    }
                    promiseArr.push(execPromise);
                } else {
                    let execPromise = Promise.resolve({
                        error: 'method not defined'
                    })
                    promiseArr.push(execPromise);
                }
            }

            Promise.all(promiseArr).then(iter => {
                console.log(iter);
                let response = {};
                iter.forEach((val, index) => {
                    response[keys[index]] = val;
                });

                resolve(response);
            }).catch(err => {
                reject(err);
            });
        });
    },

    // this is our docs endpoint
    // through this the clients should know
    // what methods and datatypes are available
    '/describe': function () {
        // load the type descriptions
        return new Promise(resolve => {
            let type = {};
            let method = {};

            // set types
            type = types;

            //set methods
            for(let m in methods) {
                let _m = JSON.parse(JSON.stringify(methods[m]));
                method[m] = _m;
            }

            resolve({
                types: type,
                methods: method
            });
        });
    }
};

這是整個程式中非常重要的一部分，因為它提供了實際的接口。我們有一組 endpoint，每個 endpoint 都對應一個處理函數，在路徑比對時被調用。根據設計原則每個處理函數都必須傳回一個 Promise。

RPC endpoint 擷取一個包含請求内容的 json 對象，然後将每個請求解析為

methods.js

檔案中的對應方法，調用該方法的

exec

函數，并将結果傳回，或者抛出錯誤。

describe endpoint 掃描方法和類型的描述，并将該資訊傳回給調用者。讓使用 API 的開發者能夠輕松地知道如何使用它。

現在讓我們添加我們之前讨論過的函數

requestListener

，然後就可以啟動服務。

// request Listener
// this is what we'll feed into http.createServer
function requestListener(request, response) {
    let reqUrl = `http://${request.headers.host}${request.url}`;
    let parseUrl = url.parse(reqUrl, true);
    let pathname = parseUrl.pathname;

    // we're doing everything json
    response.setHeader('Content-Type', 'application/json');

    // buffer for incoming data
    let buf = null;

    // listen for incoming data
    request.on('data', data => {
        if (buf === null) {
            buf = data;
        } else {
            buf = buf + data;
        }
    });

    // on end proceed with compute
    request.on('end', () => {
        let body = buf !== null ? buf.toString() : null;

        if (routes[pathname]) {
            let compute = routes[pathname].call(null, body);

            if (!(compute instanceof Promise)) {
                // we're kinda expecting compute to be a promise
                // so if it isn't, just avoid it

                response.statusCode = 500;
                response.end('oops! server error!');
                console.warn(`whatever I got from rpc wasn't a Promise!`);
            } else {
                compute.then(res => {
                    response.end(JSON.stringify(res))
                }).catch(err => {
                    console.error(err);
                    response.statusCode = 500;
                    response.end('oops! server error!');
                });
            }

        } else {
            response.statusCode = 404;
            response.end(`oops! ${pathname} not found here`)
        }
    })
}

// now we can start up the server
server.listen(PORT);

每當有新請求時調用此函數并等待拿到資料，之後檢視路徑，并根據路徑比對到路由表上的對應處理方法。然後使用

server.listen

啟動服務。

現在我們可以在目錄下運作

node server.js

來啟動服務，然後使用 postman 或你熟悉的 API 調試工具，向

http://localhost{PORT}/rpc

發送請求，請求體中包含以下 JSON 内容。

{
    "createUser": {
        "name":"alloys mila",
        "age":24
    }
}

server 将會根據你送出的請求建立一個新使用者并傳回響應結果。一個基于 RPC、文檔完善的 API 系統已經搭建完成了。

注意，我們尚未對本教程接口進行任何參數驗證，你在調用測試的時候必須手動保證資料正确性。

如何使用 NodeJS 建構基于 RPC 的 API 系統如何使用 NodeJS 建構基于 RPC 的 API 系統

如何使用 NodeJS 建構基于 RPC 的 API 系統

設計原則

現在開始

db.js

繼續閱讀

nodejs微信開發---授權登入+擷取使用者資訊微信網頁授權

debian9更新4.9.0核心到4.19.2核心過程

Javascript建構Bingo卡片遊戲

JavaScript的那些坑之事件代理事件代理事件階段

javascript的for (var i in data)慎用javascript中的for (var i in data)謹慎用

tab滑鼠經過菜單切換

vue （vue2.0）使用總結(從大體結構總結)

vue搭建過程及出現問題

/\B(?=(?:\d{3})+$)/g 一條令人費解的正規表達式

适用于JavaScript的ECMAScript 2020規範向前發展

JS生成uuid的四種方法

vue-cli簡介（中文翻譯）

Ajax發送和擷取json資料到Spring mvc 1.spring mvc後端2.web前段

layui多任務上傳添加進度條

JSONObject包導入異常 java.lang.NoClassDefFoundErrorweb項目的導入包的問題