• Stars
    star
    26
  • Rank 930,752 (Top 19 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created about 5 years ago
  • Updated over 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

My understanding of how to structure a golang project.

Go Project Layout

This is my understanding of how to structure Go project layout. The most important part is how to organize your Go code into packages.

Motivation

A good project layout will make your source code easy to understand, easy to test, and easy to maintain.
Kat Zien has a very good summary(Slides) for this, so I'd like to refer it directly as below:

Questions, decisions

  • Should I put everything in the main package?
  • Should I start with one package and extract other packages over time?
  • How do I decide if something should be in its own package?
  • Should I just use a framework?
  • What's the programming paradigm for Go?
  • Microservices or monolith?
  • How much should be shared between packages?

Why should we care?

Because if Go is going to be a language that companies invest in for the long term, the maintenance of Go programs, the ease of which they can change, will be a key factor in their decision. - Dave Cheney, Golang UK 2016 keynote

Good structure goals

  • Consistent.
  • Easy to understand, navigate and reason about. ("makes sense") Easy to change, loosely-coupled.
  • Easy to test.
  • "As simple as possible, but no simpler."
  • Design reflects exactly how the software works.
  • Structure reflects the design exactly.

Demo

# shell 1
$ go version
go version go1.13.1 linux/amd64
$
$ cd $GOPATH
$ 
$ # app 1: reverse echo
$ go get -u github.com/wangyoucao577/go-project-layout/cmd/echor
$ ./bin/echor "hello world"
dlrow olleh
$
$ # app 2: a simple diagnosis service for server diagnosis. 
$ #    return `Hostname/IP/CPUs/RemoteAddr...` by `HTTP`. 
$ #    sample request: `http://localhost:8000/diagnosis?diagnosis=ping`
$ go get -u github.com/wangyoucao577/go-project-layout/cmd/diagnosis
$ ./bin/diagnosis -alsologtostderr
I1007 18:50:05.550952    3769 main.go:33] Listen on :8000

# shell 2
$ curl "http://localhost:8000/diagnosis?diagnosis=ping"
{
  "Hostname":"server",
  "IP Addresses":[
    "192.168.29.201/24",
    "fe80::1c20:479:9094:4327/64",
    "192.168.141.1/24",
    "fe80::8002:2d87:c4f3:4aab/64",
    "192.168.128.1/24",
    "fe80::eca9:cfa0:9443:b8ff/64",
    "192.168.44.209/28",
    "fe80::8551:306e:7e7:6faf/64"
  ],
  "CPUs":8,
  "Remote Endpoint":"127.0.0.1:64717"
}

Note

This topic is kind of best practices. I'd like to discuss some of them and my opinion, then maybe deep into more best practices in the future.

Top dir /cmd

[My opinion: Strongly recommended]
The cmd layout pattern is very useful when you need to have more than one application binary.

  • Each binary gets a subdirectory (e.g., your_project/cmd/your_app).
    • The subdirectory is the main package for your application.
    • Don't put a lot of code in the main package. Instead, it should only used to initialises and ties everything together.
  • This patterns also helps you keep your project/package go gettable.
    • It means you can use the go get command to fetch (and install) your project, its applications and its libraries (e.g., go get github.com/your_github_username/your_project/cmd/your_app).
  • The official Go tool is one example of the cmd layout patter. A number of other well known projects use the same pattern: Kubernetes, Docker, Prometheus, Influxdb.

Top dir /pkg

[My opinion: NOT good enough, use it if good for you]

  • People also recommend to set up a /pkg top dir in Go project to put your public libraries.
    • These libraries can be used internally by your application.
    • They can also be used by external projects. It's an informal contract between you and other external users of your code. Other projects will import these libraries expecting them to work.
  • But I think it's NOT a good enough idea because
    • It brings confusion since Go workspaces have a directory with the same name and that directory has a different purpose(it’s used to store object files for the packages the Go compiler builds).
    • The meaning of "public libraries" is not clear enough.
      • Even many well known projects use this pattern (Kubernetes, Docker, Grafana, Influxdb, Etcd), Docker and Etcd comment the meaning of "public libraries" again. Both of them limit it only as utility packages, and these utility packages possible to be moved out into its own repository in the future:
        • Docker: pkg/ is a collection of utility packages used by the moby project without being specific to its internals.
        • Etcd: pkg/ is a collection of utility packages used by etcd without being specific to etcd itself. A package belongs here only if it could possibly be moved out into its own repository in the future.

Group packages by dependency

[My opinion: Strongly recommended]

  • Domain types
    • Domain Types are types that model your business functionality and objects.
    • Ben Johnson - Standard Package Layout recommend to place your into root package. This package only contains simple data types, so it will be extremely simple.
    • In my opinion, either place them into root package or place them into a individual subpackage are ok. The most important part here is this package should be extermely simple, and not depend on any other package in application!
  • Each package should only has a single purpose.
  • Packages names describe their purpose.
  • When necessary, use a descriptive parent package and several children implementing the functionality.
  • main package ties together dependencies

More best practices

  • Follow conventions
    • Be similar to the standard library and other popular packages
    • Don't surprise people
    • Be obvious, not clever
  • Use Go modules
  • Avoid global scope and init()

References

More Repositories

1

go-release-action

Automatically publish Go binaries to Github Release Assets through Github Action.
Shell
485
star
2

cashier

基于C#实现的一个童装收银小软件. 支持红外枪条码扫描识别(自备驱动), 可导入童装的条码、价格等数据, 红外枪扫描条码后可自动填充其价格等信息. 可支持手动输入折扣等信息,确认后支持打印机打印收银条.
C#
21
star
3

MyTinyTests

学习时写的一些简单的小例子或自动化使用的一些小工具集合, 包含c, c++, c#, JavaScript, python2/3, golang, Lua, linux bash, windows bat等各种语言的实现, 平台含Windows, Linux, macOSX, iOS, Android等. 尝试用最合适的而不是最熟悉的方法解决问题.
C++
8
star
4

assets-uploader

Command line tool to robustly upload Github release assets.
Go
6
star
5

modern-cpp

Practice and notes for Modern C++(i.e. C++ 11/14/17/20...).
C++
6
star
6

ffmpeg-build

Build ffmpeg with its dependencies from source.
Shell
5
star
7

vt2geojson

Command line tool to dump Mapbox Vector Tiles to GeoJSON.
Go
3
star
8

libmath-finite

A simple library to solve the `__xxx_finite` symbols missed problem due to `glibc` upgrade.
C
2
star
9

algorithms_practice

Practice algorithms and data structures.
Go
2
star
10

medialib

A collection of media diagnose tools.
Go
2
star
11

IpPortEndpointCheck

This tool is designed for check whether IPPortEndpoint is opened on the internet or not. Support both TCP and UDP, both IPv4 and IPv6. For TCP, it's valid if it can be connected. For UDP, it's valid if it can answer "I'm OK".
C#
2
star
12

containers

Container images and orchestration.
Dockerfile
1
star
13

plot-av

Plot Audio/Video streams for better insights.
Python
1
star