Go Sample project to understand Mysql CRUD operation with best practises Includes logging, JWT, Swagger and Transactions
Go Sample project to understand Mysql CRUD operation with best practises
A production ready sample Book store RESTful API with Go using gorilla/mux uber/Zap lumberjack with Mysql (A nice relational Database), JWT Authentication. This Project contains a golang implementation of Swagger 2.0 (aka OpenAPI 2.0): it knows how to serialize and deserialize swagger specifications.
# Download this project
git clone github.com/err-him/go-book-store-api
Before running API server, you should set the database config with yours or set the your database config with my values on db/evv.local.json
{
"host" : "127.0.0.1",
"port" : "3306",
"uname" : "root",
"dbname" : "book_store",
"pass" : "root"
}
Step 1: Create the Docker image according to Dockerfile. Ensure docker-compose is installed on your build system. For details on how to do this, see: https://docs.docker.com/compose/install/
# This may take a few minutes.
$ docker-compose up -d
This will create two containers in background for Go and Mysql respectively
Step 2:. The above process will create two separate container and DB for application, to auto populate some data in DB run
$ cat db.sql | docker exec -i full_db_mysql /usr/bin/mysql -u root --password=root book_store
Step 3: Open another terminal and access the example API endpoint.
$ curl http://localhost:9002/health
{"status": "up" }
Important Note: While setting up the docker change the DB host from 127.0.0.1
to book-store-mysql
because while creating the docker Image we are proving host name book-store-mysql
else use 127.0.0.1
if running using go run or make run
gorilla/mux is being used to setup for routing. It provides some powerful feature like grouping/middleware/handler etc.
v1 := r.PathPrefix("/api/v1").Subrouter()
v1.HandleFunc("/genre/create", genreHandler.CreateGenre).Methods(http.MethodPost)
v1.HandleFunc("/genre/update", genreHandler.UpdateGenre).Methods(http.MethodPut)
v1.HandleFunc("/genre/get/all", genreHandler.GetAll).Methods(http.MethodGet)
v1.HandleFunc("/genre/get/{id}", genreHandler.GetOne).Methods(http.MethodGet)
v1.HandleFunc("/genre/delete/{id}", genreHandler.Delete).Methods(http.MethodDelete)
Mysql is being used as database database/sql and github.com/go-sql-driver/mysql module to create and manage database connection
# Build and Run
cd go-book-store-api
make build
# Build and Run
cd go-book-store-api
make APP_ENV="local" run
# API Endpoint : http://127.0.0.1:9002
main.go -> Entry point of application
config -> folder to store all connection and routing related logic
config/app.go -> app run/db connection and routing Initialize
config/routes.go -> app routing defined here
config/driver/db.go -> mysql connection established Here
config/properties -> all application properties in JSON form stored Here, to read config file **https://github.com/err-him/gonf** package used
logger -> Folder contains application logging logic
logger/zap.go -> This contains the logger implementation logic. To implement **uber/zap** logger with **lumberjack** a log rolling package **https://github.com/err-him/gozap** package is being used
api -> Api package is used to receive an incoming request, validate the request for any bad input parameters. Generate a proper response after running our business logic.
api/constants -> contains all application related constants like http etc
api/controllers -> Contains handler functions for particular route to be called when an api is called.
api/models -> database tables to be used as models struct and interface provided for the repositories
api/handler -> basically contains the helper functions used in returning api responses, HTTP status codes, default messages etc.
api/repositories -> repository package is a wrapper on database and cache, so no other package can directly access the database. This package handle all create, update, fetch and delete operation on database tables or cache.
api/utils -> contains all application utility function.
db.sql -> file contains db schema and data information, dumped data from mysql
command for dump database => `mysqldump -u root -p book_store > /Users/himanshu/go-learning/book-store-api/db.sql`
swagger.yml -> swagger API documentation configuration
OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including:
/users
) and operations on each endpoint (GET /users
, POST /users
)API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines. The complete OpenAPI Specification can be found on GitHub: OpenAPI 2.0 Specification, OpenAPI 3.0 Specification
Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs. The major Swagger tools include: Swagger allows you to describe the structure of your APIs so that machines can read them. The ability of APIs to describe their own structure is the root of all awesomeness in Swagger.
Swagger can be written in JSON or YAML. In this guide, we only use YAML examples, but JSON works equally well. A sample Swagger specification written in YAML looks like:
swagger: "2.0"
info:
title: Sample API
description: API description in Markdown.
version: 1.0.0
host: api.example.com
basePath: /v1
schemes:
- https
paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in Markdown.
produces:
- application/json
responses:
200:
description: OK
This Project contains a golang implementation of Swagger 2.0 (aka OpenAPI 2.0): it knows how to serialize and deserialize swagger specifications.
go-swagger
brings to the go community a complete suite of fully-featured, high-performance, API components to work with a Swagger API
Installation Go Swagger To install Go SWAGGER in Mac, type following command
brew tap go-swagger/go-swagger
brew install go-swagger
Once Installation complete go to project repo and generate swagger documentation by following command
swagger serve -F=swagger ./swagger.yml
Also created nice Makefile for the same, to run via make enter:
make serve-swagger
** Swagger UI**
This Project contains a golang implementation of Swagger 2.0 (aka OpenAPI 2.0): it knows how to serialize and deserialize swagger specifications.
go-swagger
brings to the go community a complete suite of fully-featured, high-performance, API components to work with a Swagger API
Installation Go Swagger To install Go SWAGGER in Mac, type following command
brew tap go-swagger/go-swagger
brew install go-swagger
Once Installation complete go to project repo and generate swagger documentation by following command
swagger serve -F=swagger ./swagger.yml
Also created nice Makefile for the same, to run via make enter:
make serve-swagger
** Swagger UI**
POST
: Create GenrePUT
: update GenreGET
: Get all active GenreGET
: Get One genre - specified by Id or Genre slugDELETE
: delete genre - Soft delete by specified id or slugPOST
: Create PublisherPUT
: update PublisherGET
: Get all active PublisherGET
: Get One Publisher - specified by Id or Genre slugDELETE
: delete Publisher - Soft delete by specified id or slugPOST
: Create AuthorPUT
: update AuthorGET
: Get all active AuthorGET
: Get One Author - specified by Id or Genre slugDELETE
: delete Author - Soft delete by specified id or slugPOST
: Create BookPUT
: update BookGET
: Get all BooksGET
: Get One Book - specified by IdDELETE
: delete Book - Soft delete by IdGET
: Search book - by its NamePOST
: Create UserPUT
: Verify BookFeel free to open an issue if you come across any bugs or if you'd like to request a new feature.
git checkout -b new-feature
)git commit -am 'Some cool changes'
)git push origin new-feature
)