README

Go-Workflow Go Report Card codebeat badge codecov

typical-rest-server

The project status is WIP (Work in progress) which means the author continously evaluate and improve the project.

Example project for Restful Server implementation for Golang.

  • Project Layout using Go-Standards
  • Powered by Echo framework
  • Layered architecture
  • RESTful API (GET, POST, PUT, PATCH, DELETE)
  • Config using Environment Variable
  • Dependency Injection
  • ORMHate and Repository Pattern
  • Table Driven Test style
  • Test using mock
  • Database migration and seed tool
  • Using Database Transaction in Service Layer
  • Health Check and Debug API
  • Request ID in logger

Run/Test Project

The project using typical-go as its build-tool. The descriptor can be found in tools/typical-build/typical-build.go

Edit .env to set the config

cp .env.sample .env    # copy the working .env

Run application:

./typicalw docker up   # equivalent with `docker-compose up -d`
./typicalw reset       # reset infra: drop, create and migrate postgres database 
./typicalw run         # run the application

Test application:

./typicalw mock        # generate mock (if new mock needed)
./typicalw test        # run test 

Project Layout

Typical-Rest encourage standard go project layout

Source codes:

Others directory:

  • /tools Supporting tool for the project e.g. Build Tool
  • /api Any related scripts for API e.g. api-model script (swagger, raml, etc) or client script
  • /databases Any related scripts for Databases e.g. migration scripts and seed data

Layered Architecture

Typical-Rest encourage layered architecture (as most adoptable architectural pattern) with SOLID Principle

Dependency Injection

Typical-Rest encourage dependency injection using uber-dig and annotations (@ctor for constructor and @dtor for destructor).

// OpenConn open new database connection
// @ctor
func OpenConn() *sql.DB{
}
// CloseConn close the database connection
// @dtor
func CloseConn(db *sql.DB){
}

Application Config

Typical-Rest encourage application config with environment variables using envconfig and annotation (@envconfig).

type (
  // AppCfg application configuration
  // @envconfig (prefix:"APP")
  AppCfg struct {
    Address string `envconfig:"ADDRESS" default:":8089" required:"true"`
    Debug   bool   `envconfig:"DEBUG" default:"true"`
  }
)

Generate usage documentation (USAGE.md) and .env file

// in typical-build

&typcfg.EnvconfigAnnotation{
  DotEnv:   ".env",     // generate .env file
  UsageDoc: "USAGE.md", // generate USAGE.md
}

Mocking

Typical-Rest encourage mocking using gomock and annotation(@mock).

type(
  // Reader responsible to read
  // @mock
  Reader interface{
    Read() error
  }
)

Mock class will be generated in *_mock package

References

Golang:

RESTful API:

Project Starter

To setup new project, please use rest-project-starter

curl -s https://raw.githubusercontent.com/typical-go/rest-project-starter/master/setup.sh | bash -s [project_name] [package_name]

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Expand ▾ Collapse ▴