如何在前端中使用protobuf（vue篇）

摘要： 由於目前公司採用了ProtoBuf做前後端資料互動，進公司以來一直用的是公司大神寫好的基礎庫，完全不瞭解底層是如何解析的，一旦報錯只能求人，作為一隻還算有鑽研精神的猿，應該去了解一下底層的實現，在這裡記錄一下學習過程。 Protobuf簡單介紹 Google Protocol Buff...

由於目前公司採用了ProtoBuf做前後端資料互動，進公司以來一直用的是公司大神寫好的基礎庫，完全不瞭解底層是如何解析的，一旦報錯只能求人，作為一隻還算有鑽研精神的猿，應該去了解一下底層的實現，在這裡記錄一下學習過程。

Protobuf簡單介紹

Google Protocol Buffer(簡稱 Protobuf)是一種輕便高效的結構化資料儲存格式，平臺無關、語言無關、可擴充套件，可用於通訊協議和資料儲存等領域。

個人感受： 前後端資料傳輸用json還是protobuf其實對開發來說沒啥區別，protobuf最後還是要解析成json才能用。個人覺得比較好的幾點是：

• 1.前後端都可以直接在專案中使用protobuf，不用再額外去定義model；
• 2.protobuf可以直接作為前後端資料和介面的文件，大大減少了溝通成本；

沒有使用protobuf之前，後端語言定義的介面和欄位，前端是不能直接使用的，前後端溝通往往需要維護一份介面文件，如果後端欄位有改動，需要去修改文件並通知前端，有時候文件更新不及時或容易遺漏，溝通成本比較大。 使用protobuf後，protobuf檔案由後端統一定義， protobuf直接可以作為文件 ，前端只需將protobuf檔案拷貝進前端專案即可。如果後端欄位有改動，只需通知前端更新protobuf檔案即可，因為後端是直接使用了protobuf檔案，因此protobuf檔案一般是不會出現遺漏或錯誤的。長此以往，團隊合作效率提升是明顯的。

廢話了一大堆，下面進入正題。 我這裡講的主要是在vue中的使用，是目前本人所在的公司專案實踐，大家可以當做參考。

思路

前端中需要使用 IO%2Fprotobuf.js" rel="nofollow,noindex">protobuf.js 這個庫來處理proto檔案。

protobuf.js 提供了幾種方式來處理proto。

protobuf.load("awesome.proto", function(err, root) {...})
protobuf.load("awesome.json", function(err, root) {...})

眾所周知，vue專案build後生成的dist目錄中只有html,css,js,images等資源，並不會有 .proto 檔案的存在，因此需要用 protobuf.js 這個庫將 *.proto 處理成 *.js 或 *.json ，然後再利用庫提供的方法來解析資料，最後得到資料物件。

PS: 實踐發現，轉化為js檔案會更好用一些，轉化後的js檔案直接在原型鏈上定義了一些方法，非常方便。因此後面將會是使用這種方法來解析proto。

預期目標

在專案中封裝一個 request.js 模組,希望能像下面這樣使用，呼叫api時只需指定請求和響應的model，然後傳遞請求引數，不需關心底層是如何解析proto的，api返回一個Promise物件：

// /api/student.js 定義介面的檔案
import request from '@/lib/request'

// params是object型別的請求引數
// school.PBStudentListReq 是定義好的請求體model
// school.PBStudentListRsp 是定義好的響應model
// getStudentList 是介面名稱
export function getStudentList (params) {
const req = request.create('school.PBStudentListReq', params)
return request('getStudentList', req, 'school.PBStudentListRsp')
}

// 在HelloWorld.vue中使用
import { getStudentList } from '@/api/student'
export default {
name: 'HelloWorld',
created () {

},
methods: {
_getStudentList () {
const req = {
limit = 20,
offset = 0
}
getStudentList(req).then((res) => {
console.log(res)
}).catch((res) => {
console.error(res)
})
}
}
}
複製程式碼

準備工作

1.拿到一份定義好的proto檔案。

雖然語法簡單，但其實前端不用怎麼關心如何寫proto檔案，一般都是由後端來定義和維護。在這裡大家可以直接用一下我定義好的一份 demo 。

// User.proto
package framework;
syntax = "proto3";

message PBUser {
uint64 user_id = 0;
string name = 1;
string mobile = 2;
}

// Class.proto
package school;
syntax = "proto3";

message PBClass {
uint64 classId = 0;
string name = 1;
}

// Student.proto
package school;
syntax = "proto3";

import "User.proto";
import "Class.proto";

message PBStudent {
uint64 studentId = 0;
PBUser user = 1;
PBClass class = 2;
PBStudentDegree degree = 3;
}

enum PBStudentDegree {
PRIMARY = 0;// 小學生
MIDDLE = 1;// 中學生
SENIOR = 2;// 高中生
COLLEGE = 3;// 大學生
}

message PBStudentListReq {
uint32 offset = 1;
uint32 limit = 2;
}

message PBStudentListRsp {
repeated PBStudent list = 1;
}



// MessageType.proto
package framework;
syntax = "proto3";
// 公共請求體
message PBMessageRequest {
uint32 type = 1;// 訊息型別
bytes messageData = 2;// 請求資料
uint64 timestamp = 3;// 客戶端時間戳
string version = 4;// api版本號

string token = 14;// 使用者登入後伺服器返回的 token，用於登入校驗
}

// 訊息響應包
message PBMessageResponse {
uint32 type = 3;// 訊息型別
bytes messageData = 4;// 返回資料

uint32 resultCode = 6;// 返回的結果碼
string resultInfo = 7;// 返回的結果訊息提示文字（用於錯誤提示）
}
// 所有的介面
enum PBMessageType {
// 學生相關
getStudentList = 0;// 獲取所有學生的列表, PBStudentListReq => PBStudentListRsp
}
複製程式碼

其實不用去學習proto的語法都能一目瞭然。這裡有兩種名稱空間 framework 和 school ， PBStudent 引用了 PBUser ，可以認為 PBStudent 繼承了 PBUser 。

一般來說，前後端需要統一約束一個請求model和響應model，比如請求中哪些欄位是必須的，返回體中又有哪些欄位，這裡用 MessageType.proto 的 PBMessageRequest 來定義請求體所需欄位， PBMessageResponse 定義為返回體的欄位。

PBMessageType 是介面的列舉，後端所有的介面都寫在這裡，用註釋表示具體請求引數和返回引數型別。比如這裡只定義了一個介面 getStudentList 。

拿到後端提供的這份 *.proto 檔案後，是不是已經可以基本瞭解到：有一個 getStudentList 的介面，請求引數是 PBStudentListReq ，返回的引數是 PBStudentListRsp 。

所以說proto檔案可以直接作為前後端溝通的文件。

步驟

1.新建一個vue專案

同時新增安裝 axios 和 protobufjs 。

# vue create vue-protobuf
# npm install axios protobufjs --save-dev
複製程式碼

2.在 src 目錄下新建一個 proto 目錄，用來存放 *.proto 檔案,並將寫好的proto檔案拷貝進去。

此時的專案目錄和 package.json ：

3.將 *.proto 檔案生成 src/proto/proto.js （重點）

protobufjs 提供了一個叫 pbjs 的工具，這是一個神器，根據引數不同可以打包成xx.json或xx.js檔案。比如我們想打包成json檔案，在根目錄執行：

npx pbjs -t json src/proto/*.proto > src/proto/proto.json
複製程式碼

可以在 src/proto 目錄下生成一個proto.json檔案，檢視請點選這裡。 之前說了：實踐證明打包成js模組才是最好用的。我這裡直接給出最終的命令

npx pbjs -t json-module -w commonjs -o src/proto/proto.jssrc/proto/*.proto
複製程式碼

-w 引數可以指定打包js的包裝器，這裡用的是commonjs，詳情請各位自己去看文件。執行命令後在src/proto目錄下生成的 proto.js 。在chrome中 console.log(proto.js) 一下:

可以發現，這個模組在原型鏈上定義了 load , lookup

等非常有用的api，這正是後面我們將會用到的。 為以後方便使用，我們將命令新增到package.json的script中：

"scripts": {
"serve": "vue-cli-service serve",
"build": "vue-cli-service build",
"lint": "vue-cli-service lint",
"proto": "pbjs -t json-module -w commonjs -o src/proto/proto.jssrc/proto/*.proto"
},
複製程式碼

以後更新proto檔案後，只需要 npm run proto 即可重新生成最新的proto.js。

4. 封裝request.js

在前面生成了proto.js檔案後，就可以開始封裝與後端互動的基礎模組了。首先要知道，我們這裡是用axios來發起http請求的。

整個流程：開始呼叫介面 -> request.js將資料變成二進位制 -> 前端真正發起請求 -> 後端返回二進位制的資料 -> request.js處理二進位制資料 -> 獲得資料物件。

可以說request.js相當於一個加密解密的中轉站。在 src/lib 目錄下新增一個 request.js 檔案,開始開發：

既然我們的介面都是二進位制的資料，所以需要設定axios的請求頭，使用arraybuffer，如下：

import axios from 'axios'
const httpService = axios.create({
timeout: 45000,
method: 'post',
headers: {
'X-Requested-With': 'XMLHttpRequest',
'Content-Type': 'application/octet-stream'
},
responseType: 'arraybuffer'
})
複製程式碼

MessageType.proto 裡面定義了與後端約定的介面列舉、請求體、響應體。發起請求前需要將所有的請求轉換為二進位制，下面是request.js的主函式

import protoRoot from '@/proto/proto'
import protobuf from 'protobufjs'

// 請求體message
const PBMessageRequest = protoRoot.lookup('framework.PBMessageRequest')
// 響應體的message
const PBMessageResponse = protoRoot.lookup('framework.PBMessageResponse')

const apiVersion = '1.0.0'
const token = 'my_token'

function getMessageTypeValue(msgType) {
const PBMessageType = protoRoot.lookup('framework.PBMessageType')
const ret = PBMessageType.values[msgType]
return ret
}

/**
 * 
 * @param {*} msgType 介面名稱
 * @param {*} requestBody 請求體引數
 * @param {*} responseType 返回值
 */
function request(msgType, requestBody, responseType) { 
// 得到api的列舉值
const _msgType = getMessageTypeValue(msgType)

// 請求需要的資料
const reqData = {
timeStamp: new Date().getTime(),
type: _msgType,
version: apiVersion,
messageData: requestBody,
token: token
}
}
// 將物件序列化成請求體例項
const req = PBMessageRequest.create(reqData)

// 呼叫axios發起請求
// 這裡用到axios的配置項：transformRequest和transformResponse
// transformRequest 發起請求時，呼叫transformRequest方法，目的是將req轉換成二進位制
// transformResponse 對返回的資料進行處理，目的是將二進位制轉換成真正的json資料
return httpService.post('/api', req, {
transformRequest,
transformResponse: transformResponseFactory(responseType)
}).then(({data, status}) => {
// 對請求做處理
if (status !== 200) {
const err = new Error('伺服器異常')
throw err
}
console.log(data)
},(err) => {
throw err
})
}
// 將請求資料encode成二進位制，encode是proto.js提供的方法
function transformRequest(data) {
return PBMessageRequest.encode(data).finish()
}

function isArrayBuffer (obj) {
return Object.prototype.toString.call(obj) === '[object ArrayBuffer]'
}

function transformResponseFactory(responseType) {
return function transformResponse(rawResponse) {
// 判斷response是否是arrayBuffer
if (rawResponse == null || !isArrayBuffer(rawResponse)) {
return rawResponse
}
try {
const buf = protobuf.util.newBuffer(rawResponse)
// decode響應體
const decodedResponse = PBMessageResponse.decode(buf)
if (decodedResponse.messageData && responseType) {
const model = protoRoot.lookup(responseType)
decodedResponse.messageData = model.decode(decodedResponse.messageData)
}
return decodedResponse
} catch (err) {
return err
}
}
}

// 在request下新增一個方法，方便用於處理請求引數
request.create = function (protoName, obj) {
const pbConstruct = protoRoot.lookup(protoName)
return pbConstruct.encode(obj).finish()
}

// 將模組暴露出去
export default request
複製程式碼

最後寫好的具體程式碼請看： request.js 。 其中用到了 lookup() , encode() , finish() , decode() 等幾個proto.js提供的方法。

5. 呼叫request.js

在.vue檔案直接呼叫api前，我們一般不直接使用request.js來直接發起請求，而是將所有的介面再封裝一層，因為直接使用request.js時要指定請求體，響應體等固定的值，多次使用會造成程式碼冗餘。

我們習慣上在專案中將所有後端的介面放在 src/api 的目錄下，如針對student的介面就放在 src/api/student.js 檔案中，方便管理。 將 getStudentList 的介面寫在 src/api/student.js 中

import request from '@/lib/request'

// params是object型別的請求引數
// school.PBStudentListReq 是定義好的請求體model
// school.PBStudentListRsp 是定義好的響應model
// getStudentList 是介面名稱
export function getStudentList (params) {
const req = request.create('PBStudentListReq', params)
return request('getStudentList', req, 'school.PBStudentListRsp')
}
// 後面如果再新增介面直接以此類推
export function getStudentById (id) {
// const req = ...
// return request(...)
}
複製程式碼

6. 在.vue中使用介面

需要哪個介面，就import哪個介面，返回的是Promise物件，非常方便。

<template>
<div class="hello">
<button @click="_getStudentList">獲取學生列表</button>
</div>
</template>

<script>
import { getStudentList } from '@/api/student'
export default {
name: 'HelloWorld',
methods: {
_getStudentList () {
const req = {
limit: 20,
offset: 0
}
getStudentList(req).then((res) => {
console.log(res)
}).catch((res) => {
console.error(res)
})
}
},
created () {
}
}
</script>

<style lang="scss">

</style>
複製程式碼

總結

整個demo的程式碼： demo 。

前端使用的整個流程：

• 1. 將後端提供的所有的proto檔案拷進 src/proto 資料夾
• 2. 執行 npm run proto 生成proto.js
• 3. 根據介面列舉在 src/api 下寫介面
• 4. .vue 檔案中使用介面。

（其中1和2可以合併在一起寫一個自動化的指令碼，每次更新只需執行一下這個指令碼即可）。

寫的比較囉嗦，文筆也不好，大家見諒。

這個流程就是我感覺比較好的一個proto在前端的實踐，可能並不是最好，如果在你們公司有其他更好的實踐，歡迎大家一起交流分享。

後續

在vue中使用是需要打包成一個js模組來使用比較好（這是因為vue在生產環境中打包成只有html,css,js等檔案）。但在某些場景，比如在Node環境中，一個Express的專案，生產環境中是允許出現 .proto 檔案的，這時候可以採取 protobuf.js 提供的其他方法來動態解析proto,不再需要npm run proto這種操作了。

後面有時間我會再寫一篇在node端動態解析proto的記錄。