Go Package Organisation
Tags: go, structure
Published: 2020-02-22 19:19:02

---
title: Go Package Organisation
published: true
date: 2018-02-24 20:42:24 UTC
tags: go, structure
canonical_url: https://www.skillscheck.co.uk/post/go-package-organisation/
---

# Go Package Organisation

> This is more for my notes, a list of resources and perhaps a little discussion on the side.

## Package naming

[Here](https://golang.org/doc/code.html#PackageNames) is some ‘official’ documentation about name of the package. The short version is that the `main` function needs to be in the `package main`. Package name does not need to be unique, but the full import path does.

Some package naming conventions can be found [here](https://talks.golang.org/2014/organizeio.slide#6).

[This](https://dave.cheney.net/2014/12/01/five-suggestions-for-setting-up-a-go-project) says that it’s talking about package organisation but it covers naming of packages, and the effect name and location has on packages. Short version; lower case, don’t bother repeating package names in package types. But it’s worth reading all of this post along with anything else that Dave Cheney writes.

## Package layout

There are 3 interesting things to read about laying down your packages:

- [Standard Go Project Layout (Github)](https://github.com/golang-standards/project-layout)
- [Standard Package Layout](https://github.com/golang-standards/project-layout)

These 2 pages are interesting background to what kind of code to put in which packages. Short version:

- Put executatble commands (ie. with your `main` function) in sub-packages under `cmd`
- Don’t forget to put your imported Go packages under `vendor`. This is the recommended idiomatic way of managing dependencies and is the subject a _lot_ of discussion on the interwebs
- `examples` for code examples to tell people how to use your code

There are plenty of other little gems but that’s the crux of it.

My favourite result from my rabid googling is [this](https://stackoverflow.com/questions/14867452/what-is-a-sensible-way-to-layout-a-go-project). Here we have 5 concrete rules with good reasoning around it. For me, the important take-aways are:

1. The root package should contain domain objects and interfaces for services
2. Organise sub-packages by dependency, including to packages such as `net/http`

Again, there is the recommendation that you’re `main` packages sit in their own sub-package under `cmd`. This time though, it’s suggested that this is where you want to do your dependency injection.

One thing that this article doesn’t cover is where the business logic sits. The examples on the page have this spread out between a `postgres` sub-package and the root package. My gut feel is that there needs to be a certain amount of interpretation about what needs to go in to your dependency related sub packages and the root package.

## Real Examples

### Buffalo

[Buffalo](https://gobuffalo.io) happens to be my favourite Go project at the moment (as you might have observed when I [introduced Gostars](https://dev.to/dnnrly/gostars-first-steps-13l9-temp-slug-7283914)). The thing is, Buffalo doesn’t go anyway near this organisation. Domain models sit under `models`, handlers and business logic sits under `app`. In there too are directories for putting HTML templates and static assets.

This layout could be because of the Ruby On Rail heritage of this library. A side effect of this though is that you will hit several of the problems that were discuss in articles above. Beware but bare in mind that Buffalo offers an incredibly powerful approach to writing your web app.

### Goa

[Goa](https://goa.design/) is a different web framework. Again, it follows its own organisation. `app` contains handlers and request and response objects, `controllers` contains the actual controllers with business logic.

### Kubernetes

This appears to follow the example of the [Gihub project](https://github.com/golang-standards/project-layout) above.