:open_mouth: A surprisingly easy API server and generator in gRPC and Go
Features
- You can develop and deploy API servers blazingly fast :zap:
- Easy code generator
- application (inspired by
rails newandcreate-react-app) - gRPC services and their implementations (inspired by
rails g (scaffold_)controller)
- application (inspired by
- User-friendly
protocwrapper (inspired by protoeasy) - Provides gRPC and HTTP JSON API with single implementation by using grpc-gateway
- Generates codes based on google's API design guideline
:warning: Migrate 0.4.x -> 0.5.x :warning:
grapiserver will not handle os signals from v0.5.x.
We recommend to use appctx.Global() if you want to handle them.
- Bump grapi version
- `go get -u github.com/izuimn5210/grapi@v0.5'
- Update
cmd/server/run.go-
// Application context - ctx := context.Background() + ctx := appctx.Global() -
- return s.ServeContext(ctx) + return s.Serve(ctx)
-
:warning: Migrate 0.3.x -> 0.4.x :warning:
Some tools that are depended by grapi are updated. If you have a grapi project <=v0.3.x, you should migrate it.
- Bump grapi version
- If you use dep, update
Gopkg.tomlname = "github.com/izumin5210/grapi" - version = "0.3.0" + version = "0.4.0" - and run
dep ensure
- If you use dep, update
- Update gex and
tools.go-
go get -u github.com/izumin5210/gex/cmd/gex gex --regen
-
- Initialize Go Modules
-
go mod init go mod tidy
-
- Update
grapi.toml-
package = "yourcompany.yourappname" [grapi] server_dir = "./app/server" [protoc] protos_dir = "./api/protos" out_dir = "./api" import_dirs = [ "./api/protos", - "./vendor/github.com/grpc-ecosystem/grpc-gateway", - "./vendor/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis", + '{{ module "github.com/grpc-ecosystem/grpc-gateway" }}', + '{{ module "github.com/grpc-ecosystem/grpc-gateway" }}/third_party/googleapis', ] name = "go" args = { plugins = "grpc", paths = "source_relative" } name = "grpc-gateway" args = { logtostderr = true, paths = "source_relative" } name = "swagger" args = { logtostderr = true }
-
- Drop dep
-
rm Gopkg.*
-
:warning: Migrate 0.2.x -> 0.3.x :warning:
grapi v0.3.0 has some breaking changes. If you have a grapi project <=v0.2.x, you should migrate it.
- Bump grapi version
- If you use dep, update
Gopkg.tomlname = "github.com/izumin5210/grapi" - version = "0.2.2" + version = "0.3.0" - and run
dep ensure
- If you use dep, update
- Introduce gex
-
go get github.com/izumin5210/gex/cmd/gex
-
- Add defualt generator plugins:
-
gex \ --add github.com/izumin5210/grapi/cmd/grapi \ --add github.com/izumin5210/grapi/cmd/grapi-gen-command \ --add github.com/izumin5210/grapi/cmd/grapi-gen-service \ --add github.com/izumin5210/grapi/cmd/grapi-gen-scaffold-service \ --add github.com/izumin5210/grapi/cmd/grapi-gen-type
-
- Add protoc plugins via gex
-
gex \ --add github.com/golang/protobuf/protoc-gen-go \ --add github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway \ --add github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger - Remove protoc plugins from
Gopkg.toml-required = [ - "github.com/golang/protobuf/protoc-gen-go", - "github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway", - "github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger", -]
-
- Update
grapi.toml-
+package = "yourcompany.yourappname" + [grapi] server_dir = "./app/server" [protoc] protos_dir = "./api/protos" out_dir = "./api" import_dirs = [ + "./api/protos", "./vendor/github.com/grpc-ecosystem/grpc-gateway", "./vendor/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis", ] - path = "./vendor/github.com/golang/protobuf/protoc-gen-go" name = "go" args = { plugins = "grpc", paths = "source_relative" } - path = "./vendor/github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway" name = "grpc-gateway" - args = { logtostderr = true } + args = { logtostderr = true, paths = "source_relative" } - path = "./vendor/github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger" name = "swagger" args = { logtostderr = true }
-
Getting Started
Create a new application
$ grapi init awesome-app
Create a new service
$ grapi g service books
Or, if you need full standard methods, you can get them with following command:
$ grapi g scaffold-service books
And you should register generated services to the grapiserver.Engine instance:
// app/run.go
// Run starts the grapiserver.
func Run() error {
s := grapiserver.New(
grapiserver.WithDefaultLogger(),
grapiserver.WithServers(
+ server.NewBookServiceServer(),
- // TODO
),
)
return s.Serve()
}
If you updated service definition, you can re-generate .pb.go and .pb.gw.go with following command:
$ grapi protoc
Start server
$ grapi server
User-defined commands
$ grapi g command import-books
$ vim cmd/import-books/run.go # implements the command
$ grapi import-books # run the command
Build commands (including server)
$ grapi build
Installation
- grapi
- Linux
curl -Lo grapi https://github.com/izumin5210/grapi/releases/download/v0.2.2/grapi_linux_amd64 && chmod +x grapi && sudo mv grapi /usr/local/bin
- macOS
brew install izumin5210/tools/grapi
- others
go get github.com/izumin5210/grapi/cmd/grapi
- Linux
- dep or Modules
- dep
- macOS
brew install dep
- others
- See Installation · dep
curl https://raw.githubusercontent.com/golang/dep/master/install.sh, sh
- macOS
- Modules (experimental)
- Use Go 1.11 and set
GO111MODULE=onyour env vars
- Use Go 1.11 and set
- dep
- protoc
- macOS
brew install protobuf
- others
- Download and install from google/protobuf
- macOS