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

Initial cleanup step:

• Clone the repo with a new name

• Replace module name with desired one. Example:

  # Manually specify desired module name
  find . -name "*.go" -o -name "go.mod" | xargs sed -i 's|github.com/gemyago/golang-backend-boilerplate|<YOUR-MODULE-PATH>|g';
  
  # Or optionally get module name matching repo
  export module_name=$(git remote get-url origin | sed -E \
    -e 's|^git@([^:]+):|\1/|' \
    -e 's|^https?://||' \
    -e 's|\.git$||')
  
  # and specify module name matching repo name
  find . -name "*.go" -o -name "go.mod" | xargs gsed -i "s|github.com/gemyago/golang-backend-boilerplate|${module_name}|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.

• Review and actualize deployment related files:

  • deploy/README.md
  • deploy/helm/api-service/values.yaml

• Adjust docker images cleanup to list your images cleanup-docker-images.yml

• Review and actualize README.md to match your project

  • Make sure to update status badge links at the top o this file to include your repo path.

Some test artifacts (like coverage and badges) are pushed to a separate orphan branch. Please follow steps below to prepare such a branch:

git checkout --orphan test-artifacts
git rm -rf .
rm -f .gitignore
echo $'# Test Artifacts\n' > README.md
echo 'This is an orphan branch that holds test artifacts produced by CI' >> README.md
git add README.md
git commit -m 'init'
git push origin test-artifacts

Feel free to use any other branch name. In this case please make sure to update all references and push-test-artifact.yml action.

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