Golang has carved out a solid reputation as a fast, efficient language that prioritizes simplicity, which is one of the reasons why it’s so commonly used for backend services, microservices, and infrastructure tooling. However, as more developers from languages like Java and C# transition to Go, questions about implementing Clean Architecture arise. For those used to Clean Architecture’s layer-based approach to structuring applications, it can feel intuitive to apply the same principles to Go. However, as we’ll explore, trying to implement Clean Architecture in Go often backfires. Instead, we'll look at a structure tailored for Go’s strengths that’s more straightforward, flexible, and aligns with Go’s “keep it simple” philosophy.
Why Clean Architecture Feels Out of Place in Go
The goal of Clean Architecture, championed by Uncle Bob (Robert C. Martin), is to create software that’s modular, testable, and easy to extend. This is achieved by enforcing separation of concerns between layers, with core business logic kept isolated from external concerns. While this works well in highly object-oriented languages like Java, it introduces friction in Go. Here’s why:
1. Go’s Minimalism Fights Against Excessive Abstractions
In Go, there’s a strong emphasis on readability, simplicity, and reduced overhead. Clean Architecture introduces layers upon layers of abstractions: interfaces, dependency inversion, complex dependency injection, and service layers for business logic. However, these extra layers tend to add unnecessary complexity when implemented in Go.
Let’s take Kubernetes as an example. Kubernetes is a massive project built in Go, but it doesn’t rely on Clean Architecture principles. Instead, it embraces a flat, function-oriented structure that’s focused around packages and subsystems. You can see this in the Kubernetes GitHub repository, where packages are organized by functionality rather than rigid layers. By grouping code based on functionality, Kubernetes achieves high modularity without complex abstractions.
The Go philosophy prioritizes practicality and speed. The language’s creators have consistently advocated for avoiding over-architecting, favoring straightforward implementations. If an abstraction isn’t absolutely necessary, it doesn’t belong in Go code. Go’s creators even designed the language without inheritance to avoid the pitfalls of over-engineering, encouraging developers to keep their designs clean and clear.
2. Dependency Injection is Limited by Design
Clean Architecture leans heavily on Dependency Injection to decouple different layers and make modules more testable. In languages like Java, DI is a natural part of the ecosystem thanks to frameworks like Spring. These frameworks handle DI automatically, allowing you to wire dependencies together with ease, without cluttering your code.
However, Go lacks a native DI system, and most DI libraries for Go are either overly complex or feel unidiomatic. Go relies on explicit dependency injection via constructor functions or function parameters, keeping dependencies clear and avoiding “magic” hidden in DI containers. Go’s approach makes code more explicit, but it also means that if you introduce too many layers, the dependency management becomes unmanageable and verbose.
In Kubernetes, for example, you don’t see complex DI frameworks or DI containers. Instead, dependencies are injected in a straightforward manner using constructors. This design keeps the code transparent and avoids the pitfalls of DI frameworks. Golang encourages using DI only where it truly makes sense, which is why Kubernetes avoids creating unnecessary interfaces and dependencies just for the sake of following a pattern.
3. Testing Becomes More Complex with Too Many Layers
Another challenge with Clean Architecture in Go is that it can make testing unnecessarily complicated. In Java, for instance, Clean Architecture supports robust unit testing with heavy use of mocks for dependencies. Mocking allows you to isolate each layer and test it independently. However, in Go, creating mocks can be cumbersome, and the Go community generally favors integration testing or testing with real implementations wherever possible.
In production-grade Go projects, such as Kubernetes, testing isn’t handled by isolating each component but by focusing on integration and end-to-end tests that cover real-life scenarios. By reducing the abstraction layers, Go projects like Kubernetes achieve high test coverage while keeping tests close to actual behavior, which results in more confidence when deploying in production.
The Best Architectural Approach for Golang
So if Clean Architecture doesn’t fit well with Go, what does? The answer lies in a simpler, more functional structure that emphasizes packages and focuses on modularity over strict layering. One effective architectural pattern for Go is based on Hexagonal Architecture, often known as Ports and Adapters. This architecture allows for modularity and flexibility without excessive layering.
The Golang Standards Project Layout is a great starting point for creating production-ready projects in Go. This structure provides a foundation for organizing code by purpose and functionality rather than by architectural layer.
Go Project Structure: A Practical Example
You're absolutely right! Structuring Go projects with a package-focused approach, where functionality is broken down by packages rather than a layered folder structure, aligns better with Go’s design principles. Instead of creating top-level directories by layers (e.g., controllers, services, repositories), it’s more idiomatic in Go to create cohesive packages, each encapsulating its own models, services, and repositories. This package-based approach reduces coupling and keeps code modular, which is essential for a production-grade Go application.
Let’s look at a refined, package-centric structure suited for Go:
/myapp
/cmd // Entrypoints for different executables (e.g., main.go)
/myapp-api
main.go // Entrypoint for the main application
/config // Configuration files and setup
/internal // Private/internal packages (not accessible externally)
/user // Package focused on user-related functionality
models.go // Data models and structs specific to user functionality
service.go // Core business logic for user operations
repository.go // Database access methods for user data
/order // Package for order-related logic
models.go // Data models for orders
service.go // Core order-related logic
repository.go // Database access for orders
/pkg // Shared, reusable packages across the application
/auth // Authorization and authentication package
/logger // Custom logging utilities
/api // Package with REST or gRPC handlers
/v1
user_handler.go // Handler for user-related endpoints
order_handler.go // Handler for order-related endpoints
/utils // General-purpose utility functions and helpers
go.mod // Module file
Key Components in the Package-Based Structure
/cmd
This folder is the conventional location for the application's entry points. Each subfolder here represents a different executable for the app. For example, in microservice architectures, each service can have its own directory here with its main.go. The code here should be minimal, responsible only for bootstrapping and setting up dependencies.
/config
Stores configuration files and setup logic, such as loading environment variables or external configuration. This package can also define structures for application configuration.
/internal
This is where the core logic of the application resides, split into packages based on functionality. Go restricts access to internal packages from external modules, keeping these packages private to the application. Each package (e.g., user, order) is self-contained, with its own models, services, and repositories. This is key to Go’s philosophy of encapsulation without excessive layering.
/internal/user– Manages all user-related functionality, including models (data structures), service (business logic), and repository (database interaction). This keeps user-related logic in one package, making it easy to maintain./internal/order– Similarly, this package encapsulates order-related code. Each functional area has its own models, services, and repositories.
/pkg
pkg holds reusable components that are used across the application but aren’t specific to any one package. Libraries or utilities that could be used independently, such as auth for authentication or logger for custom logging, are kept here. If these packages are particularly useful, they can also be extracted to their own modules later on.
/api
The API package serves as the layer for HTTP or gRPC handlers. Handlers here handle incoming requests, invoke services, and return responses. Grouping handlers by API version (e.g., v1) is a good practice for versioning and helps keep future changes isolated.
/utils
General-purpose utilities that aren’t tied to any specific package but serve a cross-cutting purpose across the codebase (e.g., date parsing, string manipulation). It’s helpful to keep this minimal and focused on purely utility functions.
Example Code Layout for the user Package
To illustrate the structure, here’s a closer look at what the user package might look like:
models.go
// models.go - Defines the data structures related to users
package user
type User struct {
ID int
Name string
Email string
Password string
}
service.go
// service.go - Contains the core business logic for user operations
package user
type UserService struct {
repo UserRepository
}
// NewUserService creates a new instance of UserService
func NewUserService(repo UserRepository) *UserService {
return &UserService{repo: repo}
}
func (s *UserService) RegisterUser(name, email, password string) error {
// Business logic for registering a user
newUser := User{Name: name, Email: email, Password: password}
return s.repo.Save(newUser)
}
repository.go
// repository.go - Defines database interaction methods for users
package user
type UserRepository interface {
Save(user User) error
FindByID(id int) (*User, error)
}
type userRepositoryImpl struct {
// database connection or ORM
}
func NewUserRepository() UserRepository {
return &userRepositoryImpl{}
}
func (r *userRepositoryImpl) Save(user User) error {
// Logic to save user to database
return nil
}
func (r *userRepositoryImpl) FindByID(id int) (*User, error) {
// Logic to retrieve a user by ID from the database
return &User{}, nil
}
Why This Package-Based Structure is Ideal for Go
This structure aligns well with Go’s idioms:
- Encapsulation
By organizing packages based on functionality, the code is naturally encapsulated and modular. Each package owns its models, services, and repositories, keeping the code cohesive and highly modular. This makes it easier to navigate, understand, and test individual packages.
- Minimal Interfaces
Interfaces are only used at the package boundaries (e.g., UserRepository), where they make the most sense for testing and flexibility. This approach reduces the clutter of unnecessary interfaces, which can make Go code harder to maintain.
- Explicit Dependency Injection
Dependencies are injected via constructor functions (e.g., NewUserService). This keeps dependencies explicit and avoids the need for complex dependency injection frameworks, staying true to Go’s simplicity-focused design.
- Reusability in
/pkg
Components like auth and logger in the pkg directory can be shared across packages, promoting reusability without excessive coupling.
- Clear API Structure
By grouping handlers under /api, it’s easy to scale the API layer and add new versions or handlers as the application grows. Each handler can focus on handling requests and coordinating with services, keeping the code modular and clean.
This package-centric structure lets you scale as you add more domains (e.g., product, inventory), each with its own models, services, and repositories. The separation by domain aligns with Go’s idiomatic way of organizing code, staying true to simplicity and clarity over rigid layering.
Opinions and Real-World Experiences
In my experience working with Go, Clean Architecture often complicates the codebase without adding significant value. Clean Architecture tends to make sense when building large, enterprise-grade applications in languages like Java, where there’s a lot of built-in support for DI, and managing deep inheritance structures is a common need. However, Go’s minimalism, its simplicity-first mindset, and its straightforward approach to concurrency and error handling create a different ecosystem altogether.
Conclusion: Embrace Go’s Idiomatic Architecture
If you’re coming from a Java background, it might be tempting to apply Clean Architecture to Go. However, Go’s strengths lie in simplicity, transparency, and modularity without heavy abstraction. An ideal architecture for Go prioritizes packages organized by functionality, minimal interfaces, explicit DI, realistic testing, and adapters for flexibility.
When designing a Go project, look to real-world examples like Kubernetes, Vault and the Golang Standards Project Layout. These showcase how powerful Go can be when the architecture embraces simplicity over rigid structure. Rather than trying to make Go fit a Clean Architecture mold, embrace an architecture that’s as straightforward and efficient as Go itself. This way, you’re building a codebase that’s not only idiomatic but one that’s easier to understand, maintain, and scale.
Top comments (4)
i was trying to make a clean architecture project template and also reviewing many of the currently existing templates, i can totally relate to the pitfalls you've pointed out, especially the one where you've mentioned dependency injection for it is at the heart of clean architecture.
since that time i'm trying to build a dependency injection framework for Go that is as simple and lightweight as possible and can utilizes generics while keeping the bare minimum API
it'd be awesome if you could take a look at it ( github.com/firasdarwish/ore ), your review and suggestions will be highly valued
I was working in a framework avoiding re-inventing the wheel :P (has been created on top of libs like Gin Gonic, testify and other popular libs) ... it is trying to organize the project files struct, and focused on Hexagonal Architecture. The framework provides an intuitive Dependency Injection module and encourage developers thinking on Entity design and Use Cases, providing boilerplate code generation such like CRUD operations and more.
Please, take a look I think that worths.
Documentation: Torpedo docs
Posts:
Introducing Torpedo: A Golang Framework Born Out of Frustration with Messy Codebases
Creating Your First Project with Torpedo: A Step-by-Step Guide
I see that you include infrastructure code (such as the actual database connection) in the repositories like user/repository.go.
Have you found any downsides to that, specially on testability? Why having it as an interface with the implementation in the same file? I usually define the repos as interfaces, but then the implementation resides in an infra package.
If user and order models need to reference each others, the example you're showing will break due to "circular dependency" issue.