typical-rest-server

typical-rest-server

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

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

How to Use

• References for project layout and code best practice.
• Shared library (pkg) is utility/helper to general use.
• For 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]
  

Builds

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

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

Project Layout

Typical-Rest encourage standard go project layout

Source codes:

• internal: Exclusive codes for the project
  • internal/app
    • internal/app/infra: infrastructure for the project e.g. config and connection object
    • internal/app/profiler: profiling/debug the project e.g. HealthCheck, PProf, etc
    • internal/app/server
      • internal/app/server/controller: presentation layer
      • internal/app/server/service: logic layer
      • internal/app/server/repository: data access layer
  • internal/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 and Table-Driven Test

• Presentation Layer at internal/app/server/controller
  • Handling HTTP routes
  • Parsing the request
  • Sending response (both success & error)
• Logic Layer at internal/app/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/app/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/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

License

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