Go Package Organisation

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

Package naming

Here 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.

This 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)
• Standard Package 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. 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 happens to be my favourite Go project at the moment (as you might have observed when I introduced Gostars). 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 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 above.