Go Project Workspace Structure

A Minimal Layout

The simplest possible Go project is just a go.mod file and a main.go in the same directory. As a project grows, code is split into subdirectories, each subdirectory becoming its own importable package named after its folder.

Example: A Minimal Layout

package main

import "fmt"

func main() {
	fmt.Println("myapp/")
	fmt.Println("  go.mod")
	fmt.Println("  main.go")
}

Organizing Packages by Folder

Each directory containing .go files (other than the root) typically represents one package, imported by its path relative to the module root, such as github.com/example/myapp/utils. This convention keeps related code together and makes the import graph easy to follow just by looking at the file tree.

Note: Package names are conventionally short, lowercase, and match the folder name.

Example: Organizing Packages by Folder

package main

import "fmt"

func main() {
	layout := []string{"myapp/go.mod", "myapp/main.go", "myapp/utils/strings.go"}
	for _, path := range layout {
		fmt.Println(path)
	}
}

The internal/ Convention

Go treats any package inside a directory named internal specially: it can only be imported by code rooted at the parent of that internal directory. This is the standard way to mark packages as private implementation details that outside modules should not depend on.

Example: The internal/ Convention

package main

import "fmt"

func main() {
	fmt.Println("myapp/internal/auth can only be imported from within myapp")
}

Where Tests Live

Go test files sit right next to the code they cover and are named with a _test.go suffix, such as strings_test.go alongside strings.go. The 'go test' tool automatically finds and runs every _test.go file in a package, so there's no separate test-discovery configuration needed.

Example: Where Tests Live

package main

import "fmt"

func main() {
	fmt.Println("utils/strings.go")
	fmt.Println("utils/strings_test.go")
}