izumin5210/grapi - Githubissues

: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 new and create-react-app)
- gRPC services and their implementations (inspired by rails g (scaffold_)controller)
User-friendly protoc wrapper (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.

:memo: How to migrate

0. Bump grapi version - `go get -u github.com/izumin5210/grapi@v0.5' 1. Update `cmd/server/run.go` - ```diff // Application context - ctx := context.Background() + ctx := appctx.Global() ``` - ```diff - 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.

:memo: How to migrate

0. Bump grapi version - If you use [dep](https://golang.github.io/dep/), update `Gopkg.toml` ```diff [[constraint]] name = "github.com/izumin5210/grapi" - version = "0.3.0" + version = "0.4.0" ``` - and run `dep ensure` 1. Update [gex](https://github.com/izumin5210/gex) and `tools.go` - ``` go get -u github.com/izumin5210/gex/cmd/gex gex --regen ``` 1. Initialize [Go Modules](https://github.com/golang/go/wiki/Modules) - ``` go mod init go mod tidy ``` 1. Update `grapi.toml` - ```diff 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', ] [[protoc.plugins]] name = "go" args = { plugins = "grpc", paths = "source_relative" } [[protoc.plugins]] name = "grpc-gateway" args = { logtostderr = true, paths = "source_relative" } [[protoc.plugins]] name = "swagger" args = { logtostderr = true } ``` 1. 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.

:memo: How to migrate

0. Bump grapi version - If you use [dep](https://golang.github.io/dep/), update `Gopkg.toml` ```diff [[constraint]] name = "github.com/izumin5210/grapi" - version = "0.2.2" + version = "0.3.0" ``` - and run `dep ensure` 1. Introduce [gex](https://github.com/izumin5210/gex) - ``` go get github.com/izumin5210/gex/cmd/gex ``` 1. 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 ``` 1. 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` ```diff -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", -] ``` 1. Update `grapi.toml` - ```diff +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", ] [[protoc.plugins]] - path = "./vendor/github.com/golang/protobuf/protoc-gen-go" name = "go" args = { plugins = "grpc", paths = "source_relative" } [[protoc.plugins]] - path = "./vendor/github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway" name = "grpc-gateway" - args = { logtostderr = true } + args = { logtostderr = true, paths = "source_relative" } [[protoc.plugins]] - 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
dep or Modules
- dep
  - macOS
    - brew install dep
  - others
    - See Installation · dep
    - curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh
- Modules (experimental)
  - Use Go 1.11 and set GO111MODULE=on your env vars
protoc
- macOS
  - brew install protobuf
- others
  - Download and install from google/protobuf