day6 - proto buffer 简介 & spec 编写

每支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就可以进行开发了。