Boilerplate Go Backend

Boilerplate project for golang backend.

Getting Started

Prerequisite for this project:

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

Command lines:

# 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

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
  • PostgresSQL Database -- Check the code at internal/app/infra/database/postgres.go
    • Connection pool
  • Audit Columns (created_at, modified_at, etc)
  • User AuditTrail (Transaction Logs)
  • Migration tool with golang-migrate
• Security and Observability
  • Basic Auth -- Check the code at internal/app/infra/auth/basic.go
  • OAuth2 with Go-OAuth2 -- Check the code at internal/app/infra/auth/oauth.go
    • Handle authorize request
    • Handle token request
    • Validate bearer token
    • Validate scope access
  • Enable expvar endpoint (/debug/vars)
  • Enable pprof endpoint (/debug/pprof)
  • Structured Log with ZeroLog -- Check the code at /internal/app/infra/logger/logger.go
    • 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

• For Client App
  • Clock-in
  • Clock-out
• For Backoffice Dashboard
  • Manage Employee
  • Employee Clock History

Notes

• The project is OPINIONATED based on author knowledge and experience
• The project is PRAGMATIC, it use the other popular/proven go library 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 this as his actual project reference 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 a popular and faster web framework compared to Echo. The caveat is that fiber is based on fasthttp and not compatible with net/http which is cumbersome if we use other net/http based project (in our case, go-oauth2).

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

[email protected]

License

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