Skip to content

izumin5210/grapi

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
cmd
 
 
pkg
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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
    • `go get -u github.com/izumin5210/grapi@v0.5'
  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
    • Modules (experimental)
      • Use Go 1.11 and set GO111MODULE=on your env vars
  3. protoc
    • macOS
      • brew install protobuf
    • others