Merge pull request #180 from nicholasxuu/feature-quickstart-guide

Feature quickstart guide

docs/README.md

@@ -1,3 +1,7 @@
 # Documents
 
-- [中文](about)
+- [中文](about.md)
+
+- [Installation](installation.md)
+- [Quickstart](quickstart.md)
+- [Structure](structure.md)

docs/installation.md

@@ -1 +1,80 @@
-# 安装
+# 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
+```
+
+- [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
+# 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/[email protected]
+```
+
+- [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.

docs/quickstart.md

@@ -1 +1,113 @@
-# 快速入门
+# Quick Start
+
+```sh
+gobay new <your-project>
+
+# 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.
+
+### 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
+# 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
+
+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)
+
+### 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

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 # proto files here
+    ├── openapi
+    │   └── main.yml # openapi (swagger) spec
+    # ...add more if needed here
+```