How to create a proper Golang project layout

A Golang project may contain multiple files with different package names. Setting up a proper layout in these cases is not always very straightforward in Go, especially for beginners. This Go programming tutorial provides a quick overview, with a hands-on example, of specific use case scenarios so that one can understand the concept behind it and create a proper layout for a Go project.

There are no strict rules for the directory structure or how to organize Go project files in a specific way. This is both a good and a bad idea; it is bad because it is easy to create a mess and good because the organizational structure of one’s project can be built according to the programmer’s taste.

Freedom without responsibility, however, can be a mess. Golang programmers typically follow certain patterns in laying out the files and directories in their projects. This also varies from project to project. They follow these patterns because it works not only for them but also for their fellow programmers. Everybody following a specific system is not only productive but also fun to work with. Before going into the project layout, let’s understand some basic elements concerning Go projects. For starters, one of them is a module.

What is a Module in Golang?

In a typical Go project, the first thing a developer should do is create a directory with the project name. Although there are no strict rules, programmers should try to keep the directory name the same as the project name. This directory will contain every file and other subdirectories related to the project:

$ mkdir go-demoproject
$ cd go-demoproject

The next thing a Go developer typically does is use go tool commands related to the module. For instance, if we want to initialize new modules in the current directory. As an example, if we want to initialize modules with we may write the following:

go mod init

This will create two files in the current directory: go.mod and go.sum. Both are actually simple text files and can be opened with any text editor.

Therefore, a module is a collection of Go packages stored in a file tree with a go.mod file at its root. The go.mod file defines the module path from where dependent third-party files are imported and other modules needed to successfully build the application. This is more or less the same as namespaces used in C++, which separate applications in one module with the same application in another module, probably due to different version numbers.

Read: An Introduction to File Handling in Go

Using the go.mod File in Golang

Go modules are defined by the go.mod file, which describes module properties, the Go version, and the dependencies of this project on other modules. The properties include:

  • Module path of the current module, the location from which the module can be downloaded by Golang tools such as module code’s repository location. This also serves as a unique identifier in the case of multiple module version numbers. It also includes the prefix of the package path of all packages in the module.
  • Minimum Go version number required for the current module.
  • Optional instructions on how to replace the current module with another module version.