From caaafa591f03a77a4933d155beb82c80928822e4 Mon Sep 17 00:00:00 2001 From: Nicholas Xu Date: Mon, 13 Jul 2020 14:58:39 +0800 Subject: [PATCH 1/4] add quickstart guide --- docs/README.md | 4 +++ docs/installation.md | 70 +++++++++++++++++++++++++++++++++++++++++++- docs/quickstart.md | 45 +++++++++++++++++++++++++++- docs/structure.md | 46 ++++++++++++++++++++++++++++- 4 files changed, 162 insertions(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index 0cc8c916..53e069ef 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,7 @@ # Documents - [中文](about) + +- [Installation](installation) +- [Quickstart](quickstart) +- [Structure](structure) diff --git a/docs/installation.md b/docs/installation.md index 7144b3c7..6c857aa2 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1 +1,69 @@ -# 安装 +# Installation + +```sh +go get github.com/shanbay/gobay/cmd/gobay +``` + +## Tools for gobay project + +Here are the tools we recommend installing for developing a project with gobay: +`And if it's too much for you, checkout the docker development box section below` + +- [golang (programming language)](https://golang.org/doc/install) [Download and Install](https://golang.org/dl/) +- [openapi(API definition and documentation) tool](https://goswagger.io/install.html) [（openapi docs）](https://github.com/go-swagger/go-swagger) + +```sh +# mac: +brew tap go-swagger/go-swagger +brew install go-swagger + +# windows +# Download and install latest release version from: +# https://github.com/go-swagger/go-swagger/releases/tag/v0.24.0 +``` + +- [grpc tool](https://github.com/grpc/grpc-go) + +```sh +go get -u google.golang.org/grpc +``` + +- [lint tool: golangci-lint](https://golangci-lint.run/usage/install/#local-installation) + +```sh +# mac +brew install golangci/tap/golangci-lint +brew upgrade golangci/tap/golangci-lint + +# windows +# install git bash and： +# binary will be $(go env GOPATH)/bin/golangci-lint +curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.27.0 +golangci-lint --version +``` + +- [orm tool: ent, make sure to install version v0.2.5](https://github.com/shanbay/ent) + +```sh +go get github.com/facebookincubator/ent/cmd/entc@v0.2.5 +``` + +- [test tool: gotests](https://github.com/cweill/gotests) + +```sh +go get -u github.com/cweill/gotests/ +``` + +- [test coverage tool: gocovmerge](https://github.com/wadey/gocovmerge) + +```sh +go get github.com/wadey/gocovmerge +``` + +## Docker development box + +If any of the installations above is too annoying in your OS, you may try this option: + +After creating your new project (checkout the quickstart.md page), there will be a `dockerfiles` directory in your project. + +open it, and run `sh run.sh`, it will build a development ready docker image, and run a docker container with the project directory mounted. diff --git a/docs/quickstart.md b/docs/quickstart.md index b8be99be..2d1501ba 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1 +1,44 @@ -# 快速入门 +# Quick Start + +```sh +gobay new + +# i.e. +gobay new github.com/company/helloworld-project +cd helloworld-project +``` + +- Run the tools in docker dev box if you like: + +```sh +cd dockerfiles +sh run.sh +``` + +--- + +## To start a grpc server + +```sh +make run COMMAND=grpcsvc +``` + +then `grpc.health.v1.health/check` is available on port 6000. + +--- + +## To start an API server + +1. We need to generate some openapi code with the openapi spec (`spec/openapi/main.yml`) (require openapi tool, use docker dev box if needed) + +```sh +make genswagger +``` + +1. Start the server + +```sh +make run COMMAND=httpsvc +``` + +Then you may view the api docs at [http://127.0.0.1:5000/helloworld-project/docs](http://127.0.0.1:5000/helloworld-project/docs) diff --git a/docs/structure.md b/docs/structure.md index 55043883..42f4763a 100644 --- a/docs/structure.md +++ b/docs/structure.md @@ -1 +1,45 @@ -# 项目结构 +# Project Structure + +```sh +. +├── Makefile # common commands +├── app # core code area, implementations will be done in this directory. +│   ├── asynctask # async job (server). You can use async job extension client, create a job into a redis queue, and let the async job server handle the queue. +│   │   ├── handlers.go +│   │   └── server.go +│   ├── constant.go # define constants here +│   ├── extensions.go # define and prepare extensions (redis/mysql/grpc/cache/sentry/elasicApm/etc.) +│   ├── grpc # GRPC service controllers +│   │   ├── handlers.go +│   │   └── server.go +│   ├── models # repository for models and cache +│   │   ├── cache.go +│   │   └── common.go +│   │   # ...add more models and repositories here +│   └── openapi # API 的 controller +│   ├── handlers.go +│   └── server.go +├── cmd # command entry, start a (one of) grpc/openapi/asynctask/etc server by calling a command here. +│   ├── actions +│   │   ├── asynctask.go +│   │   ├── grpcsvc.go +│   │   ├── health_check.go +│   │   ├── httpsvc.go +│   │   └── root.go +│   │   # ...add more command +│   └── main.go +├── config.yaml # configs in yaml file +├── gen # geneated code, i.e. openapi/protobuf(grpc)/ent(mysql), populated with corresponding tools +├── go.mod # dependency +└── spec # specification for tools to generate stuff in /gen directory (i.e. proto for protobuf, yaml for openapi, tmpl/schema for ent) + ├── enttmpl + │   ├── builder_create.tmpl + │   ├── builder_query.tmpl + │   ├── client.tmpl + │   └── sql_create.tmpl + ├── schema # schema directory for (ent) db models + ├── grpc + ├── openapi + │   └── main.yml # openapi (swagger) spec + # ...add more if needed here +``` From d9b95ca95aa985d4c41db3026e7d040cdfefad5d Mon Sep 17 00:00:00 2001 From: Nicholas Xu Date: Mon, 13 Jul 2020 17:31:37 +0800 Subject: [PATCH 2/4] update for creating api --- docs/installation.md | 11 ++++++++++ docs/quickstart.md | 52 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 62 insertions(+), 1 deletion(-) diff --git a/docs/installation.md b/docs/installation.md index 6c857aa2..863896f1 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -28,6 +28,17 @@ brew install go-swagger go get -u google.golang.org/grpc ``` +- [protobuf tool](https://github.com/golang/protobuf) [(probably official)installation guide](http://google.github.io/proto-lens/installing-protoc.html) + +```sh +# install protobuf (or at least protobuf-compiler) +# mac: +brew install protobuf + +go get -u github.com/gogo/protobuf/protoc-gen-gofast +go get -u github.com/golang/mock/mockgen +``` + - [lint tool: golangci-lint](https://golangci-lint.run/usage/install/#local-installation) ```sh diff --git a/docs/quickstart.md b/docs/quickstart.md index 2d1501ba..5c1e60e4 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -17,7 +17,7 @@ sh run.sh --- -## To start a grpc server +## To start a GRPC server ```sh make run COMMAND=grpcsvc @@ -25,6 +25,32 @@ make run COMMAND=grpcsvc then `grpc.health.v1.health/check` is available on port 6000. +### Add more GRPC handlers + +1. Generate code for protos + +```sh +# using proto files in spec/grpc directory, generate protobuf go file. +make genproto + +# using generated protobuf go file, generate mock protobuf go file for testing. +make genprotomock +``` + +1. open `app/grpc/server.go`, register api server in `func configureAPI() {...}` method. + +```go +// i.e. +func configureAPI(s *grpc.Server, impls *helloworldProjectServer) { + // ... + // protos.RegisterHelloworldProjectServer(s, impls) + grpc_health_v1.RegisterHealthServer(s, impls) + // ... +} +``` + +1. open app/grpc/handlers.go, and implement the grpc method handler inside. + --- ## To start an API server @@ -42,3 +68,27 @@ make run COMMAND=httpsvc ``` Then you may view the api docs at [http://127.0.0.1:5000/helloworld-project/docs](http://127.0.0.1:5000/helloworld-project/docs) + +### Add more API handlers + +1. Update `spec/openapi/main.yml` (add more API specs) + +1. generate code for openapi spec + +```sh +make genswagger +``` + +1. open `openapi/server.go`, register grpc server in `func configureAPI() {...}` method. + +```go +// i.e. +func configureAPI(s *restapi.Server, api *operations.HelloworldProjectAPI, impls *helloworldProjectServer, enableApm bool) { + // ... + api.HealthHealthCheckHandler = impls.healthCheckHealthHandler() + // ... +} + +``` + +1. open `app/openapi/handlers.go`, and implement the api method handler inside From a4dde8251b4c8c62aeaf0b2a7d10a1db498498ba Mon Sep 17 00:00:00 2001 From: Nicholas Xu Date: Mon, 13 Jul 2020 17:41:20 +0800 Subject: [PATCH 3/4] add grpc generate guide --- docs/quickstart.md | 19 +++++++++++++++++++ docs/structure.md | 2 +- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 5c1e60e4..a793f90e 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -27,6 +27,25 @@ then `grpc.health.v1.health/check` is available on port 6000. ### Add more GRPC handlers +1. Create your GRPC proto files into `spec/grpc` directory, i.e. `spec/grpc/helloworld.proto` + +```proto +syntax = "proto3"; + +package helloworld; +option go_package = "github.com/com/example/helloworld"; + +service Greeter { + rpc SayHello (HelloRequest) returns (HelloReply) {} +} +message HelloRequest { + string name = 1; +} +message HelloReply { + string message = 1; +} +``` + 1. Generate code for protos ```sh diff --git a/docs/structure.md b/docs/structure.md index 42f4763a..5fcc2988 100644 --- a/docs/structure.md +++ b/docs/structure.md @@ -38,7 +38,7 @@ │   ├── client.tmpl │   └── sql_create.tmpl ├── schema # schema directory for (ent) db models - ├── grpc + ├── grpc # proto files here ├── openapi │   └── main.yml # openapi (swagger) spec # ...add more if needed here From e5f1ba6828a1d1618a667c78aae75292822c405e Mon Sep 17 00:00:00 2001 From: Nicholas Xu Date: Tue, 14 Jul 2020 16:54:24 +0800 Subject: [PATCH 4/4] fix main links --- docs/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/README.md b/docs/README.md index 53e069ef..c6a2b310 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ # Documents -- [中文](about) +- [中文](about.md) -- [Installation](installation) -- [Quickstart](quickstart) -- [Structure](structure) +- [Installation](installation.md) +- [Quickstart](quickstart.md) +- [Structure](structure.md)