DEV Community

Bohdan Stupak
Bohdan Stupak

Posted on • Edited on

Implementing clean architecture in Go

#go #architecture #docker #swagger

It has been written a lot about the clean architecture. Its main value is the ability to maintain free from side effects domain layer that allows us to test core business logic without leveraging heavy mocks.

This is accomplished by writing dependency-free core domain logic and external adapters (be it database storage or API layer) that rely on the domain and not vice versa.

In this article, we'll have a look at how clean architecture is implemented with a sample Go project. We'll cover some additional topics such as containerization and implementing OpenAPI specification with Swagger.

While I'll highlight the points of interest in the article you may take a look at the entire project at my Github

Project requirements

We are required to provide an implementation of a REST API to simulate a deck of cards.

We will need to provide the following methods to your API ho handle cards and decks:

  • Create a new Deck
  • Open a Deck
  • Draw a Card

Create a new Deck

It would create the standard 52-card deck of French playing cards, It includes all thirteen ranks in each of the four suits: clubs (♣), diamonds (♦), hearts (♥) and spades (♠). You don't need to worry about Joker cards for this assignment.

  • the deck to be shuffled or not — by default the deck is sequential: A-spades, 2-spades, 3-spades... followed by diamonds, clubs, then hearts.
  • the deck to be full or partial — by default it returns the standard 52 cards, otherwise the request would accept the wanted cards like this example ?cards=AS,KD,AC,2C,KH

The response needs to return a JSON that would include:

  • the deck id (UUID)
  • the deck properties like shuffled (boolean) and total cards remaining in this deck (integer) 
{
    "deck_id": "a251071b-662f-44b6-ba11-e24863039c59",
    "shuffled": false,
    "remaining": 30
}
Enter fullscreen mode Exit fullscreen mode

Open a Deck

It would return a given deck by its UUID. If the deck was not passed over or is invalid it should return an error. This method will "open the deck", meaning that it will list all cards by the order it was created.

The response needs to return a JSON that would include:

  • the deck id (UUID)
  • the deck properties like shuffled (boolean) and total cards remaining in this deck (integer)
  • all the remaining cards cards (card object) 
{
    "deck_id": "a251071b-662f-44b6-ba11-e24863039c59",
    "shuffled": false,
    "remaining": 3,
    "cards": [
        {
            "value": "ACE",
            "suit": "SPADES",
            "code": "AS"
        },
                {
            "value": "KING",
            "suit": "HEARTS",
            "code": "KH"
        },
        {
            "value": "8",
            "suit": "CLUBS",
            "code": "8C"
        }
    ]
}
Enter fullscreen mode Exit fullscreen mode

Draw a Card

We would draw a card(s) of a given Deck. If the deck was not passed over or invalid it should return an error. A count parameter needs to be provided to define how many cards to draw from the deck.

The response needs to return a JSON that would include:

  • all the drawn cards cards (card object) 
{
    "cards": [
        {
            "value": "QUEEN",
            "suit": "HEARTS",
            "code": "QH"
        },
        {
            "value": "4",
            "suit": "DIAMONDS",
            "code": "4D"
        }
    ]
}
Enter fullscreen mode Exit fullscreen mode

Designing the domain

Since the domain is an integral part of our application we'll start designing our system from the domain.

Let's encode our Shape and Rank types as iota. If you're acquainted with other languages you might think of it as an enum which is pretty neat since our task assumes some sort of build-in order so we might leverage underlying numerical value just for that matter.

type Shape uint8

const (
    Spades Shape = iota
    Diamonds
    Clubs
    Hearts
)

type Rank int8

const (
    Ace Rank = iota
    Two
    Three
    Four
    Five
    Six
    Seven
    Eight
    Nine
    Ten
    Jack
    Queen
    King
)
Enter fullscreen mode Exit fullscreen mode

With that done we can encode Card as a combination of its shape and rank

type Card struct {
    Rank  Rank
    Shape Shape
}
Enter fullscreen mode Exit fullscreen mode

One of the functions of domain-driven design is making illegal states unrepresentable but since all combinations of ranks and shapes are valid creating a card is pretty straightforward

func CreateCard(rank Rank, shape Shape) Card {
    return Card{
        Rank:  rank,
        Shape: shape,
    }
}
Enter fullscreen mode Exit fullscreen mode

Now let's have a look at the deck

type Deck struct {
    DeckId   uuid.UUID
    Shuffled bool
    Cards    []Card
}
Enter fullscreen mode Exit fullscreen mode

The deck will exhibit three operations: create a deck, draw cards and count remaining cards.

func CreateDeck(shuffled bool, cards ...Card) Deck {
    if len(cards) == 0 {
        cards = initCards()
    }
    if shuffled {
        shuffleCards(cards)
    }

    return Deck{
        DeckId:   uuid.New(),
        Shuffled: shuffled,
        Cards:    cards,
    }
}

func DrawCards(deck *Deck, count uint8) ([]Card, error) {
    if count > CountRemainingCards(*deck) {
        return nil, errors.New("DrawCards: Insuffucient amount of cards in deck")
    }
    result := deck.Cards[:count]
    deck.Cards = deck.Cards[count:]
    return result, nil
}

func CountRemainingCards(d Deck) uint8 {
    return uint8(len(d.Cards))
}
Enter fullscreen mode Exit fullscreen mode

Notice that when drawing cards we check whether we have a sufficient amount of cards to perform the operation. In order to signal in case we're unable to proceed we take advantage of Go multiple return values feature.

At this point we may observe one of the key benefits of clean architecture: the core domain logic has no external dependencies which greatly simplifies unit-testing. While most of them are trivial and we'll omit them for the sake of brevity, let's have a look at those that verify whether the deck is shuffled

func TestCreateDeck_ExactCardsArePassed_Shuffled(t *testing.T) {
    jackOfDiamonds := CreateCard(Jack, Diamonds)
    aceOfSpades := CreateCard(Ace, Spades)
    queenOfHearts := CreateCard(Queen, Hearts)
    cards := []Card{jackOfDiamonds, aceOfSpades, queenOfHearts}
    deck := CreateDeck(false, cards...)
    deckCardsCount := make(map[Card]int)
    for _, resCard := range deck.Cards {
        value, exists := deckCardsCount[resCard]
        if exists {
            value++
            deckCardsCount[resCard] = value
        } else {
            deckCardsCount[resCard] = 1
        }
    }
    for _, inputCard := range cards {
        value, found := deckCardsCount[inputCard]
        assert.True(t, found, "Expected all cards to be present")
        assert.Equal(t, 1, value, "Expected cards not to be duplicate")
    }
}
Enter fullscreen mode Exit fullscreen mode

Obviously, we cannot verify the order of shuffled cards. What we can do instead is to verify that the shuffled deck satisfies properties of interest which are that we have every card present and we have no duplicate cards in our deck. Such a technique closely resembles property-based testing.

As a side note, it's worth mentioning that in order to eliminate boilerplate assertion code we take advantage of testify library.

Providing the API

Let's start off with defining routes.

func main() {
    r := gin.Default()
    r.POST("/create-deck", api.CreateDeckHandler)
    r.GET("/open-deck", api.OpenDeckHandler)
    r.PUT("/draw-cards", api.DrawCardsHandler)
    r.Run()
}
Enter fullscreen mode Exit fullscreen mode

Some of the readers may be confused by the fact that the create-deck endpoint according to the requirements listed above accepts parameters as a part of URL request and might consider making this endpoint accept GET requests instead of POST. However, an important prerequisite of GET requests is that they exhibit idempotency with is not the case for this endpoint. This is the exact reason why we stick with POST.

Handlers follow the same patterns. We parse query parameters, based on them we create a domain entity, perform operations upon it, update the storage and return specialized DTO. Let's have a look at more details.

type CreateDeckArgs struct {
    Shuffled bool   `form:"shuffled"`
    Cards    string `form:"cards"`
}

type OpenDeckArgs struct {
    DeckId string `form:"deck_id"`
}

type DrawCardsArgs struct {
    DeckId string `form:"deck_id"`
    Count  uint8  `form:"count"`
}

func CreateDeckHandler(c *gin.Context) {
    var args CreateDeckArgs
    if c.ShouldBind(&args) == nil {
        var domainCards []domain.Card
        if args.Cards != "" {
            for _, card := range strings.Split(args.Cards, ",") {
                domainCard, err := parseCardStringCode(card)
                if err == nil {
                    domainCards = append(domainCards, domainCard)
                } else {
                    c.String(400, "Invalid request. Invalid card code "+card)
                    return
                }
            }
        }
        deck := domain.CreateDeck(args.Shuffled, domainCards...)
        storage.Add(deck)
        dto := createClosedDeckDTO(deck)
        c.JSON(200, dto)
        return
    } else {
        c.String(400, "Ivalid request. Expecting query of type ?shuffled=<bool>&cards=<card1>,<card2>,...<cardn>")
        return
    }
}

func OpenDeckHandler(c *gin.Context) {
    var args OpenDeckArgs
    if c.ShouldBind(&args) == nil {
        deckId, err := uuid.Parse(args.DeckId)
        if err != nil {
            c.String(400, "Bad Request. Expecing request in format ?deck_id=<uuid>")
            return
        }
        deck, found := storage.Get(deckId)
        if !found {
            c.String(400, "Bad Request. Deck with given id not found")
            return
        }
        dto := createOpenDeckDTO(deck)
        c.JSON(200, dto)
        return
    } else {
        c.String(400, "Bad Request. Expecing request in format ?deck_id=<uuid>")
        return
    }
}

func DrawCardsHandler(c *gin.Context) {
    var args DrawCardsArgs
    if c.ShouldBind(&args) == nil {
        deckId, err := uuid.Parse(args.DeckId)
        if err != nil {
            c.String(400, "Bad Request. Expecing request in format ?deck_id=<uuid>")
            return
        }
        deck, found := storage.Get(deckId)
        if !found {
            c.String(400, "Bad Request. Expecting request in format ?deck_id=<uuid>&count=<uint8>")
            return
        }
        cards, err := domain.DrawCards(&deck, args.Count)
        if err != nil {
            c.String(400, "Bad Request. Failed to draw cards from the deck")
            return
        }
        var dto []CardDTO
        for _, card := range cards {
            dto = append(dto, createCardDTO(card))
        }
        storage.Add(deck)
        c.JSON(200, dto)
        return
    } else {
        c.String(400, "Bad Request. Expecting request in format ?deck_id=<uuid>&count=<uint8>")
        return
    }
}
Enter fullscreen mode Exit fullscreen mode

Defining OpenAPI specification

The way we should treat OpenAPI specification is not solely as a fancy docs generator (although it is sufficient for the sake of our article) but also as a standard for describing REST APIs that simplifies their consumption for the clients.

Let's start off with declarative comments decorating our main method. These comments will be used later to automatically generate Swagger Specification. Here you can look up the format.

// @title Deck Management API
// @version 0.1
// @description This is a sample server server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8080
// @BasePath /
// @schemes http
func main() {
Enter fullscreen mode Exit fullscreen mode

The same goes for our handler. Let's take a look at one of them as an example.

// CreateDeckHandler godoc
// @Summary Creates new deck.
// @Description Creates deck that can be either shuffled or unshuffled. It can accept the list of exact cards which can be shuffled or unshuffled as well. In case no cards provided it returns a deck with 52 cards.
// @Accept */*
// @Produce json
// @Param shuffled query bool  true  "indicates whether deck is shuffled"
// @Param cards    query array false "array of card codes i.e. 8C,AS,7D"
// @Success 200 {object} ClosedDeckDTO
// @Router /create-deck [post]
func CreateDeckHandler(c *gin.Context) {
Enter fullscreen mode Exit fullscreen mode

Now let's pull Swagger libraries

go get -v github.com/swaggo/swag/cmd/swag
go get -v github.com/swaggo/gin-sagger
go get -v github.com/swaggo/files
Enter fullscreen mode Exit fullscreen mode

Now we're going to generate the specification

swag init -g main.go --output docs
Enter fullscreen mode Exit fullscreen mode

This command will generate needed files inside the docs folder.

The next step is updating our main.go file with the necessary imports

_ "toggl-deck-management-api/docs"
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
Enter fullscreen mode Exit fullscreen mode

And the endpoint

url := ginSwagger.URL("/swagger/doc.json")
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))
Enter fullscreen mode Exit fullscreen mode

With all that done, now we can run our application and see documentation generated by Swagger.

Containerizing API

Last but not least is how we are going to deploy our application. The traditional way of doing this is installing the runtime on a dedicated server and running the application over the runtime installed.

Containerization is the convenient way to package runtime along with the application which might be convenient if we want to utilize auto-scale functionality and we might not have all the needed servers with the environment installed at our disposal.

Docker is the most popular containerization solution so we'll take advantage of it. To do so we'll create dockerfile at the root of our project.

The first thing we'll do is chose the runtime image we'll base our application upon

FROM golang:1.18-bullseye
Enter fullscreen mode Exit fullscreen mode

After that, we'll copy the source into the workdirectory and build it

RUN mkdir /app
COPY . /app
WORKDIR /app
RUN go build -o server .
Enter fullscreen mode Exit fullscreen mode

The last step is exposing the port to the outside world and running the application

EXPOSE 8080
CMD [ "/app/server" ]
Enter fullscreen mode Exit fullscreen mode

Now, granted Docker is installed on our machine, we can run the app with

docker build -t <image-name> .
docker run -it --rm -p 8080:8080 <image-name>
Enter fullscreen mode Exit fullscreen mode

Conclusion

In this article, we've covered the holistic process of writing clean architecture API in Go. Starting from the well-tested domain, providing an API layer for it, documenting it using OpenAPI standard, and packaging our runtime together with the app and thus simplifying the deployment process.

Top comments (2)

Collapse
 
marcello_h profile image
Marcelloh •

Conculsion > Conclusion ;-)

Collapse
 
michaeltharrington profile image
Michael Tharrington •

Haha, as long as it's not Convulsion!

Read next

idsulik profile image

Introducing Helm CEL: A More Expressive Way to Validate Your Helm Charts

Suleiman Dibirov -

1shubham7 profile image

My journey from a CNCF contributor to LFX mentee

Shubham Singh -

thenanjay profile image

Docker Image Optimization: Reducing Size for Faster Deployments

Dhananjay Patel -

alvinslee profile image

Wow, pnpm, You’re Really Fast

Alvin Lee -