Follow standard Go project layout using directories like cmd, internal, pkg, and api to separate concerns and ensure scalability. 2. Organize code by domain (e.g., user, order) for larger applications to reduce coupling, or by layer (handler, service, repository) for simpler apps. 3. Use Go modules with semantic import paths by initializing with go mod init and importing packages via full module paths to ensure clean, consistent dependencies. 4. Keep main.go minimal by limiting it to configuration loading, dependency injection, and application startup. 5. Separate business logic from side effects by placing testable functions in service layers rather than handlers or main. 6. Include supporting files like Makefile, .gitignore, README.md, and Dockerfile to improve developer experience and maintainability. Following these practices ensures a maintainable, testable, and scalable Go project structure.

Structuring a Go project well is key to maintainability, testability, and scalability—especially as your project grows. While Go doesn’t enforce a strict layout, there are widely accepted conventions and best practices that help teams collaborate effectively. Here’s how to structure a Go project in a practical and scalable way.

1. Follow Standard Go Layout (with cmd, internal, pkg, etc.)

A common and scalable structure for Go projects looks like this:

my-project/
├── cmd/
│   └── myapp/
│       └── main.go
├── internal/
│   ├── app/
│   └── pkg/
├── pkg/
│   └── public/
├── pkg/
│   └── logging/
├── api/
│   └── v1/
├── config/
├── internal/
│   └── database/
├── pkg/
│   └── auth/
├── go.mod
├── go.sum
├── Makefile
└── README.md

Let’s break down the key directories:

• cmd/myapp/main.go
  Entry point for your application. Each binary goes in its own subdirectory under cmd. Keep main.go minimal—just setup and startup logic.

• internal/
  Private code that should not be imported by other projects. Go enforces this: packages under internal can only be imported by parent packages. Use this for app-specific business logic.

  

• pkg/
  Reusable public packages that other projects can import. These should be well-designed, tested, and documented. Think of them as libraries.

• api/
  API definitions (e.g., OpenAPI/Swagger specs, protobuf files, or REST route docs). Versioned subdirectories like v1/, v2/ help manage breaking changes.

• config/
  Configuration files, defaults, and schema (e.g., YAML, JSON, or code-based config structs).

• go.mod and go.sum
  Required for Go modules. Define your module path and dependencies here.

2. Organize by Domain or Layer (Avoid "God" Packages)

Don’t dump everything into a single src/ or controllers/ folder. Instead, organize by:

• Domain (Recommended for larger apps)
  Group code by business domain:

  internal/
  ├── user/
  │   ├── user.go
  │   ├── user_service.go
  │   └── user_repository.go
  ├── order/
  │   ├── order.go
  │   └── order_service.go

• Layer (Classic MVC-style, fine for smaller apps)
  Group by technical role:

  internal/
  ├── handler/
  ├── service/
  └── repository/

For most real-world services, a domain-driven approach scales better and reduces coupling.

3. Use Go Modules and Semantic Import Paths

Always initialize your project with:

go mod init github.com/yourname/my-project

This sets the module path, which should match your repository URL. It enables clean imports like:

import "github.com/yourname/my-project/internal/user"

Avoid relative imports. Use full module paths consistently.

4. Keep main.go Thin

Your main.go should do three things:

1. Load configuration
2. Wire up dependencies (database, services, etc.)
3. Start the server (or run the command)

Example:

// cmd/myapp/main.go
package main

import (
    "log"
    "my-project/internal/app"
    "my-project/internal/config"
)

func main() {
    cfg := config.Load()
    app := app.New(cfg)
    if err := app.Start(); err != nil {
        log.Fatal(err)
    }
}

This keeps the entry point clean and testable.

5. Separate Testable Logic from Side Effects

Put business logic in testable functions, not buried in HTTP handlers or main. For example:

// internal/user/service.go
func (s *UserService) CreateUser(email string) (*User, error) { ... }

Then in a handler:

func (h *UserHandler) Create(w http.ResponseWriter, r *http.Request) {
    user, err := h.service.CreateUser(email)
    // handle err, write response
}

This makes unit testing straightforward.

6. Add Common Supporting Files

Include these for better developer experience:

• Makefile – for common tasks:

  build:
      go build -o bin/app cmd/myapp/main.go
  
  test:
      go test -v ./...
  
  run:
      go run cmd/myapp/main.go

• .gitignore – ignore bin/, tmp/, IDE files

• README.md – how to build, run, and test

• Dockerfile – if containerizing

---

Final Tips

• ? Use go mod tidy regularly to clean up dependencies.
• ? Write tests in _test.go files alongside the code.
• ? Avoid circular imports by designing clean boundaries.
• ? Use gofmt or goimports to keep code style consistent.

---

There’s no one-size-fits-all, but this structure works well for APIs, CLIs, and microservices. Start simple, then evolve as needed.

Basically: thin main, domain structure, internal vs pkg, and proper modules. That’ll get you 90% of the way.

The above is the detailed content of How do you structure a Go project?. For more information, please follow other related articles on the PHP Chinese website!