The Folder Structure for Every Golang Project

folder_structure.md

Go - The Ultimate Folder Structure

Organizing your Go (Golang) project's folder structure can help improve code readability, maintainability, and scalability. While there is no one-size-fits-all structure, here's a common folder structure for a Go project:

project-root/
    ├── cmd/
    │   ├── your-app-name/
    │   │   ├── main.go         # Application entry point
    │   │   └── ...             # Other application-specific files
    │   └── another-app/
    │       ├── main.go         # Another application entry point
    │       └── ...
    ├── internal/                # Private application and package code
    │   ├── config/
    │   │   ├── config.go       # Configuration logic
    │   │   └── ...
    │   ├── database/
    │   │   ├── database.go     # Database setup and access
    │   │   └── ...
    │   └── ...
    ├── pkg/                     # Public, reusable packages
    │   ├── mypackage/
    │   │   ├── mypackage.go    # Public package code
    │   │   └── ...
    │   └── ...
    ├── api/                     # API-related code (e.g., REST or gRPC)
    │   ├── handler/
    │   │   ├── handler.go      # HTTP request handlers
    │   │   └── ...
    │   ├── middleware/
    │   │   ├── middleware.go  # Middleware for HTTP requests
    │   │   └── ...
    │   └── ...
    ├── web/                     # Front-end web application assets
    │   ├── static/
    │   │   ├── css/
    │   │   ├── js/
    │   │   └── ...
    │   └── templates/
    │       ├── index.html
    │       └── ...
    ├── scripts/                 # Build, deployment, and maintenance scripts
    │   ├── build.sh
    │   ├── deploy.sh
    │   └── ...
    ├── configs/                 # Configuration files for different environments
    │   ├── development.yaml
    │   ├── production.yaml
    │   └── ...
    ├── tests/                   # Unit and integration tests
    │   ├── unit/
    │   │   ├── ...
    │   └── integration/
    │       ├── ...
    ├── docs/                    # Project documentation
    ├── .gitignore               # Gitignore file
    ├── go.mod                   # Go module file
    ├── go.sum                   # Go module dependencies file
    └── README.md                # Project README

Here's a brief explanation of the key directories:

• cmd/: This directory contains application-specific entry points (usually one per application or service). It's where you start your application.

• internal/: This directory holds private application and package code. Code in this directory is not meant to be used by other projects. It's a way to enforce access control within your project.

• pkg/: This directory contains public, reusable packages that can be used by other projects. Code in this directory is meant to be imported by external projects.

• api/: This directory typically holds HTTP or RPC API-related code, including request handlers and middleware.

• web/: If your project includes a front-end web application, this is where you'd put your assets (CSS, JavaScript, templates, etc.).

• scripts/: Contains scripts for building, deploying, or maintaining the project.

• configs/: Configuration files for different environments (e.g., development, production) reside here.

• tests/: Holds unit and integration tests for your code.

• docs/: Project documentation, such as design documents or API documentation.

This is a general guideline, and you can adjust it to match the specific needs of your project. Additionally, you can consider using a project layout tool like "golang-standards/project-layout" as a reference to structure your Go project.

Other Possible

The folder structure for a Go project can vary depending on the size and complexity of the project, as well as personal or team preferences. Here are some alternative folder structures for Go projects:

1. Flat Structure: In smaller projects, you might opt for a flat structure where all your Go source files reside in the project root directory. This approach is simple but may become hard to manage as the project grows.

   project-root/
       ├── main.go
       ├── handler.go
       ├── config.go
       ├── database.go
       ├── ...
       ├── static/
       ├── templates/
       ├── scripts/
       ├── configs/
       ├── tests/
       └── docs/

2. Layered Structure: Organize your code into layers, such as "web," "api," and "data." This approach helps separate concerns.

   project-root/
       ├── main.go
       ├── web/
       │   ├── handler.go
       │   ├── static/
       │   ├── templates/
       ├── api/
       │   ├── routes.go
       │   ├── middleware/
       ├── data/
       │   ├── database.go
       │   ├── repository.go
       ├── configs/
       ├── tests/
       ├── docs/

3. Domain-Driven Design (DDD): In larger applications, consider structuring your project based on domain-driven design principles. Each domain has its own directory.

   project-root/
       ├── cmd/
       │   ├── app1/
       │   ├── app2/
       ├── internal/
       │   ├── auth/
       │   │   ├── handler.go
       │   │   ├── service.go
       │   ├── orders/
       │   │   ├── handler.go
       │   │   ├── service.go
       │   ├── ...
       ├── pkg/
       │   ├── utility/
       │   │   ├── ...
       │   ├── ...
       ├── api/
       │   ├── app1/
       │   │   ├── ...
       │   ├── app2/
       │   │   ├── ...
       ├── web/
       │   ├── app1/
       │   │   ├── ...
       │   ├── app2/
       │   │   ├── ...
       ├── scripts/
       ├── configs/
       ├── tests/
       └── docs/

4. Clean Architecture: You can adopt a clean architecture approach, which emphasizes a separation of concerns between different layers of your application.

   project-root/
       ├── cmd/
       │   ├── your-app/
       │   │   ├── main.go
       ├── internal/
       │   ├── app/
       │   │   ├── handler.go
       │   │   ├── service.go
       │   ├── domain/
       │   │   ├── model.go
       │   │   ├── repository.go
       ├── pkg/
       │   ├── utility/
       │   │   ├── ...
       ├── api/
       │   ├── ...
       ├── web/
       │   ├── ...
       ├── scripts/
       ├── configs/
       ├── tests/
       └── docs/

5. Modular Structure: Organize your code into separate modules, each with its own directory structure. This approach can be useful when developing multiple independent components within a single project.

   project-root/
       ├── module1/
       │   ├── cmd/
       │   ├── internal/
       │   ├── pkg/
       │   ├── api/
       │   ├── web/
       │   ├── scripts/
       │   ├── configs/
       │   ├── tests/
       │   └── docs/
       ├── module2/
       │   ├── ...

Remember that the right folder structure depends on the specific needs of your project and your team's development practices. Choose a structure that helps maintain code organization, readability, and collaboration as your project evolves.