This is the fourth article in the "Clean Code in Go" series.
Previous Parts:
- Clean Code: Functions and Error Handling in Go: From Chaos to Clarity [Part 1]
- Clean Code in Go (Part 2): Structs, Methods, and Composition Over Inheritance
- Clean Code: Interfaces in Go - Why Small Is Beautiful [Part 3]
Why Import Cycles Hurt
I've spent countless hours helping teams untangle circular dependencies in their Go projects. "Can't load package: import cycle not allowed" — if you've seen this error, you know how painful it is to refactor tangled dependencies. Go is merciless: no circular imports, period. And this isn't a bug, it's a feature that forces you to think about architecture.
Common package organization mistakes I've seen:
- Circular dependencies attempted: ~35% of large Go projects
- Everything in one package: ~25% of small projects
- Utils/helpers/common packages: ~60% of codebases
- Wrong interface placement: ~70% of packages
- Over-engineering with micropackages: ~30% of projects
After 6 years working with Go and reviewing architecture in projects from startups to enterprise, I've seen projects with perfect package structure and projects where everything imports everything (spoiler: the latter don't live long). Today we'll explore how to organize packages so your project scales without pain and new developers understand the structure at first glance.
Anatomy of a Good Package
Package Name = Purpose
// BAD: generic names say nothing
package utils
package helpers
package common
package shared
package lib
// GOOD: name describes purpose
package auth // authentication and authorization
package storage // storage operations
package validator // data validation
package mailer // email sending
Project Structure: Flat vs Nested
BAD: Java-style deep nesting
/src
/main
/java
/com
/company
/project
/controllers
/services
/repositories
/models
# GOOD: Go flat structure
/cmd
/api # API server entry point
/worker # worker entry point
/internal # private code
/auth # authentication
/storage # storage layer
/transport # HTTP/gRPC handlers
/pkg # public packages
/logger # reusable
/crypto # crypto utilities
Internal: Private Project Packages
Go 1.4+ has a special `internal` directory whose code is accessible only to the parent package:
// Structure:
// myproject/
// cmd/api/main.go
// internal/
// auth/auth.go
// storage/storage.go
// pkg/
// client/client.go
// cmd/api/main.go - CAN import internal
import "myproject/internal/auth"
// pkg/client/client.go - CANNOT import internal
import "myproject/internal/auth" // compilation error!
// Another project - CANNOT import internal
import "github.com/you/myproject/internal/auth" // compilation error!
Rule: internal for Business Logic
// internal/user/service.go - business logic is hidden
package user
type Service struct {
repo Repository
mail Mailer
}
func NewService(repo Repository, mail Mailer) *Service {
return &Service{repo: repo, mail: mail}
}
func (s *Service) Register(email, password string) (*User, error) {
// validation
if err := validateEmail(email); err != nil {
return nil, fmt.Errorf("invalid email: %w", err)
}
// check existence
if exists, _ := s.repo.EmailExists(email); exists {
return nil, ErrEmailTaken
}
// create user
user := &User{
Email: email,
Password: hashPassword(password),
}
if err := s.repo.Save(user); err != nil {
return nil, fmt.Errorf("save user: %w", err)
}
// send welcome email
s.mail.SendWelcome(user.Email)
return user, nil
}
Dependency Inversion: Interfaces on Consumer Side
Rule: Define Interfaces Where You Use Them
// BAD: interface in implementation package
// storage/interface.go
package storage
type Storage interface {
Save(key string, data []byte) error
Load(key string) ([]byte, error)
}
// storage/redis.go
type RedisStorage struct {
client *redis.Client
}
func (r *RedisStorage) Save(key string, data []byte) error { /*...*/ }
func (r *RedisStorage) Load(key string) ([]byte, error) { /*...*/ }
// PROBLEM: service depends on storage
// service/user.go
package service
import "myapp/storage" // dependency on concrete package!
type UserService struct {
store storage.Storage
}
// GOOD: interface in usage package
// service/user.go
package service
// Interface defined where it's used
type Storage interface {
Save(key string, data []byte) error
Load(key string) ([]byte, error)
}
type UserService struct {
store Storage // using local interface
}
// storage/redis.go
package storage
// RedisStorage automatically satisfies service.Storage
type RedisStorage struct {
client *redis.Client
}
func (r *RedisStorage) Save(key string, data []byte) error { /*...*/ }
func (r *RedisStorage) Load(key string) ([]byte, error) { /*...*/ }
// main.go
package main
import (
"myapp/service"
"myapp/storage"
)
func main() {
store := storage.NewRedisStorage()
svc := service.NewUserService(store) // storage satisfies service.Storage
}
Import Graph: Wide and Flat
Problem: Spaghetti Dependencies
// BAD: everyone imports everyone
// models imports utils
// utils imports config
// config imports models // CYCLE!
// controllers imports services, models, utils
// services imports repositories, models, utils
// repositories imports models, database, utils
// utils imports... everything
Solution: Unidirectional Dependencies
// Application layers (top to bottom)
// main
// ↓
// transport (HTTP/gRPC handlers)
// ↓
// service (business logic)
// ↓
// repository (data access)
// ↓
// models (data structures)
// models/user.go - zero dependencies
package models
type User struct {
ID string
Email string
Password string
}
// repository/user.go - depends only on models
package repository
import "myapp/models"
type UserRepository interface {
Find(id string) (*models.User, error)
Save(user *models.User) error
}
// service/user.go - depends on models and defines interfaces
package service
import "myapp/models"
type Repository interface {
Find(id string) (*models.User, error)
Save(user *models.User) error
}
type Service struct {
repo Repository
}
// transport/http.go - depends on service and models
package transport
import (
"myapp/models"
"myapp/service"
)
type Handler struct {
svc *service.Service
}
Organization: By Feature vs By Layer
By Layers (Traditional MVC)
project/
/controllers
user_controller.go
post_controller.go
comment_controller.go
/services
user_service.go
post_service.go
comment_service.go
/repositories
user_repository.go
post_repository.go
comment_repository.go
/models
user.go
post.go
comment.go
# Problem: changing User requires edits in 4 places
By Features (Domain-Driven)
project/
/user
handler.go # HTTP handlers
service.go # business logic
repository.go # database operations
user.go # model
/post
handler.go
service.go
repository.go
post.go
/comment
handler.go
service.go
repository.go
comment.go
# Advantage: all User logic in one place
Hybrid Approach
project/
/cmd
/api
main.go
/internal
/user # user feature
service.go
repository.go
/post # post feature
service.go
repository.go
/auth # auth feature
jwt.go
middleware.go
/transport # shared transport layer
/http
server.go
router.go
/grpc
server.go
/storage # shared storage layer
postgres.go
redis.go
/pkg
/logger
/validator
Dependency Management: go.mod
Minimal Version Selection (MVS)
// go.mod
module github.com/yourname/project
go 1.21
require (
github.com/gorilla/mux v1.8.0
github.com/lib/pq v1.10.0
github.com/redis/go-redis/v9 v9.0.0
)
// Use specific versions, not latest
// BAD:
// go get github.com/some/package@latest
// GOOD:
// go get github.com/some/[email protected]
Replace for Local Development
// go.mod for local development
replace github.com/yourname/shared => ../shared
// For different environments
replace github.com/company/internal-lib => (
github.com/company/internal-lib v1.0.0 // production
../internal-lib // development
)
Code Organization Patterns
Pattern: Options in Separate File
package/
server.go # main logic
options.go # configuration options
middleware.go # middleware
errors.go # custom errors
doc.go # package documentation
// options.go
package server
type Option func(*Server)
func WithPort(port int) Option {
return func(s *Server) {
s.port = port
}
}
func WithTimeout(timeout time.Duration) Option {
return func(s *Server) {
s.timeout = timeout
}
}
// errors.go
package server
import "errors"
var (
ErrServerStopped = errors.New("server stopped")
ErrInvalidPort = errors.New("invalid port")
)
// doc.go
// Package server provides HTTP server implementation.
//
// Usage:
// srv := server.New(
// server.WithPort(8080),
// server.WithTimeout(30*time.Second),
// )
package server
Pattern: Facade for Complex Packages
// crypto/facade.go - simple API for complex package
package crypto
// Simple functions for 90% of use cases
func Encrypt(data, password []byte) ([]byte, error) {
return defaultCipher.Encrypt(data, password)
}
func Decrypt(data, password []byte) ([]byte, error) {
return defaultCipher.Decrypt(data, password)
}
// For advanced cases - full access
type Cipher struct {
algorithm Algorithm
mode Mode
padding Padding
}
func NewCipher(opts ...Option) *Cipher {
// configuration
}
Testing and Packages
Test Packages for Black Box Testing
// user.go
package user
type User struct {
Name string
age int // private field
}
// user_test.go - white box (access to private fields)
package user
func TestUserAge(t *testing.T) {
u := User{age: 25} // access to private field
// testing
}
// user_blackbox_test.go - black box
package user_test // separate package!
import (
"testing"
"myapp/user"
)
func TestUser(t *testing.T) {
u := user.New("John") // only public API
// testing
}
Anti-patterns and How to Avoid Them
Anti-pattern: Models Package for Everything
// BAD: all models in one package
package models
type User struct {}
type Post struct {}
type Comment struct {}
type Order struct {}
type Payment struct {}
// 100500 structs...
// BETTER: group by domain
package user
type User struct {}
package billing
type Order struct {}
type Payment struct {}
Anti-pattern: Leaking Implementation Details
// BAD: package exposes technology
package mysql
type MySQLUserRepository struct {}
// BETTER: hide details
package storage
type UserRepository struct {
db *sql.DB // details hidden inside
}
Practical Tips
1. Start with a monolith— don't split into micropackages immediately
2.internal for all private code— protection from external dependencies
3.Define interfaces at consumer— not at implementation
4.Group by features, not by file types
5. **One package = one responsibility \ 6.Avoid circular dependenciesthrough interfaces
7.Document packages in doc.go
Package Organization Checklist
- Package has clear, specific name
- No circular imports
- Private code in internal
- Interfaces defined at usage site
- Import graph flows top to bottom
- Package solves one problem
- Has doc.go with examples
- Tests in separate test package
Conclusion
Proper package organization is the foundation of a scalable Go project. Flat import graph, clear responsibility boundaries, and Dependency Inversion through interfaces allow project growth without the pain of circular dependencies.
In the final article of the series, we'll discuss concurrency and context — unique Go features that make the language perfect for modern distributed systems.
What's your approach to package organization? Do you prefer organizing by feature or by layer? How do you handle the temptation to create a "utils" package? Let me know in the comments!