😮 A surprisingly easy API server and generator in gRPC and Go

Features

• You can develop and deploy API servers blazingly fast ⚡
• 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

⚠️ Migrate 0.4.x -> 0.5.x ⚠️

grapiserver will not handle os signals from v0.5.x. We recommend to use appctx.Global() if you want to handle them.

📝 How to migrate

0. Bump grapi version
   • `go get -u github.com/izumin5210/grapi@v0.5'
1. Update cmd/server/run.go

   •  	// Application context
     -	ctx := context.Background()
     +	ctx := appctx.Global()

   • -	return s.ServeContext(ctx)
     +	return s.Serve(ctx)

⚠️ Migrate 0.3.x -> 0.4.x ⚠️

Some tools that are depended by grapi are updated. If you have a grapi project <=v0.3.x, you should migrate it.

📝 How to migrate

0. Bump grapi version
   • If you use dep, update Gopkg.toml

      [[constraint]]
        name = "github.com/izumin5210/grapi"
     -  version = "0.3.0"
     +  version = "0.4.0"

   • and run dep ensure
1. Update gex and tools.go

   • go get -u github.com/izumin5210/gex/cmd/gex
     gex --regen
     

2. Initialize Go Modules

   • go mod init
     go mod tidy
     

3. 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',
     ]
     
       [[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 }

4. Drop dep

   • rm Gopkg.*
     

⚠️ Migrate 0.2.x -> 0.3.x ⚠️

grapi v0.3.0 has some breaking changes. If you have a grapi project <=v0.2.x, you should migrate it.

📝 How to migrate

0. Bump grapi version
   • If you use dep, update Gopkg.toml

      [[constraint]]
        name = "github.com/izumin5210/grapi"
     -  version = "0.2.2"
     +  version = "0.3.0"

   • and run dep ensure
1. Introduce gex

   • go get github.com/izumin5210/gex/cmd/gex
     

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

3. 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",
     -]

4. 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",
      ]
     
        [[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

1. 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
2. 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
3. protoc
   • macOS
     • brew install protobuf
   • others
     • Download and install from google/protobuf