Clean Architecture in Go should be implemented by organizing code around features, not layers, with domain logic protected and external concerns isolated; 1. Structure the project by feature-based packages like /internal/user/ containing entity, usecase, delivery, and repository sub-packages; 2. Define core entities and interfaces in inner layers, such as UserRepository interface depending on User entity; 3. Implement use cases that orchestrate business logic using interfaces without knowing concrete implementations; 4. Implement infrastructure components like PostgresUserRepository in /pkg/database/ that satisfy the interfaces; 5. Keep delivery mechanisms like HTTP handlers thin by only parsing input, calling use cases, and formatting output; 6. Perform manual dependency injection in main.go to wire dependencies explicitly without frameworks; avoid common pitfalls like over-naming layers globally, leaking database models into entities, or forcing unnecessary layers, ensuring code remains maintainable, testable, and independent of external concerns.

Implementing Clean Architecture in Go isn't about slapping on layers or creating folders just for the sake of structure — it's about writing code that's maintainable, testable, and independent of frameworks, databases, or external concerns. Go, with its simplicity and strong support for interfaces, is actually a great fit for Clean Architecture.

Here’s how to do it right, without over-engineering.

What Is Clean Architecture (in Practice)?

At its core, Clean Architecture separates your code into layers based on abstractions, not frameworks. The main idea is the Dependency Rule: inner layers should not know about outer layers.

A typical structure looks like this:

• Domain (Entities) – your business logic and core models
• Use Cases (Application Business Rules) – orchestrate data flow, implement app-specific rules
• Interfaces (Delivery) – HTTP handlers, CLI, gRPC, etc.
• Infrastructure (External) – databases, external APIs, config, logging

The flow of control and data goes inward — from the outside in — but dependencies point inward.

1. Structure Your Project by Package (Not Layer)

Avoid domain/, usecase/, infrastructure/ as top-level folders. Instead, organize by feature or context, and keep architectural layers within each.

Example:

/cmd/
  api/
    main.go
/internal/
  user/
    delivery/
      http.go
    usecase/
      user_usecase.go
    entity/
      user.go
    repository/
      user_repository.go
  order/
    ...
/pkg/
  database/
  middleware/

This way, each feature (user, order) is self-contained, and you can grow without a giant monolithic layer.

2. Define Entities and Interfaces in the Inner Layers

Your entities and interfaces should live in the inner layers. Infrastructure (like PostgreSQL) implements those interfaces.

// /internal/user/entity/user.go
type User struct {
  ID    int
  Name  string
  Email string
}

// /internal/user/repository/user_repository.go
type UserRepository interface {
  GetByID(id int) (*User, error)
  Create(user *User) error
}

Now, the use case depends on the interface — not the database.

3. Write Use Cases That Orchestrate Logic

Use cases are where your application-specific logic lives. They depend on entities and interfaces.

// /internal/user/usecase/user_usecase.go
type UserUsecase struct {
  repo user.UserRepository
}

func (u *UserUsecase) GetUser(id int) (*user.User, error) {
  return u.repo.GetByID(id)
}

This keeps business rules separate from delivery mechanisms.

4. Implement Interfaces in Infrastructure

Now, implement the UserRepository in the PostgreSQL package.

// /pkg/database/postgres/user_repo.go
type PostgresUserRepository struct {
  db *sql.DB
}

func (r *PostgresUserRepository) GetByID(id int) (*User, error) {
  // actual DB call
}

Then inject it into the use case at startup (in main.go):

// cmd/api/main.go
db := connectDB()
repo := &postgres.PostgresUserRepository{db}
usecase := &user.UserUsecase{repo}
httpHandler := &user.HTTPHandler{Usecase: usecase}

5. Keep Delivery Thin

HTTP handlers should only:

• Parse input
• Call use case
• Format output

// /internal/user/delivery/http.go
func (h *HTTPHandler) GetUser(w http.ResponseWriter, r *http.Request) {
  id, _ := strconv.Atoi(r.URL.Query().Get("id"))
  user, err := h.Usecase.GetUser(id)
  // handle err, encode JSON
}

No business logic here. Just glue.

6. Dependency Injection Is Manual (and That’s OK)

Go doesn’t need a DI framework. Wire things up in main.go. It’s explicit and clear.

// cmd/api/main.go
func main() {
  db, _ := sql.Open("postgres", dsn)
  repo := &postgres.UserRepo{db}
  usecase := &user.UserUsecase{repo}
  handler := &user.HTTPHandler{usecase}

  http.HandleFunc("/user", handler.GetUser)
  http.ListenAndServe(":8080", nil)
}

You control the graph. No magic.

Common Pitfalls to Avoid

• Forcing every layer everywhere: Not every feature needs all layers. Keep it pragmatic.
• Leaking database models into entities: Don’t expose gorm.Model or SQL tags in your core.
• Naming packages after layers globally: It leads to “anemic” services and scattered logic.
• Using generics or complex patterns prematurely: Clean Architecture is about separation, not complexity.

Final Thoughts

Clean Architecture in Go works best when it’s simple and practical. Focus on:

• Protecting your business logic
• Depending on abstractions
• Keeping external concerns (DB, HTTP) at the edges
• Organizing by feature, not just layer

It’s not about rigid rules — it’s about making your code easier to change, test, and understand.

Basically: write small packages, use interfaces, and wire things cleanly in main. That’s 90% of it.

The above is the detailed content of Implementing Clean Architecture in Go. For more information, please follow other related articles on the PHP Chinese website!