grapi

module

v0.5.0 Latest Latest Go to latest Published: Oct 8, 2019 License: MIT

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/izumin5210/grapi

Links

Open Source Insights

README ¶

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

:memo: How to migrate

Bump grapi version
- `go get -u github.com/izuimn5210/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.

:memo: 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.

:memo: 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

Directories ¶

Path	Synopsis
cmd
grapi
grapi-gen-command
grapi-gen-command/template Package statik contains static assets.	Package statik contains static assets.
grapi-gen-scaffold-service
grapi-gen-service
grapi-gen-type
grapi-gen-type/di
grapi-gen-type/template Package statik contains static assets.	Package statik contains static assets.
pkg
cli
excmd
excmd/testing
gencmd
gencmd/testing
gencmd/util
grapicmd
grapicmd/cmd
grapicmd/di
grapicmd/internal/module
grapicmd/internal/module/script
grapicmd/internal/module/testing Package moduletesting is a generated GoMock package.	Package moduletesting is a generated GoMock package.
grapicmd/internal/usecase
grapicmd/internal/usecase/template Package statik contains static assets.	Package statik contains static assets.
grapicmd/util/fs
grapiserver
grapiserver/internal
grapiserver/testing/api Package api_pb is a generated protocol buffer package.	Package api_pb is a generated protocol buffer package.
grapiserver/testing/app/server
protoc
svcgen
svcgen/params
svcgen/template Package statik contains static assets.	Package statik contains static assets.
svcgen/testing

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL