gomicro
a yeoman generator for golang rest microservices
project backlog here
Quick Start
$ npm install -g generator-gomicro$ yo gomicroOverview
gomicro 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:
Table of Contents
Components
HTTP Router
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
Command Line Interface
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 --helpgomicro 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" Database Driver
The generator provides support for multiple backend database drivers configurable by command line flags.
MySQL
--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 Sqlite
--db-location=DATABASE-LOCATION or DB_PORT=DATABASE-LOCATION--db-name=DATABASE-NAME or DB_NAME=DATABASE-NAMEPostgreSQL
--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 MongoDB
coming soon
API Documentation
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.
Unit Testing
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 testHTTP Access Control (CORS)
CORS 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"})Logging
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"Authorization
Static Password File
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)
Static Token File
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.
SSL
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.
Docker
The generator create a Dockerfile that you can use to build a lightweight docker image for your application. Image size ~10MB
make dockerdocker build -t petrasphere/gomicro:latest .Build Scripts
Various aspects of your application are build via the make utility. Here are the provided scripts:
make
Install dependencies and build binary
make install
Install dependencies
make local-dev
Install dependencies, build binary, and start backend database
make clean
Remove binary
Local Development
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:
MySQL
Host: 127.0.0.1
Port: 3306
User: root
Password: password
Database Name: plural of resource noun
PostgreSQL
Host: 127.0.0.1
Port: 5432
User: root
Password: password
Database Name: plural of resource noun
Deployment
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.
Error Handling
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):
Health Checks
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.