typical-rest-server

README

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:

• /internal: private codes for the project
  • /app
    • /infra: infrastructure for the project e.g. config and connection object
    • /domain
      • /mylibrary
        • /controller: presentation for mylibrary domain
        • /service: logic for mylibrary domain
      • /mymusic
        • /controller: presentation for mymusic domain
        • /service: logic for mymusic domain
    • /data_access
      • /postgresdb: data access to postgresdb
      • /mysqldb: data access to postgresdb
  • /generated: code generated e.g. typical, grpc, xsd, etc.
• /pkg: shareable codes e.g. helper/utitily Library
• /cmd: the main package

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

• Presentation Layer at internal/app/domain/[DOMAIN]/controller
  • Handling HTTP routes
  • Parsing the request
  • Sending response (both success & error)
• Logic Layer at internal/app/domain/[DOMAIN]/service
  • Intermediary between controller (end-point) and repository (data)
  • Logic of controller
  • Data Validation
  • DTO (Data Transfer Object) Model
• Data Access Layer at internal/app/data_access/[DATABASE]
  • No logic except operation to database
  • Repository pattern
  • DAO (Data Access Object) Model
  • Database Entity or Business Entity

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:

• Go Documentation
• Go For Industrial Programming
• Uber Go Style Guide
• Go Code Review Comments

RESTful API:

• Best Practices for Designing a Pragmatic 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