Important note!
The version of v1.3.X imported rk-gin, rk-echo, rk-grpc and rk-gf in the go.mod file initially. User only needs to [go get rk-boot] for starting web framework.
From v1.4.X, rk-boot will not include those dependencies in one place.
Instead, we use multi-module repository for supported web frameworks.
Release Description Example v1.4.x Use multi-module repository, [go get] submodule as needed for web frameworks go get github.com/rookie-ninja/rk-boot/gin v1.3.x Use root-module repository, will import all web frameworks, not suggested! go get github.com/rookie-ninja/rk-boot The version of submodule will follow version of rk-xxx dependencies.
For example, rk-grpc is currently at release of v1.2.15, so the latest version of submodule would be github.com/rookie-ninja/rk-boot/grpc@v1.2.15
Bootstrapper for rkentry.Entry. With rk-boot, users can start gRPC, gin, echo, GoFrame, prometheus client or custom entry service with yaml formatted config file. Easy to compile, run and debug your grpc service, grpc gateway, swagger UI and rk-tv web UI.
Table of Contents generated with DocToc
- Online document
- Concept
- Supported web frameworks
- Quick Start
- Grpc interceptor
- Gin middleware
- Echo middleware
- GoFrame middleware
- gRPC proxy
- Development Status: Stable
- Build instruction
- Test instruction
- Dependencies
- Contributing
rk-boot is a library which support bootstrapping server at runtime. It is a little like spring boot way.
- Build application with unified project layout at enterprise level .
- Build API with the unified format of logging, metrics, tracing, authorization at enterprise level.
- Make application replace core dependencies quickly.
- Save learning time of writing initializing procedure of popular frameworks and libraries.
- User defined Entry for customization.
Welcome to contribute your web framework dependencies into rk-boot family.
Start with docs and refer rk-gin as example.
Frameworks | Stage | Installation | Dependency |
---|---|---|---|
Gin | Stable | go get github.com/rookie-ninja/rk-boot/gin | rk-gin |
gRPC | Stable | go get github.com/rookie-ninja/rk-boot/grpc | rk-grpc |
Echo | Stable | go get github.com/rookie-ninja/rk-boot/echo | rk-echo |
GoFrame | Pre-release | go get github.com/rookie-ninja/rk-boot/gf | rk-gf |
Fiber | Testing | TBD | rk-fiber |
go-zero | Implementing | TBD | rk-zero |
There are two ways users can run service.
- From YAML
- From Code
User needs to [go get] web framework as needed. Bellow web frameworks are supported.
- Installation
go get github.com/rookie-ninja/rk-boot/grpc
- boot.yaml
---
grpc:
- name: greeter # Required, Name of grpc entry
port: 8080 # Required, Port of grpc entry
enabled: true # Required, Enable grpc entry
commonService:
enabled: true # Optional, Enable common service
tv:
enabled: true # Optional, Enable RK TV
sw:
enabled: true # Optional, Enable Swagger UI
- main.go
package main
import (
"context"
"github.com/rookie-ninja/rk-boot"
_ "github.com/rookie-ninja/rk-boot/grpc"
)
// Application entrance.
func main() {
// Create a new boot instance.
boot := rkboot.NewBoot()
// Bootstrap
boot.Bootstrap(context.Background())
// Wait for shutdown sig
boot.WaitForShutdownSig(context.Background())
}
- go.mod
module github.com/rookie-ninja/rk-demo
go 1.16
require (
github.com/rookie-ninja/rk-boot v1.4.0
github.com/rookie-ninja/rk-boot/grpc v1.2.15 // indirect
)
- validate
$ go run main.go
$ curl -X GET localhost:8080/rk/v1/healthy
{"healthy":true}
- Swagger: http://localhost:8080/sw
- Installation
go get github.com/rookie-ninja/rk-boot/gin
- boot.yaml
---
gin:
- name: greeter # Required, Name of gin entry
port: 8080 # Required, Port of gin entry
enabled: true # Required, Enable gin entry
sw:
enabled: true # Optional, Enable swagger UI
commonService:
enabled: true # Optional, Enable common service
tv:
enabled: true # Optional, Enable RK TV
- main.go
package main
import (
"context"
"github.com/rookie-ninja/rk-boot"
_ "github.com/rookie-ninja/rk-boot/gin"
)
func main() {
// Create a new boot instance.
boot := rkboot.NewBoot()
// Bootstrap
boot.Bootstrap(context.Background())
// Wait for shutdown sig
boot.WaitForShutdownSig(context.Background())
}
- go.mod
module github.com/rookie-ninja/rk-demo
go 1.16
require (
github.com/rookie-ninja/rk-boot v1.4.0
github.com/rookie-ninja/rk-boot/gin v1.2.12 // indirect
)
- validate
$ go run main.go
$ curl -X GET localhost:8080/rk/v1/healthy
{"healthy":true}
- Swagger: http://localhost:8080/sw
- Installation
go get github.com/rookie-ninja/rk-boot/echo
- boot.yaml
---
echo:
- name: greeter # Required, Name of gin entry
port: 8080 # Required, Port of gin entry
enabled: true # Required, Enable gin entry
sw:
enabled: true # Optional, Enable swagger UI
commonService:
enabled: true # Optional, Enable common service
tv:
enabled: true # Optional, Enable RK TV
- main.go
package main
import (
"context"
"github.com/rookie-ninja/rk-boot"
_ "github.com/rookie-ninja/rk-boot/echo"
)
func main() {
// Create a new boot instance.
boot := rkboot.NewBoot()
// Bootstrap
boot.Bootstrap(context.Background())
// Wait for shutdown sig
boot.WaitForShutdownSig(context.Background())
}
- go.mod
module github.com/rookie-ninja/rk-demo
go 1.16
require (
github.com/rookie-ninja/rk-boot v1.4.0
github.com/rookie-ninja/rk-boot/echo v0.0.5 // indirect
)
- validate
$ go run main.go
$ curl -X GET localhost:8080/rk/v1/healthy
{"healthy":true}
- Swagger: http://localhost:8080/sw
- Installation
go get github.com/rookie-ninja/rk-boot/gf
- boot.yaml
---
gf:
- name: greeter # Required, Name of gin entry
port: 8080 # Required, Port of gin entry
enabled: true # Required, Enable gin entry
sw:
enabled: true # Optional, Enable swagger UI
commonService:
enabled: true # Optional, Enable common service
tv:
enabled: true # Optional, Enable RK TV
- main.go
package main
import (
"context"
"github.com/rookie-ninja/rk-boot"
_ "github.com/rookie-ninja/rk-boot/gf"
)
func main() {
// Create a new boot instance.
boot := rkboot.NewBoot()
// Bootstrap
boot.Bootstrap(context.Background())
// Wait for shutdown sig
boot.WaitForShutdownSig(context.Background())
}
- go.mod
module github.com/rookie-ninja/rk-demo
go 1.16
require (
github.com/rookie-ninja/rk-boot v1.4.0
github.com/rookie-ninja/rk-boot/gf v0.0.3 // indirect
)
- validate
$ go run main.go
$ curl -X GET localhost:8080/rk/v1/healthy
{"healthy":true}
- Swagger: http://localhost:8080/sw
rk-boot depends on rk-grpc which contains some commonly used middlewares can be used with gin framework directly. rk-grpc
- logging interceptor
- prometheus metrics interceptor
- auth interceptor
- tracing interceptor
- panic interceptor
- metadata interceptor
- rate limit interceptor
- timeout interceptor
- cors interceptor
- jwt interceptor
- secure interceptor
- csrf interceptor
- boot.yaml
---
grpc:
- name: greeter # Name of grpc entry
port: 8080 # Port of grpc entry
enabled: true # Enable grpc entry
commonService:
enabled: true # Enable common service for testing
interceptors:
loggingZap:
enabled: true
$ go run main.go
$ curl -X GET localhost:8080/rk/v1/healthy
{"healthy":true}
# logs would be printed as bellow.
------------------------------------------------------------------------
endTime=2021-07-09T23:44:09.81483+08:00
startTime=2021-07-09T23:44:09.814784+08:00
elapsedNano=46065
timezone=CST
ids={"eventId":"67d64dab-f3ea-4b77-93d0-6782caf4cfee"}
app={"appName":"rk-demo","appVersion":"master-f414049","entryName":"greeter","entryType":"GrpcEntry"}
env={"arch":"amd64","az":"*","domain":"*","hostname":"lark.local","localIP":"10.8.0.2","os":"darwin","realm":"*","region":"*"}
payloads={"grpcMethod":"Healthy","grpcService":"rk.api.v1.RkCommonService","grpcType":"unaryServer","gwMethod":"","gwPath":"","gwScheme":"","gwUserAgent":""}
error={}
counters={}
pairs={"healthy":"true"}
timing={}
remoteAddr=localhost:58205
operation=/rk.api.v1.RkCommonService/Healthy
resCode=OK
eventStatus=Ended
EOE
Please refer online docs
rk-boot depends on rk-gin which contains some commonly used middlewares can be used with gin framework directly. rk-gin
- logging middleware
- prometheus metrics middleware
- auth middleware
- tracing middleware
- panic middleware
- metadata middleware
- rate limit middleware
- timeout middleware
- gzip middleware
- cors interceptor
- jwt interceptor
- secure interceptor
- csrf interceptor
No codes needed!
Enable middleware in boot.yaml file as bellow. Please refer online docs for details.
- boot.yaml
gin:
- name: greeter # Required
port: 8080 # Required
enabled: true # Required
commonService: # Optional
enabled: true # Optional, default: false
interceptors: # Optional
loggingZap:
enabled: true # Enable logging middleware
$ go run main.go
$ curl -X GET localhost:8080/rk/v1/healthy
{"healthy":true}
# logs would be printed as bellow.
------------------------------------------------------------------------
endTime=2021-07-05T23:42:35.588164+08:00
startTime=2021-07-05T23:42:35.588095+08:00
elapsedNano=69414
timezone=CST
ids={"eventId":"9b874eea-b16b-4c46-b0f5-d2b7cff6844e"}
app={"appName":"rk-demo","appVersion":"master-f414049","entryName":"greeter","entryType":"GinEntry"}
env={"arch":"amd64","az":"*","domain":"*","hostname":"lark.local","localIP":"10.8.0.2","os":"darwin","realm":"*","region":"*"}
payloads={"apiMethod":"GET","apiPath":"/rk/v1/healthy","apiProtocol":"HTTP/1.1","apiQuery":"","userAgent":"curl/7.64.1"}
error={}
counters={}
pairs={}
timing={}
remoteAddr=localhost:56274
operation=/rk/v1/healthy
resCode=200
eventStatus=Ended
EOE
Please refer online docs
rk-boot depends on rk-echo which contains some commonly used middlewares can be used with echo framework directly. rk-gin
- logging middleware
- prometheus metrics middleware
- auth middleware
- tracing middleware
- panic middleware
- metadata middleware
- rate limit middleware
- timeout middleware
- rate limit middleware
- timeout middleware
- gzip middleware
- cors interceptor
- jwt interceptor
- secure interceptor
- csrf interceptor
No codes needed!
Enable middleware in boot.yaml file as bellow. Please refer online docs for details.
- boot.yaml
echo:
- name: greeter # Required
port: 8080 # Required
enabled: true # Required
commonService: # Optional
enabled: true # Optional, default: false
interceptors: # Optional
loggingZap:
enabled: true # Enable logging middleware
$ go run main.go
$ curl -X GET localhost:8080/rk/v1/healthy
{"healthy":true}
# logs would be printed as bellow.
------------------------------------------------------------------------
endTime=2021-07-05T23:42:35.588164+08:00
startTime=2021-07-05T23:42:35.588095+08:00
elapsedNano=69414
timezone=CST
ids={"eventId":"9b874eea-b16b-4c46-b0f5-d2b7cff6844e"}
app={"appName":"rk-demo","appVersion":"master-f414049","entryName":"greeter","entryType":"EchoEntry"}
env={"arch":"amd64","az":"*","domain":"*","hostname":"lark.local","localIP":"10.8.0.2","os":"darwin","realm":"*","region":"*"}
payloads={"apiMethod":"GET","apiPath":"/rk/v1/healthy","apiProtocol":"HTTP/1.1","apiQuery":"","userAgent":"curl/7.64.1"}
error={}
counters={}
pairs={}
timing={}
remoteAddr=localhost:56274
operation=/rk/v1/healthy
resCode=200
eventStatus=Ended
EOE
Please refer online docs
rk-boot depends on rk-echo which contains some commonly used middlewares can be used with GoFrame framework directly. rk-gin
- logging middleware
- prometheus metrics middleware
- auth middleware
- tracing middleware
- panic middleware
- metadata middleware
- rate limit middleware
- timeout middleware
- rate limit middleware
- cors interceptor
- jwt interceptor
- secure interceptor
- csrf interceptor
No codes needed!
Enable middleware in boot.yaml file as bellow. Please refer online docs for details.
- boot.yaml
gf:
- name: greeter # Required
port: 8080 # Required
enabled: true # Required
commonService: # Optional
enabled: true # Optional, default: false
interceptors: # Optional
loggingZap:
enabled: true # Enable logging middleware
$ go run main.go
$ curl -X GET localhost:8080/rk/v1/healthy
{"healthy":true}
# logs would be printed as bellow.
------------------------------------------------------------------------
endTime=2021-12-05T21:03:40.983602+08:00
startTime=2021-12-05T21:03:40.983493+08:00
elapsedNano=108745
timezone=CST
ids={"eventId":"c240ca5c-439e-4235-aacf-1136d7f65965"}
app={"appName":"rk-boot","appVersion":"master-506a2f8","entryName":"greeter","entryType":"GfEntry"}
env={"arch":"amd64","az":"*","domain":"*","hostname":"lark.local","localIP":"192.168.1.102","os":"darwin","realm":"*","region":"*"}
payloads={"apiMethod":"GET","apiPath":"/rk/v1/healthy","apiProtocol":"HTTP/1.1","apiQuery":"","userAgent":"curl/7.64.1"}
error={}
counters={}
pairs={}
timing={}
remoteAddr=localhost:51750
operation=/rk/v1/healthy
resCode=200
eventStatus=Ended
EOE
Please refer online docs
User can start a gRPC server as proxy server which proxies request to backend gRPC servers.
It is under experimental where docs can be found here.
Simply run make all to validate your changes. Or run codes in example/ folder.
- make all If proto or files in boot/assets were modified, then we need to run it.
Run unit test with make test command.
github workflow will automatically run unit test and golangci-lint for testing and lint validation.
module github.com/rookie-ninja/rk-boot
go 1.16
require (
github.com/rookie-ninja/rk-entry v1.0.4
github.com/rookie-ninja/rk-prom v1.1.4
github.com/stretchr/testify v1.7.0
)
We encourage and support an active, healthy community of contributors — including you! Details are in the contribution guide and the code of conduct. The rk maintainers keep an eye on issues and pull requests, but you can also report any negative conduct to lark@rkdev.info.
Released under the Apache 2.0 License.