Skip to content

izumin5210/grapi

Repository files navigation

grapi

CI GoDoc Go Report Card GitHub release (latest SemVer) license

😮 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

asciicast

⚠️ 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
  1. Bump grapi version
  2. 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
  1. 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
  2. Update gex and tools.go
    • go get -u github.com/izumin5210/gex/cmd/gex
      gex --regen
      
  3. Initialize Go Modules
    • go mod init
      go mod tidy
      
  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",
      +  '{{ 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 }
  5. 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
  1. 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
  2. Introduce gex
    • go get github.com/izumin5210/gex/cmd/gex
      
  3. 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
      
  4. 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",
      -]
  5. 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