structuring golang projects (uncompleted)

Structuring Golang Projects

Who never ask yourself about what is the best way to create a new project? Should I use the Hexagonal, DDD, Clean and these others fancy architectures? Go has a different style, but when you are a newcomer in the language, probably you don’t had the enough time to consume and read all the good repositories and resources to drive your decisions. This post is a collection of my thoughts and experiences about how to structure Go projects. With name conventions, package organization, and some tips to make your codebase more readable and maintainable.

Dilemmas

prs
  • Should I put everything together?
  • Start small and grow?
  • What is the “Go way”?

What is non-negotiable?

  • Consistency across the codebase
  • Easy to change, loosely coupled
  • Easy to test, that implies decoupled package with clear duties and goals
  • Design reflect how the software works

Grouping

Listing some feasible approaches to organize your golang codebase.

Flat

.
├── cmd
│   └── main.go
└── flat
    ├── disk.go
    ├── http.go
    ├── inmem.go
    ├── lamps.go
    ├── output.txt
    └── processes.go

At least for me, in a first glance, seems a good approach. Everything is together, easy to find, easy to change. But, obviously, when the projects grow, this approach will become a mess.

By Function/Layer

By Context

.
├── Dockerfile
├── Makefile
├── cmd
│   └── appname
│       └── main.go
├── compose.yaml
├── domain1.go
├── domain2.go
├── domain3.go
├── firestore
│   ├── domain1.go
│   └── firestore.go
├── http
│   ├── docs
│   │   └── swagger.yaml
│   ├── domain1.go
│   └── http.go
├── mock
│   └── domain1.go
├── output.txt
├── postgres
│   ├── domain1.go
│   ├── migrations
│   │   ├── migration1-down.sql
│   │   └── migration1-up.sql
│   └── postgres.go
└── pubsub
    ├── domain3.go
    └── pubsub.go

Package organization

This was the best definition of how to organize packages in the golang style without screwing up the codebase. It’s a 2 definition rule that shape the whole codebase.

Domain Types

The domain types are the ones that represent the business logic of the application.

Service

The service packages are the ones that will operate on the domain types.

Names and Conventions

Mock

Important Resources