Organize Your Go Project Gracefully

Stefanie Lai
4 min readNov 17, 2023
from Unsplash

The structure design of a Go project always practices the Go philosophy of conciseness and efficiency. A reasonable and favorable layout can improve code readability, simplify dependency management, and optimize the compiling process, which, to some extent, determines the success of the project.

Directories like cmd, internal, and docs are the basics of a standard Go project and play different roles. Such as, the cmd directory is where the entry point of the executable file lies, and docs is the entry of all documents related, while internal contains project-private code. The proper package division can avoid circular dependencies, and facilitate unit testing and code reuse.

Nonetheless, this Go project layout may lead to excessive directory levels and package division, which would burden the management and overwhelm the green hands sometimes.

So it comes to how to grasp “reasonably” when designing. Let’s attempt to find the balance between simplicity and functionality in the directory structure and package design so that the project can grow healthily amid changes.

Standard Layout

Directory structures like cmd and internal were summarized by some gophers in the community before they were systematically concluded in the Standard Go Project Layout, which has more than 40K stars. The standard layout has become the de facto standard for the Go project directory structure even though the beginning of it lies a tip.

It’s not an official standard defined by the core Go dev team.

It is easy to find out that most of the famous Go open-source projects on GitHub basically follow the above layout if you read the source code often, such as Kubernetes, a giant Go project.

Let’s take a glance.

  • The go.mod and go.sum related to the Go…