DOCSEARCHbyAlgolia
Submit Docs

Go Project Layout

repository·master·Indexed 13 days ago

https://github.com/golang-standards/project-layout

A community-driven guide for organizing Go projects using common architectural patterns. It provides a recommended directory structure—including /cmd, /internal, /pkg, /api, and /deployments—to help manage complexity and maintain a clean separation of concerns as projects grow.

Tokens
15.1K
Snippets
14
Records
107
Agent score
78%

What's inside Go Project Layout

  1. Overview of the Standard Go Project Layout

    master

    This project provides a common layout pattern for Go projects. It is not an official standard defined by the Go development team, but rather a collection of patterns and best practices that have emerged from the Go ecosystem.

    When to use this layout

    • Avoid for small projects: If you are learning Go, building a Proof of Concept (PoC), or a simple experiment, do not use this complex structure. A single main.go and a go.mod file are sufficient.
    • Use for growing projects: As your project grows, this layout helps manage dependencies, prevent global variable sprawl, and organize code for multiple contributors.
    • Use for open source: When others will consume your code, using specific directories like internal helps protect private logic.

    Key Recommendations

    • Use Go Modules: Always use Go Modules (go.mod) for dependency management. Ensure your module path contains a dot (e.g., github.com/user/repo) to maintain compatibility with older Go versions.
    • Be Intentional: Do not feel obligated to use every directory listed in this layout. Clone this repository, take what you need, and delete the rest.

  2. Overview of the Go Project Layout standard

    master

    The Go Project Layout is a community-driven template for organizing Go projects. While not an official standard defined by the Go core team, it follows historically established patterns in the Go ecosystem and provides improvements for large-scale applications.

    When to use this layout

    • Small/Learning projects: Avoid this layout. A single main.go file is sufficient for learning or small personal tools.
    • Growing projects: Use this layout when your project requires structure to manage dependencies and avoid global state.
    • Open source/Shared libraries: Use this layout to clearly define public vs. internal (internal) packages so consumers understand what is safe to use.

    Key Principles

    • Use Go Modules: Always use Go Modules. This removes the need to worry about $GOPATH or specific project locations.
    • Modular approach: Do not feel obligated to use every directory provided in this template. Clone the repository and only use what is necessary for your specific use case.
    • Package-oriented design: Focus on creating clear boundaries between packages to manage complexity.

  3. Understand the Go Project Layout standard

    master

    This project provides a community-driven layout pattern for Go applications. It is not an official standard from the Go core team, but a collection of patterns used in the Go ecosystem to manage large-scale projects.

    When to use this layout

    • Avoid for small projects: If you are learning Go, building a PoC, or a simple personal project, this layout is overkill. A simple main.go and go.mod are sufficient.
    • Use for growing projects: As your project grows, a structured layout helps prevent messy source code, hidden dependencies, and global state issues. It is especially useful when multiple people are working on a project or when you are building an open-source library.

    Key Recommendations

    • Use Go Modules: Use go.mod for dependency management. Avoid relying on $GOPATH.
    • Module Naming: While not strictly required in recent Go versions, it is a best practice for the module path to contain a dot (e.g., github.com/user/repo).

  4. Understand the Standard Go Project Layout

    master

    The Standard Go Project Layout is a set of common directory patterns used within the Go ecosystem.

    Important Caveats:

    • Not Official: This is NOT an official standard defined by the core Go development team.
    • Not for Beginners: If you are learning Go or building a simple Proof of Concept (PoC), this layout is likely overkill. Start with a single main.go file and only introduce structure as the project grows to avoid unnecessary complexity.
    • Use as a Guide, Not a Mandate: You do not need to use every directory listed in this repository. Only use the patterns that make sense for your specific project.
    • Go Modules: Always use Go Modules for dependency management. When using modules, you do not need to worry about $GOPATH or specific project locations. Ensure your go.mod file is present at the root.

  5. Understand the Go Project Layout philosophy

    master

    This project provides a collection of common and emerging layout patterns used in the Go ecosystem. It is not an official standard defined by the Go core team, but rather a set of community-driven best practices.

    Key Principles:

    • Not a monolith: You do not need to use every directory listed. Use only what your project requires.
    • Scalability: For simple PoCs or small projects, a single main.go and go.mod is sufficient. This layout is intended for larger projects where managing dependencies, public/private code, and team collaboration becomes critical.
    • Avoid Over-engineering: Do not apply this complex structure to simple projects where it isn't needed.
    • Public vs. Private: Use specific directories (like internal) when you want to prevent other projects from importing your code.
    • Go Modules: Always use Go Modules. The go.mod file is the foundation of your project structure.

  6. Use the `/deployments` directory for infrastructure and orchestration configurations

    master

    The /deployments directory is used to store deployment configurations and templates for various infrastructure and orchestration platforms. This includes configurations for IaaS (Infrastructure as a Service), PaaS (Platform as a Service), system orchestration, and container orchestration.

    Commonly used tools and formats found in this directory include:

    • docker-compose for container orchestration
    • kubernetes/helm for Kubernetes deployments
    • mesos for cluster management
    • terraform for Infrastructure as Code (IaC)
    • bosh for cloud platform automation

  7. Use Go Modules for project management

    master

    Since Go 1.14, Go Modules are the standard way to manage dependencies. Using Go Modules eliminates the need to worry about $GOPATH and where your project is located on your filesystem.

    When initializing your project, ensure you have a go.mod file in the root. While the module path often corresponds to a GitHub URL, it can be any valid path. Note that for older versions of Go, the first component of the module path may require a version identifier (e.g., example.com/pkg/v2), though modern Go versions are more flexible.

  9. Use /internal for private application and library code

    master

    The /internal directory is used for private application code and library code that you do not want other programs or libraries to import.

    Key Characteristics:

    • Compiler Enforcement: The Go compiler enforces this pattern. Packages inside an internal directory can only be imported by code that shares a common ancestor with the internal directory.
    • Flexibility: You are not limited to a single top-level internal directory; you can have multiple internal directories at different levels of your project tree.
    • Organization: For larger projects, you can further structure internal code to separate common and non-common logic, such as /internal/app/myapp for specific application code and /internal/pkg/myprivlib for shared private libraries.

  10. Use common application directories for configuration and scripts

    master

    Organize non-code project assets using the following standard directories:

    • /configs: Configuration file templates or default settings (e.g., confd or consul-template files).
    • /init: System init configurations (systemd, upstart, sysv) and process managers (runit, supervisord).
    • /scripts: Scripts for building, installing, analysis, and other tasks. Use these to keep your root Makefile small and simple.
    • /test: External test applications and test data. To ensure Go ignores these directories, place data in /test/data or /test/testdata. Note that Go also ignores directories or files starting with . or _.

  11. Use the `/internal` directory for private application code

    master

    The /internal directory is for the internal code of your application and libraries. Code placed here is protected by the Go compiler and cannot be imported by other applications or libraries.

    Structuring Internal Code:

    • You can use multiple internal directories at different levels of your project structure.
    • For larger projects, you can separate application code from internal library code:
      • /internal/app/myapp: Application-specific logic.
      • /internal/pkg/myprivlib: Private libraries used by the application.
    /internal
  /app
    /myapp
  /pkg
    /myprivlib

  12. Organize external tests in `/test`

    master

    The /test directory is for additional external test applications and test data. You can organize this directory freely.

    Best Practices:

    • For large projects, use subdirectories for test data, such as /test/data or /test/testdata.
    • Go will automatically ignore files in paths starting with . or _, providing flexibility for naming test data directories.