😮 A surprisingly easy API server and generator in gRPC and Go
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
_tests/e2e Rename integration -> e2e Nov 10, 2018
cmd v0.3.0 Nov 15, 2018
pkg Use the same version as grapi cli on init app Nov 15, 2018
.codecov.yml Configure codecov Nov 12, 2018
.dockerignore Fix CI configuration Nov 10, 2018
.gitignore Ignore dist Nov 11, 2018
.reviewdog.yml Setup reviewdog Oct 2, 2018
.travis.yml Run test for go master Nov 12, 2018
Gopkg.lock Drop clicontrib Nov 15, 2018
Gopkg.toml Drop clicontrib Nov 15, 2018
LICENSE Create LICENSE Feb 24, 2018
Makefile Tweak timeout Nov 11, 2018
README.md Update README.md Nov 15, 2018
grapi.png Update README Mar 25, 2018
tools.go Add wire Oct 12, 2018

README.md

grapi

Build Status GoDoc Go Report Card Go project version 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.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