Go API Boilerplate

A slightly opinionated HTTP API boilerplate with the Go programming language, following (some) Clean Architecture principles.

Features

• HTTP server with net/http;
• Testing suites, assertions and mocks with testify;
• Live reload with air;
• Logging with zerolog;
• Configuration with viper;
• PostgreSQL database connection with pgx and sqlx
• Pre-configured CI job with Github Actions;
• JWT authentication (under the with-auth branch)

Project structure

.
├── cmd
│   └── api                    <== Application entrypoint
├── config                     <== Configurations setup
├── docs                       <== Auto-generated OpenAPI documents
├── internal
│   ├── domain                 <== Domain objects with their own contracts and business logic
│   ├── infra                  <== Everything related to the infrastructure layer, such as databases, web handlers, queues etc
│   │   ├── database
│   │   │   ├── models         <== Objects representing database entities
│   │   │   └── repositories   <== Database operations and queries
│   │   ├── gateways           <== Objects that encapsulates access to infra resources, following an interface defined by each use-case
│   │   └── web                <== Everything related to the HTTP REST API
│   │       ├── handlers       <== "Controllers"
│   │       │   └── dto        <== Input and output objects
│   │       └── middlewares    <== Request middlewares
│   ├── pkg                    <== Shared code that doesn't contain business logic, but are needed to support other packages
│   │   ├── apierror           <== Error returned to the API client
│   │   ├── apperror           <== Internal error object
│   │   ├── di                 <== Dependency injection resolver, where everything is glued together
│   │   └── logger             <== Logging utilities
│   ├── tests                  <== Testing utilities
│   │   ├── fixtures           <== Pre-built objects for test cases
│   │   └── mocks              <== Methods mocks for necessary packages
│   └── usecases               <== Main business rules
│       └── counter
├── migrations                 <== Database migrations generated with `migrate`
├── scripts                    <== Utilitarian shell scripts

Requirements

• Go 1.24 (or newer)
• GNU Make
• Docker
• air: live-reloading
• migrate: database migrations

First run

1. Create .env file

cp .env.example .env

2. Rename packages to your project's name

make rename-pkgs

3. Run setup script

make setup

Running locally

To start a local server with live-reload and all necessary containers, execute:

make run

Testing

To execute all test suites and get a coverage report at the end, just run:

make test

Building for production

With Docker

There's a Dockerfile.prod included with the project to build an optimized image based on distroless, so you just need to adapt it for your needs and publish to your desired registry.

# This should be set by your CI/CD system
export BUILD_ID="$(uuidgen)"

# Building the image
docker build . \
  -t mathcale/go-api-boilerplate \
  -f Dockerfile.prod \
  --build-arg BUILD_ID

# Clean intermediate images
docker image prune \
  --filter label=stage=builder \
  --filter label=build=$BUILD_ID

Manually

By running the following command, the application will be compiled and outputted to the bin directory.

make build

Next Steps

• Add database connection
• Add logging middleware
• Add Github Actions CI workflow
• Add database
• Add authentication branch
• Add OpenAPI specs on web handlers
• Improve project structure documentation