README
protorepo
Required File Structure
$GOPATH
├── bin
│
├── pkg
│ └── mod
└── (anyname other than src)
├── protorepo *
Dependencies
prototool:
brew install prototool
-
go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger go get -u github.com/golang/protobuf/protoc-gen-go
-
npm install ts-protoc-gen
Usage
Create a new service
- Create a new dir:
mkdir -p proto/new_service/v1beta1/
- (Optional) Create a config file if extra configs are needed:
prototool config init proto/new_service
- Create a protobuf template:
prototool create proto/new_service/v1beta1/new_service.proto
Write API definition Note:
all those definitions must follow the protobuf lint rules. Uber's lint rule v2 is recommended and set as the default lint rule since it is strict.
If extra REST interfaces are needed, follow the tutorial of grpc-gateway.
Lint your API:
prototool lint proto/new_service/v1beta1/new_service.proto
Note we are think of adding this lint process in our CI pipeline, any commit with lint error will be intolerant.
- Generate your API pb files:
prototool generate proto/new_service/v1beta1/new_service.proto
Generated pb files will be under pkg/new_service/v1beta1
- Import file into your service codebase
package main
import "gitlab.aitmed.io/backend/protorepo/go/new_service/v1beta1"
Supported language pb files repo
Once a set of protobuf files is designed, language-specific code templates called pb files will be automatically generated by the CI. Javascript (frontend client), golang and python (cross-service communication) are the major customers of those files. Note that those files should be considered as library files thus cannot be modified. The very problem remains how to package files into library.
Golang
Dependency management in golang is easy since golang has built-in git support
for fetching 3rd-party libraries and this only happens during development and
build time. Simply import files like
gitlab.aitmed.io/backend/protorepo/pkg/...
should be fine.
Javascript/Typescript
Private javascript repo.
Python
python will be packaged as an egg file, simply import those files should be fine.
Java
Java pb files will be packed into a jar file for easy import. Upload to the central maven repo if needed.
API changes
API is always changing. The basic idea is any API version number with suffix
alpha#
beta#
might introduces breaking changes. Other APIs will not break,
however.