Go Project

External

• https://github.com/golang-standards/project-layout
• https://medium.com/@benbjohnson/standard-package-layout-7cdbc8391fc1

Internal

• Go Language Modularization

TODO

• Where are the generated executables placed? In a transient ./build? This is how YuniKorn does it. The project layout document does not say anything about it.

Overview

This page collects recommendation and facts about Go projects and it was mainly written with the assumption that one project lives in its own repository and contains a single module, as described in Packages, Modules, Projects and Repositories. Of course project can contain multiple modules, but that is not recommended.

A Java-style /src is not recommended.

Project Layout

This layout is inspired by:

https://github.com/golang-standards/project-layout

.
├── api
│    ├── openapi.yaml
│    ├── openapi-spec.gen.go # Generated from openapi.yaml
│    ├── openapi-types.gen.go # Generated from openapi.yaml
│    └── file1.proto, ...
├── protobuf # Alternative directory for Protocol Buffer files.
│    ├── somepkgpb
│    │    ├── file1.proto
│    │    └── file2.proto
│    └── someotherpkgpb
│         ├── file3.proto
│         └── file4.proto
│
├── cmd
│    ├── myserver 
│    │    └── main.go
│    └── myclient
│         └── main.go
├── pkg
├── internal
│    └── server
│         └── openapi-http-server.gen.go # Generated from openapi.yaml
├── config
├── scripts
│    ├── build-myserver.sh 
│    └── build-myclient.sh 
├── docs
├── Makefile
├── README.md
├── go.mod
├── go.sum
└── .gitignore

Directories

api

The directory contains OpenAPI specification files, JSON schema files, protocol definition files.

One option is to also place the type and the spec files generated by the OpenAPI code generator, as shown in the layout above. For more details on how to generate code from the OpenAPI specification, see:

Generate Code with oapi-codegen

Protocol Buffer Support

Protocol Buffer files can be placed in this directory. Alternatively, a protobuf or a protocol can be used. Also see:

Protocol Buffers Go Code Generation

cmd

The directory contains the main applications for this project. If the project has multiple executables, the code fore each should live under their own directory, and the name of the directory should match the name of the executable. This convention aligns with the behavior of the go build command, which names the executable after the name of its parent directory. The Go code file name can be either main.go, which is preferred, or the name of the command myserver.go. Different projects use one of these two conventions. Do not put a lot of code in the /cmd directory. If you think the code can be imported and used in other projects, put it in the /pkg directory. If the code is not reusable, put it in the /internal directory. It's common to have a small main function that imports and invokes the code from the /internal and /pkg directories and nothing else.

main.go

Some project name this file myserver.go.

package main

import "fmt"

func main() {
  fmt.Print("starting my service ...\n")
}

pkg

Place here the packages publicly exported by the module. The presence of a package in this directory shows that it is OK to be used by external applications. Other projects will import these libraries expecting the to work, so think twice before putting something there. The internal directory is a better way to ensure your private packages are not importable, because this is enforced by the complier.

internal

This is the module code that shouldn't be imported by the module's dependent application or libraries. This layout pattern is enforced by the Go compiler. For more details, see:

Internal (Private) Packages

config

Configuration file templates and default configuration.

scripts

This directory contain scripts to perform various build functions, install, analysis, etc.

They should be used by Makefile, which will keep the file small and simple.

docs

Generated documentation, user documentation, design documentation.

Files

Makefile

Makefile should prefer to use scripts from the /scripts directory, which should keep it simple.

.PHONY: build

build: myserver myclient

myserver:
	"$(CURDIR)/scripts/build-myserver.sh"

myserver:
	"$(CURDIR)/scripts/build-myclient.sh"

Example to process: https://github.com/hashicorp/terraform/blob/main/Makefile

Generated Code

Placed within the regular layout, though files have a .gen.go extension.

Project Bootstrap

Follow the same template as Python Project Bootstrap. Use and possibly merge with Go.mod#Initialize_go.mod

Microservice-based Project Layout

Microservices in Go | Project Layout

TODO

• Finish parsing https://github.com/golang-standards/project-layout
• Integrate Vendoring