每支API都要寫文件的日子, 你還記得嗎？

API文件是讓別人瞭解系統提供哪些功能的媒介, 文件要寫的清楚明瞭真的要花上不少時間, 有時候寫API文件所花的時間還比coding時間久, 使用了Protobuf之後, proto 檔案就是我的文件, Input格式、Output格式、每個參數的資料型別都可以清楚的寫在proto上面, 一旦有異動也只要更新spec就可以知道新的接口跟型別, 不需要來回修改文件、Client端也不用再來確認格式等等的, 重要的是不用擔心圖文不符會被追殺

protobuf 簡介

Protobuf指的是Protocol Buffers, 它是由Google 開發的一種數據交換格式, 寫好資料結構的spec之後就可以透過工具protoc-gen-go依照使用的語言編譯成對應的檔案, 我使用的是proto3。

編寫proto

1. 先寫一個ping-pong 接口, 用來確認服務狀態。我們的服務都會留一個ping-pong接口來做服務存活確認, ping接口中可以自訂要檢查的項目。

syntax = "proto3";

option go_package = "./;coconut";

package coconut;

service Coconut {
    rpc Ping(PingRequest) returns (Pong){}
}

message PingRequest {}

message Pong {
    string pong = 1;
}

2. 填上接口與參數API。基本會開的API大概都不離：新增、修改、刪除、查詢。這次異動的裝置是Redis, 所以先開修改跟查詢的API。

	syntax = "proto3";

	option go_package = "coconut/pb;coconut";

	package coconut;

	service Coconut {
	    rpc Ping(PingRequest) returns (Pong){}
	    // 更新統計點數
	    rpc UpdatePoints(PointsRequest) returns (RetPoints){}
	    // 取得點數統計狀況
	    rpc GetPoints(GetPointsRequest) returns (RetPoints){}
	}

	message PingRequest {}

	message Pong {
	    string pong = 1;
	}

	// 更新統計點數參數
	message PointsRequest {
	    string level_1 = 1; // 第一層, 最上層代號
	    string level_2 = 2; // 第二層代號
	    string level_3 = 3; // 第三層代號
	    string user_name = 4;  // 操作員代號
	    int32 point = 5; // 施作點數
	}

	message PointInfo {
	    string name = 1; // 層級名稱
	    int32 points = 2; // 點數
	}
	message RetPoints {
	    repeated PointInfo data = 1; // 回傳當前資料
	}

	message GetPointsRequest {
	    string level_1 = 1; // 第一層, 最上層代號
	    string level_2 = 2; // 第二層代號
	    string level_3 = 3; // 第三層代號
	}

這邊要注意的是：message 的參數一開了之後，如果要刪除，需要通知有使用spec的服務一起更新才行, 因為spec如果判斷到型別不相同或是參數取不到就會無法使用, 實務上會來使用spec的系統可能有5~10個, 如果隨便刪除或改變資料型別會需要很多系統一起更新, 但有可能遇到每個系統更新時程不同的問題, 後來採用的方式就是棄用前面的參數, 持續在後面加上新的, 這樣急迫需要使用到新參數的人再更新spec就好。

3. 會產生 .pb.go 的程式, 因為我使用的是Go開發, 所以用go_out來輸出需要的格式, 他還有支援很多輸出格式, 可參考grpc.io

protoc -I/usr/local/include -I. -I/Users/evelyn_chen/Dev/workspaces/src coconut.proto --go_out=plugins=grpc:.

查看 pb.go內容可以看到protobuff文件已被成功編譯為程式了

接下來要在專案中引用spec就可以進行開發了。