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

1. 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.

2. 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