DEV Community

Cover image for Go - Project Structure and Guidelines
Ankit Kumar
Ankit Kumar

Posted on

Go - Project Structure and Guidelines

Alt Text

Assuming you read my post you should have the starting point for a minimal go web service. For your first project it is easier to keep all your code in one folder, in the base of your project, but at some point you want to restructure things.

All go code is organised into packages and its simply consists of several .go files. A package is the entry point to access Go code.

  1. Best Practice to use multiple files
    a. Feel free to separate you code into as many files as possible.
    b. Aim to ensure it is easy to navigate your way around
    c. Loosely couple sections of the service or application

  2. Keep types close
    It is often a good practice to keep the core types grouped at the top of a file.

  3. Organise by responsibility
    In other languages we organise types by models or types but in go we organise code by their functional responsibilities.

  4. Start to Use Godoc
    Godoc extracts and generates documentation for Go programs. It runs as a web server and presents the documentation as a web page.

  5. Dont't write your business logic to main.go

Naming Convention

  1. Package names should be lowercase. Don't use snake_case or camelCase.
  2. Avoid overly use terms like util, common, script etc
  3. Use singular form
  4. Rename should follow the same rules

import (
gourl "net/url"
myurl "myApp/url"

*Repository Structures examples: *


As you noticed, there is func_test.go file in the same directory. In Go, you save unit tests inside separate files with a filename ending with _test.go. Go provides go test command out of the box which executes these files and runs tests.

Common terms we use in package structure

  1. /cmd
    This folder contains the main application entry point files for the project, with the directory name matching the name for the binary.

  2. /pkg
    This folder contains code which is OK for other services to consume, this may include API clients, or utility functions which may be handy for other projects but don’t justify their own project.

  3. /internal
    This package holds the private library code used in your service, it is specific to the function of the service and not shared with other services.

  4. go.mod
    The go. mod file defines the module's module path, which is also the import path used for the root directory, and its dependency requirements, which are the other modules needed for a successful build.

  5. go.sum contains all the dependency check sums, and is managed by the go tools. The checksum present in go.sum file is used to validate the checksum of each of direct and indirect dependency to confirm that none of them has been modified.


├── config.go
├── go.mod
├── go.sum
├── clientlib
│   ├── lib.go
│   └── lib_test.go
├── cmd
│   ├── modlib-client
│   │   └── main.go
│   └── modlib-server
│       └── main.go
├── internal
│   └── auth
│       ├── auth.go
│       └── auth_test.go
└── serverlib
    └── lib.go


Discussion (0)