Boilerplate Go Backend

Boilerplate for golang backend project.

Prerequisite

Programming Language: Go
Task Manager/Build-Tool: GoTask
DB Migration Tool: Golang-Migrate
Infrastructure: Docker

Getting Started

# First setup for mac (for other OS, please refer to respective documentation)
brew install go
brew install go-task
brew install golang-migrate

task --list-all   # Show available tasks
task run          # Run the project
task clean        # Clean the dev local environment

task gen-oapi        # Generate open-api controller from api-spec.yaml
task gen-dotenv      # Generate .env file from config struct
task gen-entity      # Generate entity/repo from database table
task gen-converter   # Generate converter from DAO to Entity and vice-versa

task create-migration NAME=create_some_table   # Create new migration file

Tech Overview

Framework/library:

Echo: High performance, minimalist Go web framework
OApi-CodeGen: Generate Go client and server boilerplate from OpenAPI 3 specifications
Go-Auth2: OAuth 2.0 server library for the Go programming language
Go-Mock: a mocking framework for the Go programming language
Dig: A reflection based dependency injection toolkit for Go.
Squirrel: Fluent SQL generation for golang
Zerolog: Zero Allocation JSON Logger

Database:

Relational Database: Postgres
In-Memory Database: Redis

Project Checklist

General
- Golang Standards Project Layout
- Dependency Injection with Uber Dig -- Check the code at internal/app/infra/di/di.go
- Centralized config (env variable) -- Check the code at internal/app/infra/config/config.go
- Graceful Shutdown -- Check the code at cmd/boilerplate-go-backend/main.go
- Health check -- Check the code at internal/app/health.go
API Server
- OpenAPI Specification 3.0 -- Check the specification at api/api-spec.yml
  - Enable swagger-ui (/swagger/ui)
- Echo Framework -- Check the router at internal/app/router.go
  - Recovery from panic
  - Generate Request ID
  - Protection against XSS attack and other common security threats
  - Custom error handler
  - Server-Side Cache (Redis)
  - Rate Limiter (Redis)
RESTful API
- POST Create operation
- GET Read operation
  - Single entity
  - Entity List
  - Pagination
  - Search / Filtering
  - Sorting
- UPDATE Update operation
- PATCH Partially update operation
- DELETE Delete operation
  - Soft-Delete
  - Idempotent
Layered Architecture
- Controller Layer -- Generated by oapi-codegen
- Business Logic Layer (Services) -- Check the code at internal/app/service
  - Validation Logics
  - Trigger Database Transaction (BEGIN) -- Check dbtxn library
- Data Access Layer (Repos) - Generated by tools/entity-gen
  - ORMHate Philosophy
  - Query Builder (using Squirrel)
Database
- Connection pool -- Check the code at internal/app/infra/database/postgres.go
- Audit Columns (created_at, modified_at, etc)
- Migration tool with golang-migrate
- Data seeding to insert initial dummy data to database -- Check the tool at tools/dbseed
- User AuditTrail (Transaction Logs)
Security and Observability
- Basic Auth -- Check the code at internal/app/infra/auth/basic.go
- OAuth2 with Go-OAuth2
  - Use Postgres to store oauth-client -- Check the code at internal/app/infra/auth/oauth_client_store.go
  - Use Redis to store oauth-token
  - Handle authorize request and token access
  - Validate bearer token and scope access -- Check the code at internal/app/infra/auth/oauth_handler.go
- Enable expvar endpoint (/debug/vars)
- Enable pprof endpoint (/debug/pprof)
- Structured Log with ZeroLog -- Check the code at /internal/app/infra/logger
  - Pretty format (not json) when debug enabled
  - Escalate log level to WARN for slow API
  - Append log field pid
  - Append log field go_version
  - Append log field latency
  - Append log field request_id
  - Append log field user_id
- Open Tracing
Code Generator
- Generate Server Interface and Controller Layer with oapi-codegen -- Check the config at tools/openapi-gen
- Generate Dotenv file from Config struct -- Check the tool at tools/dotenv-gen
- Generate Entity Model and Repository Layer from Database schema -- Check the tool at tools/entity-gen
- Generate Converter from DAO to Entity and vice-versa -- Check the tool at tools/converter-gen
Testing
- Table Driven Test -- Check the code at internal/app/service/employee_svc_test.go
- Mocking object with GoMock
- API Test Automation
Others
- Build tool with TaskFile (a better alternative from GNU Make)
- Dockerfile
- Docker-compose

Study Case: Employee Clocking System

The project use employee clocking system as the study case

Client App API
- Clock-in
- Clock-out
Backoffice Dashboard API
- Manage Employee
- Employee Clock History

Notes

The project is OPINIONATED based on author knowledge and experience
The project is PRAGMATIC, it use proven libraries/frameworks as much as possible without reinvented the wheel
The project is MONOLITH BACKEND, you may need to customize code for microservices needs
This is CONTINUOUS PROJECT, the author use it as his actual work and keep improve it
The project is OPEN-FOR-DISCUSSION, feel free to ping the author for any feedback/question and/or open issue ticket

FAQ

Echo VS Fiber?

Fiber is arguably better than Echo but is not compatible with net/http (it is based on fasthttp). We use go-oauth2 who only support net/http, therefore we choose to use Echo instead.
Pgx for postgres?

Pgx is a faster and more compatible postgres driver compared with pq. There are 2 ways to use pgx: through database/sql and direct implementation (which offer more capability) but not compatible with database/sql. We want to keep compatibility with database/sql to give flexibility to use other library.

Author

iman.tung@gmail.com

License

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

imantung/boilerplate-go-backend