Why Start with a Project Structure?

When beginning a new Go project, establishing a clear directory structure is a foundational step. For newcomers, every aspect of development can be a new challenge:

• Where should global configurations reside?
• How is the database connection initialized?
• How should data models be designed?
• How are routes organized?

These questions can be overwhelming. Frameworks like Java's Spring Boot or PHP's Laravel provide a default structure, guiding developers on where to place different components. Go, however, offers more freedom, which is beneficial for experienced developers but can lead beginners to make common mistakes.

My experience has shown that:

A well-defined structure leads to cllearer thinking and a more comfortable development experience.

By planning the structure upfront, you can break down the problem into manageable parts, avoiding the chaos of a monolithic codebase from the start.

A Common Go Project Structure (Gin Example)

Here is a directory structure I frequently use, suitable for most small to medium-sized web applications:

.
├── cmd/              # Application entry points
│   └── main.go       # Main program entry
├── internal/         # Private application code
│   ├── dto/          # Data transfer object definitions
│   ├── handler/      # HTTP handlers (equivalent to Controllers)
│   ├── model/        # Data models
│   ├── repository/   # Data access layer
│   ├── router/       # Routing definitions
│   └── service/      # Business logic layer
├── pkg/              # Reusable packages for external use
│   ├── config/       # Configuration management
│   ├── i18n/         # Internationalization
│   ├── jwt/          # JSON Web Token handling
│   ├── middleware/   # Middleware components
│   └── utils/        # Utility functions
├── api/              # API documentation (Swagger)
│   └── swagger.json
├── scripts/          # Build and deployment scripts
├── go.mod
├── LICENSE
├── Makefile          # Automation script definitions
└── README.md

cmd/: Application Entry Points

The cmd directory contains the main entry points for the application. Typically, a project has a single entry point:

cmd/
└── main.go

If the project evolves into multiple services (e.g., an API server and a background worker), the structure can be expanded:

cmd/
├── api/
│   └── main.go
├── worker/
│   └── main.go

This appproach facilitates better management of multi-service architectures.

internal/: Private Application Code

The internal directory leverages Go's built-in private code mechanism. Packages within this directory are only accessible to the current project and cannot be imported by external projects. This directory is organized into distinct layers with clear responsibilities:

internal/
├── dto/          # Request/response structures
├── handler/      # HTTP layer
├── service/      # Business logic
├── repository/   # Data access
├── model/        # Database entities
└── router/       # Route registration

The typical call flow is unidirectional:

Handler → Service → Repository → Model

Here's a brief overview of each layer's responsibility:

• Handler: Receives and parses incoming requests, validates parameters, and invokes the corresponding Service.
• Service: Contains the core business logic.
• Repository: Handles database operations (pure CRUD, no business logic).
• Model: Defines the data structures mapped to database tables.
• DTO (Data Transfer Object):strong> Defines structures for request and response payloads, separating them from the internal Model.
• Router: Registers application routes and binds them to handlers.

This layered architecture is well-suited for Go and is more maintainable than approaches where a single component handles everything, as sometimes seen in other frameworks. A key feature of Go is that:

Multiple .go files within the same package are treated as a single unit by the compiler.

This allows you to split code into multiple files (e.g., user.go, order.go) for better readability without any impact on compilation, as they are part of the same logical package.

For developers transitioning from object-oriented languages, Go requires a fundamental shift in thinking:

1. Forget "Classes": Embrace "Structs + Methods".
2. Forget "Inheritance": Use "Composition + Interfaces".
3. Forget "Design Pattterns": Focus on solving the actual problem.
4. Embrace Explicit Error Handling: There is no try-catch mechanism.

pkg/: Reusable Public Packages

The pkg directory is for general-purpose packages that can be imported by other projects. Examples include:

pkg/
├── config/
├── i18n/
├── jwt/
├── middleware/
└── utils/

If a package is intended only for the current project, it should be placed in the internal directory. It's also advisable to avoid creating a monolithic utils package; instead, split functionality into smaller, focused packages for easier maintenance.

api/: API Documentation

This directory typically contains definitions for API documentation tools like Swagger or OpenAPI (in JSON or YAML format). Using such tools helps:

• Automatically generate documentation.
• Keep frontend and backend teams in sync.

This is invaluable for collaboration in team environments.

Makefile: A Shortcut for Common Commands

I recommend using a Makefile to define common commands, such as:

run:
    go run cmd/main.go

build:
    go build -o bin/app cmd/main.go

test:
    go test ./...

A Makefile is an excellent tool. You can list all project-related commands, and for better onboarding, you can even create a help target:

help:
	@echo "Available commands:"
	@echo "  make deps          # Install/update Go dependencies"
	@echo "  make fmt           # Format backend Go code"
	@echo "  make test          # Run all Go unit tests"

This is very helpful for new team members, allowing them to quickly understand the project's workflow by reading the Makefile.