go-clean-arch

Introduction to go-clean-arch

The go-clean-arch project exemplifies the implementation of Clean Architecture principles in Go (Golang) applications. This project aims to offer developers a structured and organized way to build their software while adhering to the key principles of Clean Architecture as proposed by Uncle Bob.

Background and Versions

The project's journey began with a proposal in 2017, evolving through several versions to improve its structure and capabilities.

• v1 (2017-2018): This initial version laid the foundation, focusing on the basic structure and principles of Clean Architecture in a Go environment, as detailed in an article.

• v2 (2018-2020): An improvement over v1, this version made refinements to the architecture, captured in another article.

• v3 (2019-2020): This iteration introduced a Domain package, enhancing the functionality and modularity of the architecture, documented in PR #21.

• v4 (2024): The latest version in the master branch. It focuses on restructuring by declaring interfaces on the consuming side and introducing the internal and Service-focused packages, elaborated in PR #88.

Clean Architecture Principles

The architecture is guided by several core principles:

• Independence from Frameworks: Allows using frameworks as tools without constraining the system.
• Testability: Business rules can be tested independently of interfaces, databases, and other external aspects.
• UI Independence: The UI can be altered or replaced without affecting business rules.
• Database Independence: Different databases can be interchanged without binding business logic.
• External Agency Independence: Business rules lack knowledge of external influences.

These principles ensure that the architecture remains flexible, allowing easy maintenance and enhancements over time. More insights can be found in Uncle Bob's original description here.

Domain Layers

The application is organized into four main domain layers:

• Models Layer: Defines data structures and models essential for the application.
• Repository Layer: Manages data retrieval and storage operations.
• Usecase Layer: Contains business logic and rules.
• Delivery Layer: Handles presentation logic and user interaction.

The structure enables a robust separation of concerns, allowing each layer to evolve independently.

Getting Started

To run the project, first ensure the article.sql is executed in your MySQL setup. The project leverages Go Modules, making it easy to manage dependencies without needing to place it inside GOPATH.

Testing and Running the Application

Install the necessary dependencies and run the tests using:

$ make tests

To deploy the application, use Docker Compose:

# Go to your workspace and clone the repository
$ cd workspace
$ git clone https://github.com/bxcodec/go-clean-arch.git

# Enter the project directory
$ cd go-clean-arch

# Copy the configuration
$ cp example.env .env

# Start the application
$ make up

# Use another terminal to execute a test request
$ curl localhost:9090/articles

Tools and Libraries

The project employs various tools listed in its go.mod file. It also uses "github.com/vektra/mockery" for generating test mocks, promoting thorough testing capabilities.

The go-clean-arch project offers a practical implementation of Clean Architecture principles, encouraging developers to adopt a structured approach to building and scaling Go applications. Each version builds upon its predecessor, introducing improvements that facilitate a modular and maintainable codebase.