Mastering Go Project Structure: Best Practices for Packages and Naming

Overview

Go, first released in 2009, is widely adopted because of its minimal syntax, rich standard library, and built‑in concurrency primitives. Organizing source files into a clear package structure is essential for maintainability, testability, and team collaboration.

Package Splitting Principles

Group by functionality : Place code that serves the same domain in a single package. For example, an http package contains request handlers, client utilities and middleware, while a json package provides encoding/decoding helpers.

Avoid circular imports : The Go compiler rejects import cycles. If two packages need each other’s types, extract the shared definitions into a third package or redesign the responsibilities.

Use sub‑packages when a package grows large : A large package such as net/http can expose a core http package and a dedicated http/httptest sub‑package for testing utilities.

Naming Conventions

Keep names short, singular and descriptive . Prefer store over stores , avoid underscores or mixed case.

Do not use generic names like common , util or helpers unless the package truly contains a cohesive set of utilities.

Directory‑package alignment : The package name must match the directory name. If the package is declared as json , the source files should reside in /path/to/json .

Common Top‑Level Directories

cmd : One sub‑directory per executable, e.g. cmd/server/main.go .

pkg : Reusable libraries intended for external consumption; code here should have stable APIs.

internal : Private packages that can only be imported by code within the same module, enforcing encapsulation.

api : OpenAPI/Swagger specifications, .proto files for gRPC, or other contract definitions.

web or server : HTTP handlers, router configuration, middleware chains.

client : Client libraries for external services (REST, database drivers, etc.).

config : Configuration parsing, environment variable handling, and related helpers.

service or app : Core business logic, orchestrating use‑cases.

model or domain : Struct definitions and domain‑specific methods.

store or repository : Persistence layer, database access, transaction management.

util or helper : Small, self‑contained utilities; split further when they grow beyond a single concern.

Package Hierarchy Strategies

Domain‑Driven Design (DDD) : Create a top‑level package per business domain, e.g. order , customer , inventory . Each domain package can contain sub‑packages such as order/service or order/repository .

Layered architecture : Separate technical layers into distinct packages— model for data structures, service for business rules, and handler (or controller ) for HTTP entry points.

Internal packages : Place implementation details that must not be exported in an internal directory. The Go toolchain enforces that only code within the parent module can import these packages.

Practical Tips

Start with a minimal layout (e.g., cmd , internal , pkg ) and evolve as the codebase grows.

When a package becomes too large, extract a sub‑package or move shared types to a new package to keep import graphs shallow.

Run go vet ./... and go test ./... regularly to ensure that refactoring the package structure does not introduce import cycles or broken APIs.

Summary

Applying functional package splitting, consistent naming, conventional top‑level directories, and a clear hierarchy (DDD or layered) enables Go projects to remain readable, testable, and scalable while supporting collaborative development.