golang-backend-boilerplate

Basic golang boilerplate for backend projects.

Key features:

• cobra - CLI interactions
• viper - Configuration management
• apigen - API layer generator
• uber dig is used as DI framework
  • for small projects it may make sense to setup dependencies manually
• slog is used for logs
• slog-http is used to produce access logs
• testify and mockery are used for tests
• gow is used to watch and restart tests or server

Starting a new project

• Clone the repo with a new name

• Replace module name with desired one. Example:

  find . -name "*.go" -o -name "go.mod" | xargs sed -i 's|github.com/gemyago/golang-backend-boilerplate|<YOUR-MODULE-PATH>|g';

  Note: on osx you may have to install and use gnu sed. In such case you may need to replace sed with gsed above.

Project structure

• cmd/server is a main entrypoint to start the server
• cmd/jobs is a main entrypoint to start jobs
• internal/api/http - includes http routes related stuff
  • internal/api/http/v1routes.yaml - OpenAPI spec for the api routes. HTTP layer is generated with apigen
• internal/app - place to add application layer code (e.g business logic).
• internal/services - lower level components are supposed to be here (e.g database access layer e.t.c).

Project Setup

Please have the following tools installed:

• direnv
• gobrew

Install/Update dependencies:

# Install
go mod download
go install tool

# Update:
go get -u ./... && go mod tidy

Build dependencies

This step is required if you plan to work on the build tooling. In this case please make sure to install:

• pyenv.

# Install required python version
pyenv install -s

# Setup python environment
python -m venv .venv

# Reload env
direnv reload

# Install python dependencies
pip install -r requirements.txt

If updating python dependencies, please lock them:

pip freeze > requirements.txt

Development

Lint and Tests

Run all lint and tests:

make lint
make test

Run specific tests:

# Run once
go test -v ./internal/api/http/v1controllers/ --run TestHealthCheck

# Run same test multiple times
# This is useful to catch flaky tests
go test -v -count=5 ./internal/api/http/v1controllers/ --run TestHealthCheck

# Run and watch. Useful when iterating on tests
gow test -v ./internal/api/http/v1controllers/ --run TestHealthCheck

Run local API server:

# Regular mode
go run ./cmd/server/ start

# Watch mode (double ^C to stop)
gow run ./cmd/server/ start