When organizing a Go project, the choice of layout is a crucial decision that impacts long-term maintainability and developer experience. While there isn’t one universally perfect structure, some approaches can lead to unnecessary complexity and confusion, while others promote clarity and simplicity.
Often, developers look for a standard Go project layout to follow, hoping it will provide a rigid template for success. However, trying to force every project into a single, overly detailed directory structure can be counterproductive. Go’s strength lies in its simplicity and the way its package system handles visibility and dependencies. A project layout should complement these features, not fight against them.
One common pitfall is creating excessively deep or abstract directory structures right from the start. Layers like pkg, internal, api, service, repository, domain, etc., while sometimes useful, can quickly become confusing if not applied thoughtfully. The goal should be to make code easy to find, understand, and manage dependencies.
For many typical Go applications, especially services, a simpler layout is often more effective. A structure driven by the application’s core domains or functionalities can make more sense than one based purely on technical layers. For instance, grouping related code (like handlers, services, and repositories for a specific feature) within a clear package can improve coherence.
Go’s built-in internal directory is a powerful tool for encapsulation. Code placed inside internal is explicitly limited in its visibility, preventing other projects from importing it. This is excellent for application-specific logic that you don’t intend to expose as a reusable library. Placing your main application code here is a good practice.
Entry points for executables typically reside in the cmd directory. Each subdirectory within cmd represents a separate executable application. For example, cmd/api/main.go could be the entry point for your main service, and cmd/worker/main.go for a background processing application.
The use of a top-level pkg directory is often debated. According to Go conventions, pkg is intended for library code that is safe for external use by other projects. If your project is primarily an application and doesn’t expose reusable libraries, you might not need pkg at all, or you might keep it minimal for truly generic code. Putting application internals in pkg defeats the purpose of internal and can confuse users if the project is public.
Ultimately, a good project layout is one that evolves with the project, keeps dependencies clear and manageable, and makes it easy for any developer joining the team to understand where things are and why. Prioritize simplicity, use Go’s features like internal effectively, and let the structure be guided by the needs of your specific application rather than adhering blindly to a complex template. A flat structure is often better than deep nesting, and grouping by domain or feature can be more intuitive than strict technical layering for smaller to medium-sized projects. The most important aspect is that the chosen layout is consistent and well-understood by the team.
Source: https://itnext.io/go-standard-project-layout-a-mildly-unhinged-rant-be20cb793d0d?source=rss—-5b301f10ddcd—4
