DEV Community: Cody Potter

The case for `self` receivers in Go

Cody Potter — Sun, 04 Sep 2022 19:52:43 +0000

Ok ok, hear me out. I know you're already lighting torches and sharpening your pitchforks (Side note: Can you sharpen a pitchfork?). I know I'm probably in the minority here, so please allow the little-guy to make a small case for the use of self as a receiver name.

Counterarguments

In an attempt to not straw-man, I want to present as strong of a counterargument I've come across, Refactors. If you use the keyword self for all of your receivers, but you need to move a method from one type to another, suddenly, you are forced to rewrite the context of the method. This specifically becomes a problem when you're moving code between levels of abstraction.

I would however argue that moving logic between levels of abstraction should require you to rethink and restructure your code anyway. No one should expect copying and pasting code from one layer to another should "just work".

The current meta

Go has an official stance on the naming of method receivers.

The name of a method's receiver should be a reflection of its identity; often a one or two letter abbreviation of its type suffices (such as "c" or "cl" for "Client"). Don't use generic names such as "me", "this" or "self", identifiers typical of object-oriented languages that gives the method a special meaning. In Go, the receiver of a method is just another parameter and therefore, should be named accordingly. The name need not be as descriptive as that of a method argument, as its role is obvious and serves no documentary purpose. It can be very short as it will appear on almost every line of every method of the type; familiarity admits brevity. Be consistent, too: if you call the receiver "c" in one method, don't call it "cl" in another.

I'd like to argue that the very last sentence there completely contradicts all of the previous statements, "Be consistent". Idiomatic go code aims to be clear above all else. Having no reserved keyword to use as the name for the method's owner leaves an opportunity for a lack of clarity. Extremely short variable names have a tendency to collide with other names and have the same result.

There is no mechanism enforcing consistency here. There's nothing stopping the programmer from giving every method a different receiver name for the same type. For example, a type Server could have any of the receiver names s, srv, server, or sv. You might be able to make a case for this if you had been using s for all your previous methods, but then you have to add a new function signature like:

func (server Server) CashOut (s Service)

From inside the function, the short variable naming begins to work against you. Does s represent the Server or the Service? You'd have to either:
A. Break your previous pattern of using s as the receiver.
B. Break the pattern of short variable naming and name use a name like service for the Service.
Either way, this is unclear, and you're forced to break a rule.

Certainly not OOP

Go insists strongly that it does not have classes. However, you can define methods on types. Sure, Object-Oriented-Programming and classes come with a lot of baggage. However, I'd argue that simply referring to these functions as methods lets the cat out of the bag. We're attaching a function to an obje --cough cough, excuse me, type. We're defining a method on a type. Go treats the receiver as if its an additional argument to the function.

Go insists that a receiver is just syntactic sugar for an additional parameter. But don't get it twisted! A type can only satisfy an interface if all the methods are defined on the type 😉.

It's beginning to sound like we're having our cake and eating it too! I'm a little confused why the designers of Go are so staunchly opposed to reserving a keyword for the receiver but then rely so heavily on the concept of methods which originates from object oriented programming.

The language has basically cracked a window for code smells to leak into. The proverbial window is programmer-defined keywords and the smell is bad variable naming.

To swap metaphors for a second, gifting the programmer with the ability to name the method receiver is a cafe door that swings both ways. Sure you have the ability to customize your receiver name to something that reads very nicely, but that cafe door can come swing back and smack you in the face when you rework your type and now the name no longer reads nicely. Or you just flat out picked a bad name that isn't working in your favor any longer.

In short, TLDR

If we really care so much about consistency, reserve a keyword for method receiver and be consistent about it. Pick a word and stick with it. I'll be using self.

I'd love to hear strong counterarguments and be proven wrong. I love this language and I'd love to be on board with the design, but I have yet to hear a good argument for single-letter names for variables or receivers.

Layered Architectures in Go

Cody Potter — Sun, 04 Sep 2022 03:00:28 +0000

Motivation

There is a need to implement consistent architectural language in large Go services. One such pattern that has proven to work well is the Layered Architecture.

When I talk about architecture, I'm not talking about infrastructure. I'm speaking only to code organization for a go project.

This post is a pretty opinionated take on how you could implement this pattern, so take what you like and leave what you don't.

What is a layered architecture?

It's an extremely common and widely used architectural design pattern. It defines an application composed of horizontal layers that function together as one unit of software. We separate the code components logically. Layers may be individual or logical groupings of Go packages.

Closely related patterns include Domain-driven design, N-tiered, Uncle Bob Martin Clean Architecture, Hexagonal, and Ports and Adapters.

Guidelines

Let's start with broad strokes before we dive into the code.

Layered Packages

A layered package is a go package that aligns with the following principles:

Layered packages must only import their immediate child or any neutral packages. The compiler's import cycle detection will help to enforce this. It's up to you to avoid "skipping a layer" by calling a method from a layer 2 steps down, for example. Following this principle will make testing easier (more on this later). This principle aligns with the Law of Demeter, i.e. "Only talk to your immediate friends".
Global shared variables are not welcome in layered packages. Eliminating globals means eliminating side effects and hard-to-read code. Minimizing variable scope is a core tenet of clean code. This concept is covered extensively in Code Complete.
Layer implementations (structs) should have an interface that describes its functionality to the layer above. This interface can be defined in the layer itself or the parent layer. Whatever makes the most intuitive sense to you.
Layered packages should have a New() function that creates and configures a new instance of the component that satisfies the interface described in principle 3. Principles 3 and 4 correlate to a popular go-ism "accept interfaces, return structs."
Avoid shared structs that are passed layer to layer. This leads to bloated static data structures that aren't always properly hydrated. Frequently, the field tags will be correct in one layer, but incorrect in another. If you need data transfer objects (DTOs), each layer should have its own DTOs that get returned upward only with the necessary fields. I suggest using arguments/parameters instead of passing DTOs downward. A good rule of thumb is that basic data types get passed down as parameters and structs get returned upward when needed.

Neutral Packages

A neutral package is a go package that isn't part of our layered design. A neutral package can follow its own design rules. A neutral package may not import a layered package nor any neutral packages (Libraries are fine of course). Need to import another neutral package? It’s likely those packages should be joined.

Example: itty bitty social

Let's design a layered architecture for a small social network API. Let's pretend the requirements for this API could grow very rapidly. If we start out with a layered architecture, it will be easy to grow and scale as more requirements are added. For now, we just need to support users and posts using a SQL database and all the http endpoints that go along with the user and post models.

Here's the working example itty-bitty-social

There's a fair amount going on in this diagram, so lets just break it down from the outside in.

The Layers

The topmost layer consists of the http API. For simplicity sake, we can call it the http layer. It could also be commonly referred to as the communication or driver layer. This layer could be easily swapped out with a worker pool, a CLI, or a GUI in the future. We'll put our gin router stuff and our authentication logic here.
Below that is the app layer. Our business logic and authorization will live here. Additionally, we can slice this layer into a collection of interfaces like Post and User and embed them into one App interface if the layer itself becomes too large.
The third layer is the store layer. We could also call this the repository layer. If we needed to worry about caching in the future, we could split the layer into MySQL and Redis interfaces. We'll put our gorm logic in this layer.
Finally, the neutral metrics package stands alone. Any layered package can freely import it. We can always add more neutral packages that don't depend on others. Neutral packages must remain neutral, meaning they must strictly not import layered packages nor each other. Else, you risk creating two separate layered architectures in one service (yuck). We don't think of these packages as the final layer, because it would break the rule that layered packages should only import their immediate descendant. For example, the http layer could not import the metrics package if it were the 4th layer.

The code

Setup

Let's walk through a vertical slice of our layers to get an idea of how they are set up.



// main.go
package main
func main() {
    // create store layer
    storeLayer := storelayer.New()

    // create app layer
    appLayer := applayer.New(storeLayer)

    // create http layer
    api := httplayer.New(appLayer)

    api.Engage()
}

You can see here how we build the layers from the bottom up, each time using the lower layer to build the layer above. Finally, we engage the http layer.



// httplayer/router.go
package httplayer

import (
    ...
)

type httpApi struct {
    engine *gin.Engine
    app    applayer.App
}

func New(appLayer applayer.App) *httpApi {
    a := &httpApi{
        engine: gin.New(),
        app:    appLayer,
    }
    a.SetupRoutes()
    return a
}

func (self *httpApi) SetupRoutes() {
    self.engine.Use(gin.Recovery())
    api := self.engine.Group("/api")
    {
        users := api.Group("/users")
        {
            users.GET("", self.getAllUsers)
            users.POST("", self.createUser)
        }
        posts := api.Group("/posts")
        {
            posts.GET("", self.getAllPosts)
            posts.POST("", self.createPost)
        }
    }
}

func (self *httpApi) Engage() {
    self.engine.Run()
}

Pardon my use of self as a receiver here. I have a personal dislike of Go's custom receiver names. In my opinion, custom receiver naming is a violation of the go proverb "clear is better than clever".

Notice the New function that creates the http api and how it stores the app layer on itself to use later. Also, notice we aren't using any global variables here.



// applayer/app.go
package applayer

import (
    ...
)

type App interface {
    GetAllUsers(ctx context.Context) ([]storelayer.User, error)
    CreateUser(ctx context.Context, name, handle string) error
    CreatePost(ctx context.Context, content, owner string) error
    GetAllPosts(ctx context.Context) ([]Post, error)
}

type app struct {
    store storelayer.Store
}

func New(store storelayer.Store) *app {
    return &app{
        store: store,
    }
}

We use the same exact pattern here for the app layer as we did for the http layer.



// storelayer/store.go
package storelayer

import (
    ...
)

type Store interface {
    CreateUser(ctx context.Context, name, handle string) error
    GetAllUsers(ctx context.Context) ([]User, error)
    CreatePost(ctx context.Context, content, owner string) error
    GetAllPosts(ctx context.Context) ([]Post, error)
}

type store struct {
    db *gorm.DB
}

func New() *store {
    db, err := gorm.Open(sqlite.Open("itty-bitty-social.db"), &gorm.Config{})
    if err != nil {
        panic("failed to connect database")
    }

    db.AutoMigrate(&User{})
    db.AutoMigrate(&Post{})
    return &store{
        db: db,
    }
}

Same old song and dance. One interesting thing to note here is how we're storing the reference to the gorm db. It's not a global like you might commonly see. Notice we set up the connection in the New function.

That's how the layers are linked together. Now let's explore a vertical slice of how a request gets fulfilled.

Request Walkthrough



// httplayer/posts.go
package httplayer
...
func (self *httpApi) createPost(c *gin.Context) {
    newPost := &post{}
    err := c.BindJSON(newPost)
    if err != nil {
        logrus.Error("failed to bind in create post: %v", err)
        c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{
            "message": err.Error(),
        })
        return
    }

    // TODO: should set post.owner from auth
    err = self.app.CreatePost(c, newPost.Content, "noodle")
    if err != nil {
        logrus.Error("failed to create post: %v", err)
        c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{
            "message": err.Error(),
        })
        return
    }
    c.JSON(http.StatusAccepted, gin.H{
        "message": "created successfully",
    })
}

The above code is part of the http layer, so it only has 3 responsibilities.

Parse the request
Call into the application layer
Decide how to respond

Notice that if the app layer func CreatePost has an err, we will respond with an appropriate http status code and response. We could use a switch here to parse out sentinel errors from the app layer to make better decisions on the response if different issues could occur in the app layer.



// applayer/posts.go
package applayer
...
func (self *app) CreatePost(ctx context.Context, content, owner string) error {
    return self.store.CreatePost(ctx, content, owner)
}

For the above example, the app layer is just immediately calling the store layer, because we don’t need to add any business logic here. However, this would be a good place to emit metrics, check if the user is banned from posting, or any other “business rules” you could think of.

You might be tempted to omit this method and instead do something like self.appLayer.storeLayer.CreatePost(...), but this is a violation of the Law of Demeter and creates an interdependency. It's best to avoid this and leave this little wrapper function in place. Here's an awesome article about interdependence to check out if you're curious about the motivation here.



// storelayer/posts.go
package storelayer
...
func (self *store) CreatePost(ctx context.Context, content, owner string) error {
    user := &User{}
    err := self.db.Limit(1).Find(user, "handle = ?", owner).Error
    if err != nil {
        return err
    }
    err = self.db.WithContext(ctx).Create(&Post{
        Content: content,
        UserID:  user.ID,
    }).Error
    if err != nil {
        return err
    }
    return nil
}

Any errors that occur here will get passed all the way back up to the http layer and emit a 500. To take this a step further, we should return a store layer sentinel error if the user is not found. Then the app layer would check for that sentinel and return an appropriately detailed error to the http layer so we could return a 4**.

Testing

One of the huge benefits to this pattern is testability. Since each layer is injected into each parent layer, we can generate mocks for each layer and inject those instead. For this code we could easily achieve 100% code coverage when unit testing each layer, since we have full control of the child layers. A great tool to use for generating mocks from interfaces is vektra/mokery. One command will create mocks for each of your interfaces that we can inject during test.

In summary

Thanks for reading! I hope this was a helpful example for understanding the layering design pattern. I appreciate any feedback or questions you might have. If you’d like to see a follow up post on writing unit tests in this pattern, I’m happy to write it up.

Going further

As you take this pattern further, you may find that your layers grow too large. Large interfaces weaken abstraction. To work around this, consider either:
A. Split your layer into smaller layers. You can always add more layers.
B. Split your layer into vertical slices. You can slice a layer's interfaces into smaller interfaces, then the consuming parent can define its own interface for the child, embedding the smaller interfaces into one.