grapi: A Go repository from rahagi

😮 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

Bump grapi version
- `go get -u github.com/izumin5210/grapi@v0.5'

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

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

Update gex and tools.go

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

Initialize Go Modules
- ```
go mod init
go mod tidy
```

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 }

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

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

Introduce gex

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

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

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

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

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

rahagi/grapi

Features

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

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

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

Getting Started

Create a new application

Create a new service

Start server

User-defined commands

Build commands (including server)

Installation