Go Clean Architecture

Welcome to the documentation for go-clean-arch, a practical implementation of Robert C. Martin's (Uncle Bob) Clean Architecture in Go. This project serves as a clear, real-world example for developers looking to structure their Go applications in a way that is scalable, testable, and independent of external frameworks and dependencies.

The Problem It Solves

Modern software development often leads to tightly coupled codebases where business logic is entangled with database queries, framework specifics, and UI concerns. This makes the application difficult to test, maintain, and evolve. A change in the database, for example, could ripple through the entire system.

Clean Architecture addresses this by enforcing a strict separation of concerns through layers. The core principle is the Dependency Rule: source code dependencies can only point inwards. Nothing in an inner circle can know anything at all about something in an outer circle.

Clean Architecture Diagram

This project implements this concept with four primary layers:

  1. Domain (Models) Layer: The innermost circle, containing enterprise-wide business rules and data structures. It is the core of the application.
  2. Service (Usecase) Layer: Orchestrates the flow of data to and from the domain entities. It contains application-specific business rules.
  3. Repository Layer: Provides an abstraction layer for data sources. It implements interfaces defined by the usecase layer, decoupling the core logic from the database.
  4. Delivery Layer: The outermost layer, responsible for presenting data to the user. This could be a REST API, a gRPC server, or a command-line interface.

Key Features

  • Separation of Concerns: A clear distinction between business logic and implementation details (like databases or web frameworks).
  • Testability: Core business logic can be tested without any external dependencies like a database or a web server.
  • Framework Independence: The application is not tied to a specific web framework (it uses echo, but could be swapped) or database (it uses mysql, but the interface allows for others).
  • Service-Focused Packaging: The structure is organized around features or services (e.g., the article service), making the codebase intuitive to navigate.
  • Modern Go Practices: Utilizes Go modules, a clear internal package structure, and a comprehensive Makefile for development tasks.

Project History

This project has evolved over several versions, with each iteration refining the structure. The current main branch represents version 4, which emphasizes declaring interfaces on the consumer side and utilizing the internal package to hide implementation details. For a historical perspective, you can explore the v1, v2, and v3 branches of the repository.

Ready to get started? Head over to the Installation page.