go-gin-sql-sample

To run the application

go run main.go

Architecture

Simple Layer Architecture

Layer Architecture with full features

core-go/search

• Build the search model at http handler
• Build dynamic SQL for search
  • Build SQL for paging by page index (page) and page size (limit)
  • Build SQL to count total of records

Search users: Support both GET and POST

POST /users/search

Request: POST /users/search

In the below sample, search users with these criteria:

• get users of page "1", with page size "20"
• email="tony": get users with email starting with "tony"
• dateOfBirth between "min" and "max" (between 1953-11-16 and 1976-11-16)
• sort by phone ascending, id descending

{
    "page": 1,
    "limit": 20,
    "sort": "phone,-id",
    "email": "tony",
    "dateOfBirth": {
        "min": "1953-11-16T00:00:00+07:00",
        "max": "1976-11-16T00:00:00+07:00"
    }
}

GET /users/search?page=1&limit=2&email=tony&dateOfBirth.min=1953-11-16T00:00:00+07:00&dateOfBirth.max=1976-11-16T00:00:00+07:00&sort=phone,-id

In this sample, search users with these criteria:

• get users of page "1", with page size "20"
• email="tony": get users with email starting with "tony"
• dateOfBirth between "min" and "max" (between 1953-11-16 and 1976-11-16)
• sort by phone ascending, id descending

Response:

• total: total of users, which is used to calculate numbers of pages at client
• list: list of users

{
    "list": [
        {
            "id": "ironman",
            "username": "tony.stark",
            "email": "[email protected]",
            "phone": "0987654321",
            "dateOfBirth": "1963-03-24T17:00:00Z"
        }
    ],
    "total": 1
}

API Design

Common HTTP methods

• GET: retrieve a representation of the resource
• POST: create a new resource
• PUT: update the resource
• PATCH: perform a partial update of a resource, refer to core-go/core and core-go/sql
• DELETE: delete a resource

API design for health check

To check if the service is available.

Request: GET /health

Response:

{
    "status": "UP",
    "details": {
        "sql": {
            "status": "UP"
        }
    }
}

API design for users

Resource: users

Get all users

Request: GET /users

Response:

[
    {
        "id": "spiderman",
        "username": "peter.parker",
        "email": "[email protected]",
        "phone": "0987654321",
        "dateOfBirth": "1962-08-25T16:59:59.999Z"
    },
    {
        "id": "wolverine",
        "username": "james.howlett",
        "email": "[email protected]",
        "phone": "0987654321",
        "dateOfBirth": "1974-11-16T16:59:59.999Z"
    }
]

Get one user by id

Request: GET /users/:id

GET /users/wolverine

Response:

{
    "id": "wolverine",
    "username": "james.howlett",
    "email": "[email protected]",
    "phone": "0987654321",
    "dateOfBirth": "1974-11-16T16:59:59.999Z"
}

Create a new user

Request: POST /users

{
    "id": "wolverine",
    "username": "james.howlett",
    "email": "[email protected]",
    "phone": "0987654321",
    "dateOfBirth": "1974-11-16T16:59:59.999Z"
}

Response: 1: success, 0: duplicate key, -1: error

1

Update one user by id

Request: PUT /users/:id

PUT /users/wolverine

{
    "username": "james.howlett",
    "email": "[email protected]",
    "phone": "0987654321",
    "dateOfBirth": "1974-11-16T16:59:59.999Z"
}

Response: 1: success, 0: not found, -1: error

1

Patch one user by id

Perform a partial update of user. For example, if you want to update 2 fields: email and phone, you can send the request body of below.

Request: PATCH /users/:id

PATCH /users/wolverine

{
    "email": "[email protected]",
    "phone": "0987654321"
}

Response: 1: success, 0: not found, -1: error

1

Delete a new user by id

Request: DELETE /users/:id

DELETE /users/wolverine

Response: 1: success, 0: not found, -1: error

1

Common libraries

• core-go/health: include HealthHandler, HealthChecker, SqlHealthChecker
• core-go/config: to load the config file, and merge with other environments (SIT, UAT, ENV)
• core-go/log: logging
• core-go/log/gin: middleware log tracing for gin

core-go/health

To check if the service is available, refer to core-go/health

Request: GET /health

Response:

{
    "status": "UP",
    "details": {
        "sql": {
            "status": "UP"
        }
    }
}

To create health checker, and health handler

    db, err := sql.Open(cfg.Driver, cfg.DataSourceName)
    if err != nil {
        return nil, err
    }

    sqlChecker := s.NewSqlHealthChecker(db)
    healthHandler := health.NewHealthHandler(sqlChecker)

core-go/config

To load the config from "config.yml", in "configs" folder

package main

import "github.com/core-go/config"

type Config struct {
    DB DatabaseConfig `mapstructure:"db"`
}

type DatabaseConfig struct {
    Driver         string `mapstructure:"driver"`
    DataSourceName string `mapstructure:"data_source_name"`
}

func main() {
    var cfg Config
    err := config.Load(&cfg, "configs/config")
    if err != nil {
        panic(err)
    }
}

To configure to ignore the health check, use "skips":

middleware:
  skips: /health