typical-rest-server

typical-rest-server

Opinionated, simple and straight forward Restful server implementation for Golang.

How to Use

• Use the project as reference for project layout and code best practice.
• The pkg package is shared library that can help in various needs.

Prerequisite

• Go
• Docker-Compose

Quick Start

The project using typical-go as its build-tool.

Run applicaton

./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 needed)
./typicalw test        # run test 

Project Layout

Typical-Rest encourage standard go project layout

• internal Exclusive go source files for the project
  • internal/app main functionality/entry-point
  • internal/infra infrastructure for the project e.g. config and connection object
  • internal/profiler profiling/debug the project e.g. HealthCheck, PProf, etc
  • internal/server server controller/logic
  • internal/generated code generated from annotation
• pkg Shareable go source files e.g. helper/utitily Library
• 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
• tools Supporting tool for the project e.g. Build Tool

Layered Architecture

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

• Presentation Layer at internal/server/controller
  • Handling HTTP routes
  • Parsing the request
  • Sending response (both success & error)
• Logic Layer at internal/server/service
  • Intermediary between controller (end-point) and repository (data)
  • Logic of controller
  • Data Validation
  • DTO (Data Transfer Object) Model
• Data Access Layer at internal/server/repository
  • 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

ORM Hate

Typical-Rest do not encourage Objection-Relation-Mapping/ORM (ORM Hate)

Shared Library

The pkg contain useful library for general needs

• pkg/typrest Utility for rest application e.g. health check, error, etc
• pkg/dbkit Utility for database operation
• pkg/dbtxn Utility for database transaction
• pkg/dockerrx Docker Recipe Collection to be generated by typical-go
• pkg/echotest Utility for table-driven test echo handler

3rd-Party Library

The project use go modules to manage package dependency. The compelete library list can be found in go.mod.

• Echo Framework: Web Framework
• dig: Dependency Injection
• gomock: Mock for interface
• logrus: Logging
• testify: Test assertion
• squirrel: SQL Query Builder
• go-sqlmock: Mock for database connection

Golang References

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

Project Status

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

License

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