go-clean-starter

🇯🇵 日本語

This is a Go template of clean architecture to ease and boost up a backend development with up to date libraries utilizing clean architecture as design.

Requirements

Name	Used for
Go	for backend application
Docker and docker-compose	for containers
goimports	for formatting source code
golangci-lint	for linting source code

Overview

This app has three containers.

• api to run api server
• task to run task
• postgres for database

Architecture

┌────────────────────────────────────────────┐
│           Docker Compose Project           │
│                                            │
│    ┌──────────────┐   ┌────────────────┐   │
│    │     API      │   │   Task-Runner  │   │
│    │    (HTTP)    │   │   (CLI Tasks)  │   │
│    └───────┬──────┘   └───────┬────────┘   │
│            │                  │            │
│            ▼                  ▼            │
│     ┌────────────────────────────────┐     │
│     │          PostgreSQL DB         │     │
│     │     (go_clean_starter DB)      │     │
│     └────────────────────────────────┘     │
└────────────────────────────────────────────┘

Key Technologies

• Go: Primary language for high performance, simplicity, and strong concurrency support
• Echo: Fast and lightweight HTTP web framework with clean routing and rich middleware support
• PostgreSQL: Reliable database with advanced features like JSONB, full-text search, and strong consistency
• sqlc: Generates type-safe Go code from raw SQL queries for compile-time safety and better performance
• golang-migrate: Handles database schema migrations with version control, locking, and rollback support
• oapi-codegen: Generates Go structs and types from OpenAPI specifications for type-safe API development
• Wire: Compile-time dependency injection for clean, type-safe, and maintainable object initialization
• Air: Hot reload tool for fast development cycles with automatic rebuilds on file changes
• Docker & Docker Compose: Containerization for consistent development and deployment environments

Directory structure

go-clean-starter
├── builder
│   ├── dependency.go
│   ├── wire.go         # manually written wire code
│   └── wire_gen.go     # wire code auto generated by `wire.go`
├── cmd
│   ├── migration.go    # command to run migration
│   ├── serve.go        # command to run API server
│   └── task.go         # commands to run tasks (currently only one task is defined here)
├── config
├── domain # domain models
├── go.sum
├── internal
│   ├── http # http layer
│   │   ├── base
│   │   ├── handler
│   │   │   ├── errors.go
│   │   │   ├── openapi_types.gen.go # auto generated Go structs by doc/api.yaml
│   │   │   └── user
│   │   ├── middleware
│   │   └── server.go
│   ├── repository # data access layer
│   │   ├── item
│   │   ├── user
│   │   └── transaction.go
│   ├── service # business logic layer
│   │   └── user
│   ├── sqlc # sqlc input & output
│   │   ├── query
│   │   │   ├── items.sql
│   │   │   └── users.sql
│   │   ├── db.go
│   │   ├── items.sql.go
│   │   ├── models.go
│   │   └── users.sql.go
│   └── task # task program such as job, batch, etc...
│       └── item
│           ├── data
│           │   └── item.csv
│           ├── item.go
│           └── usecase.go
├── main.go
├── migration
│   ├── migrate.go
│   └── sql # migration sql files
├── pkg                         # pkg is empty now. add packages that can be imported by other projects
├── README.md
├── WHY.md                      # document to explain why this tech stack and tech specifications are choosen
├── docker-compose.test.yaml
├── docker-compose.yaml
└── sqlc.yaml                    # configuration of sqlc

Setup

Setup environment values

• create .env by copying .env.sample

cp .env.sample .env

Docker

• run make build to build Docker images

make build

• run make up to create and run Docker containers by docker-compose

make up

💡 This project uses air, which is Go hot reload. Hot reload helps us to develop faster.

Test

• run make test to test make test will create a test environment using the test specific docker-compose.test.yaml with the same Dockerfile as development. Thus safety of test environment is assured as it's separated from local environment for development.

make test

API Usage

Once the server is running, you can interact with the API:

📋 Complete API documentation is available in api.yaml - OpenAPI 3.1 specification with all endpoints, schemas, and examples.

Health Check

curl http://localhost:8080/health

Getting Help

• Check Issues for known problems
• Review WHY.md for architecture decisions

Contributions

read CONTRIUTING.md to contribute to this project.