| <!--{ | |
| "Title": "Organizing a Go module" | |
| }--> | |
| A common question developers new to Go have is "How do I organize my Go | |
| project?", in terms of the layout of files and folders. The goal of this | |
| document is to provide some guidelines that will help answer this question. To | |
| make the most of this document, make sure you're familiar with the basics of Go | |
| modules by reading [the tutorial](/doc/tutorial/create-module) and | |
| [managing module source](/doc/modules/managing-source). | |
| Go projects can include packages, command-line programs or a combination of the | |
| two. This guide is organized by project type. | |
| ### Basic package | |
| A basic Go package has all its code in the project's root directory. The project | |
| consists of a single module, which consists of a single package. The package | |
| name matches the last path component of the module name. For a very simple | |
| package requiring a single Go file, the project structure is: | |
| ``` | |
| project-root-directory/ | |
| go.mod | |
| modname.go | |
| modname_test.go | |
| ``` | |
| _[throughout this document, file/package names are entirely arbitrary]_ | |
| Assuming this directory is uploaded to a GitHub repository at | |
| `github.com/someuser/modname`, the `module` line in the `go.mod` file should say | |
| `module github.com/someuser/modname`. | |
| The code in `modname.go` declares the package with: | |
| ``` | |
| package modname | |
| // ... package code here | |
| ``` | |
| Users can then rely on this package by `import`-ing it in their Go code with: | |
| ``` | |
| import "github.com/someuser/modname" | |
| ``` | |
| A Go package can be split into multiple files, all residing within the same | |
| directory, e.g.: | |
| ``` | |
| project-root-directory/ | |
| go.mod | |
| modname.go | |
| modname_test.go | |
| auth.go | |
| auth_test.go | |
| hash.go | |
| hash_test.go | |
| ``` | |
| All the files in the directory declare `package modname`. | |
| ### Basic command | |
| A basic executable program (or command-line tool) is structured according to its | |
| complexity and code size. The simplest program can consist of a single Go file | |
| where `func main` is defined. Larger programs can have their code split across | |
| multiple files, all declaring `package main`: | |
| ``` | |
| project-root-directory/ | |
| go.mod | |
| auth.go | |
| auth_test.go | |
| client.go | |
| main.go | |
| ``` | |
| Here the `main.go` file contains `func main`, but this is just a convention. The | |
| "main" file can also be called `modname.go` (for an appropriate value of | |
| `modname`) or anything else. | |
| Assuming this directory is uploaded to a GitHub repository at | |
| `github.com/someuser/modname`, the `module` line in the `go.mod` file should | |
| say: | |
| ``` | |
| module github.com/someuser/modname | |
| ``` | |
| And a user should be able to install it on their machine with: | |
| ``` | |
| $ go install github.com/someuser/modname@latest | |
| ``` | |
| ### Package or command with supporting packages | |
| Larger packages or commands may benefit from splitting off some functionality | |
| into supporting packages. Initially, it's recommended placing such packages into | |
| a directory named `internal`; | |
| [this prevents](https://pkg.go.dev/cmd/go#hdr-Internal_Directories) other | |
| modules from depending on packages we don't necessarily want to expose and | |
| support for external uses. Since other projects cannot import code from our | |
| `internal` directory, we're free to refactor its API and generally move things | |
| around without breaking external users. The project structure for a package is | |
| thus: | |
| ``` | |
| project-root-directory/ | |
| internal/ | |
| auth/ | |
| auth.go | |
| auth_test.go | |
| hash/ | |
| hash.go | |
| hash_test.go | |
| go.mod | |
| modname.go | |
| modname_test.go | |
| ``` | |
| The `modname.go` file declares `package modname`, `auth.go` declares `package | |
| auth` and so on. `modname.go` can import the `auth` package as follows: | |
| ``` | |
| import "github.com/someuser/modname/internal/auth" | |
| ``` | |
| The layout for a command with supporting packages in an `internal` directory is | |
| very similar, except that the file(s) in the root directory declare `package | |
| main`. | |
| ### Multiple packages | |
| A module can consist of multiple importable packages; each package has its own | |
| directory, and can be structured hierarchically. Here's a sample project | |
| structure: | |
| ``` | |
| project-root-directory/ | |
| go.mod | |
| modname.go | |
| modname_test.go | |
| auth/ | |
| auth.go | |
| auth_test.go | |
| token/ | |
| token.go | |
| token_test.go | |
| hash/ | |
| hash.go | |
| internal/ | |
| trace/ | |
| trace.go | |
| ``` | |
| As a reminder, we assume that the `module` line in `go.mod` says: | |
| ``` | |
| module github.com/someuser/modname | |
| ``` | |
| The `modname` package resides in the root directory, declares `package modname` | |
| and can be imported by users with: | |
| ``` | |
| import "github.com/someuser/modname" | |
| ``` | |
| Sub-packages can be imported by users as follows: | |
| ``` | |
| import "github.com/someuser/modname/auth" | |
| import "github.com/someuser/modname/auth/token" | |
| import "github.com/someuser/modname/hash" | |
| ``` | |
| Package `trace` that resides in `internal/trace` cannot be imported outside this | |
| module. It's recommended to keep packages in `internal` as much as possible. | |
| ### Multiple commands | |
| Multiple programs in the same repository will typically have separate directories: | |
| ``` | |
| project-root-directory/ | |
| go.mod | |
| internal/ | |
| ... shared internal packages | |
| prog1/ | |
| main.go | |
| prog2/ | |
| main.go | |
| ``` | |
| In each directory, the program's Go files declare `package main`. A top-level | |
| `internal` directory can contain shared packages used by all commands in the | |
| repository. | |
| Users can install these programs as follows: | |
| ``` | |
| $ go install github.com/someuser/modname/prog1@latest | |
| $ go install github.com/someuser/modname/prog2@latest | |
| ``` | |
| A common convention is placing all commands in a repository into a `cmd` | |
| directory; while this isn't strictly necessary in a repository that consists | |
| only of commands, it's very useful in a mixed repository that has both commands | |
| and importable packages, as we will discuss next. | |
| ### Packages and commands in the same repository | |
| Sometimes a repository will provide both importable packages and installable | |
| commands with related functionality. Here's a sample project structure for such | |
| a repository: | |
| ``` | |
| project-root-directory/ | |
| go.mod | |
| modname.go | |
| modname_test.go | |
| auth/ | |
| auth.go | |
| auth_test.go | |
| internal/ | |
| ... internal packages | |
| cmd/ | |
| prog1/ | |
| main.go | |
| prog2/ | |
| main.go | |
| ``` | |
| Assuming this module is called `github.com/someuser/modname`, users can now both | |
| import packages from it: | |
| ``` | |
| import "github.com/someuser/modname" | |
| import "github.com/someuser/modname/auth" | |
| ``` | |
| And install programs from it: | |
| ``` | |
| $ go install github.com/someuser/modname/cmd/prog1@latest | |
| $ go install github.com/someuser/modname/cmd/prog2@latest | |
| ``` | |
| ### Server project | |
| Go is a common language choice for implementing *servers*. There is a very large | |
| variance in the structure of such projects, given the many aspects of server | |
| development: protocols (REST? gRPC?), deployments, front-end files, | |
| containerization, scripts and so on. We will focus our guidance here on the | |
| parts of the project written in Go. | |
| Server projects typically won't have packages for export, since a server is | |
| usually a self-contained binary (or a group of binaries). Therefore, it's | |
| recommended to keep the Go packages implementing the server's logic in the | |
| `internal` directory. Moreover, since the project is likely to have many other | |
| directories with non-Go files, it's a good idea to keep all Go commands together | |
| in a `cmd` directory: | |
| ``` | |
| project-root-directory/ | |
| go.mod | |
| internal/ | |
| auth/ | |
| ... | |
| metrics/ | |
| ... | |
| model/ | |
| ... | |
| cmd/ | |
| api-server/ | |
| main.go | |
| metrics-analyzer/ | |
| main.go | |
| ... | |
| ... the project's other directories with non-Go code | |
| ``` | |
| In case the server repository grows packages that become useful for sharing with | |
| other projects, it's best to split these off to separate modules. |