protorepo

Required File Structure

$GOPATH
├── bin
│   
├── pkg
│   └── mod
└── (anyname other than src)
    ├── protorepo *

Dependencies

1. prototool:

   brew install prototool

2. grpc-gateway

   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

3. ts-protoc-gen

   npm install ts-protoc-gen

Usage

Create a new service

1. Create a new dir:

mkdir -p proto/new_service/v1beta1/

2. (Optional) Create a config file if extra configs are needed:

prototool config init proto/new_service

3. Create a protobuf template:

prototool create proto/new_service/v1beta1/new_service.proto

4. Write API definition Note:

5. 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.

6. If extra REST interfaces are needed, follow the tutorial of grpc-gateway.

7. 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.

6. Generate your API pb files:

prototool generate proto/new_service/v1beta1/new_service.proto

Generated pb files will be under pkg/new_service/v1beta1

7. 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.