a yeoman generator for golang rest microservices
project backlog here
$ npm install -g yo
$ npm install -g generator-gomicro
$ yo gomicrogomicro aims to provide a production grade generator for applications that implement a restful api through create/retrieve/update/delete (CRUD) operations. Below are the aspects that gomicro implements to make your application production ready:
Start the server with ./gomicro start (replace "gomicro" with the name of your binary). The server implements CRUD operations on your resource. Reference the api documentation for full api usage. Drag and Drop the generated swagger.json onto the swagger editor
A robust command line tool is included in your project. Available cli flags can are documented throughout this README. However, you can always find out more via the command line tool itself (replace "gomicro" with the name of your binary).
$ ./gomicro --help
gomicro is a RESTful microservice that performs CRUD operations on the Phone resources
Usage:
gomicro [command]
Available Commands:
help Help about any command
start start a new server
test run all unit tests
version print the version information
Use "gomicro [command] --help" for more information about a command.The generator provides support for multiple backend database drivers configurable by command line flags.
--db-port=DATABASE-PORT or DB_PORT=DATABASE-PORT
--db-host=DATABASE-HOST or DB_HOST=DATABASE-HOST
--db-user=DATABASE-USER or DB_USER=DATABASE-USER
--db-pass=DATABASE-PASS or DB_PASS=DATABASE-PASS
--db-name=DATABASE-NAME or DB_NAME=DATABASE-NAME --db-location=DATABASE-LOCATION or DB_PORT=DATABASE-LOCATION
--db-name=DATABASE-NAME or DB_NAME=DATABASE-NAME--db-port=DATABASE-PORT or DB_PORT=DATABASE-PORT
--db-host=DATABASE-HOST or DB_HOST=DATABASE-HOST
--db-user=DATABASE-USER or DB_USER=DATABASE-USER
--db-pass=DATABASE-PASS or DB_PASS=DATABASE-PASS
--db-name=DATABASE-NAME or DB_NAME=DATABASE-NAME coming soon
Swagger is the industry standard for documenting APIs. Because of this, you will find complete API documentation for your application in your project. Note that you will only have to modify the data model to match yours.
tack this backlog item here
No project is complete with comprehensive unit testing. The goal is to have over 90% code coverage. You can run these unit tests by executing the following command (replace "gomicro" with the name of your binary):
./gomicro testCORS give you the ability to secure cross-origin HTTP requests. For example, the following code allows the Content-Type header, allows requests from all origin domains, and only allows four HTTP methods:
headersOk := handlers.AllowedHeaders([]string{"Content-Type"})
originsOk := handlers.AllowedOrigins([]string{"*"})
methodsOk := handlers.AllowedMethods([]string{"GET", "DELETE", "POST", "PUT"})Robust logging is streamed to stdout with the following json format:
{"duration":0,"level":"info","method":"GET","msg":"http server started","name":"RetrievePhone","time":"2017-03-26T22:55:25-05:00","uri":"/phone/6"}Basic authentication is enabled by passing the --basic-auth-file=SOMEFILE option to the server. Currently, the basic auth credentials last indefinitely, and the password(s) cannot be changed without restarting the server.
The basic auth file is a csv file with exactly 2 columns: password, user name. When using basic authentication from an http client, the server expects an Authorization header with the value of Basic BASE64ENCODED(USER:PASSWORD) By default, user:pass is the default credentials
The server reads bearer tokens from a file when given the --token-auth-file=SOMEFILE option on the command line. Currently, tokens last indefinitely, and the token list cannot be changed without restarting the server.
The token file is a csv file with 1 column: token. When using bearer token authentication from an http client, the server expects an Authorization header with a value of Bearer THETOKEN. The bearer token must be a character sequence that can be put in an HTTP header value using no more than the encoding and quoting facilities of HTTP. By default, abc123 is the default token
The server can be secured via SSL by setting the --tls-cert-file=SOMEFILE and --tls-private-key-file=SOMEFILE cli flags. The generator will automatically generate self-signed certificates with a common name of localhost. If these cli flags are not set, the server will be served insecurely over HTTP.
The generator create a Dockerfile that you can use to build a lightweight docker image for your application. Image size ~10MB
make docker
docker build -t petrasphere/gomicro:latest .Various aspects of your application are build via the make utility. Here are the provided scripts:
Install dependencies and build binary
Install dependencies
Install dependencies, build binary, and start backend database
Remove binary
Unless you are using sqlite as a database driver, you will need too start up a database to test your application. So assist with this, a docker-compose.yaml file is provided and will start a database matching that of your driver. Here are the necessary configuration items that might be relevant as a side effect of using this feature:
Host: 127.0.0.1
Port: 3306
User: root
Password: password
Database Name: plural of resource noun
Host: 127.0.0.1
Port: 5432
User: root
Password: password
Database Name: plural of resource noun
Since it is recommended that your application be deployed inside of a Docker container, a container orchestration tool is needed in production. Robust configuration for both Kubernetes and Docker Swarm are provided.
The server properly handlers all errors so that it does not have any unexpected results. If errors are encountered, they are written to the HTTP response with this body (as per the API documentation):
{
"code": 401,
"msg": "unauthorized"
}It is often useful to have an HTTP route to diagnose application health. For example, this is used in the Kubernetes deployments. The /health route will attempt to connect to the database and return a 200 if successful or a 500 if it is not.