Go Modules and Project Layout

A Go module is a collection of packages versioned together, defined by a go.mod file at its root.

go.mod

module github.com/acme/shop

go 1.25

require (
    github.com/jackc/pgx/v5 v5.7.1
    golang.org/x/sync v0.10.0
)

Everyday commands

go mod init github.com/acme/shop
go get github.com/jackc/pgx/v5@latest    # add or upgrade a dependency
go mod tidy                               # add missing, remove unused
go list -m -u all                         # see available upgrades
go mod why golang.org/x/text              # why is this here?

go.sum records checksums so builds are reproducible and tamper-evident. Commit both files.

A common layout

shop/
  go.mod
  cmd/
    api/main.go          # one folder per binary
    worker/main.go
  internal/              # importable only from inside this module
    orders/
      orders.go
      orders_test.go
      postgres.go
    platform/
      config/
      database/
  migrations/

• cmd/<name> holds small main packages that wire things together.
• internal/ is enforced by the compiler: other modules can't import it.
• Organise packages by domain (orders, users), not by layer (models, controllers).

Start simple

A small service can live in a single main package. Add packages when a part of the code has a clear, separate responsibility, not before.

Tool dependencies

go get -tool golang.org/x/tools/cmd/stringer   # Go 1.24+: tracked in go.mod
go tool stringer -type=Status