Golang on Ompluscator's Blog

LLM and Go: OpenAI integration via Responses API

marko.milojevic@ompluscator.io (Marko Milojevic) — Thu, 19 Mar 2026 10:00:00 +0100

The previous two articles in this series covered the Chat Completions API — how to set up a client, maintain conversation history manually, call external tools, and control output structure with response_format. That API gives you full control and a clear mental model of what goes over the wire. This article covers the other primary OpenAI interface: the Responses API.

The Responses API moves conversation state from the client to OpenAI’s servers. You no longer maintain a history slice and re-send it with every call. Instead, you track a response ID and pass it back on the next request. That is a meaningful shift for agent-oriented applications — less maintenance, but also less transparency. Understanding the trade-offs between the two APIs is worth doing before choosing which one to build on.

Responses API
#

OpenAI introduced the Responses API in 2025, positioning it as the foundation for building agents. The Chat Completions API is stateless — every request must carry the full conversation history, and the client owns that state entirely. The Responses API inverts this: conversation state lives on OpenAI’s servers, and you reference previous turns by ID rather than re-sending them.

Both APIs give you access to the same underlying models and tool-calling mechanics. The difference is where the orchestration responsibility sits. The table below, first introduced in the Chat Completions API article, summarizes the trade-offs:

Feature	Chat Completions API	Responses API
Conversation state	Client-managed	Server-managed
History management	Manual — sent with every request	Automatic
Tool support	Manual function calling	Built-in tools (web search, code interpreter)
Streaming	Yes	Yes
Control	Full	Limited
Vendor coupling	Low	Higher
Best for	Custom agents, full control	Rapid prototyping, built-in tooling

The Chat Completions API is the right default when you want to control exactly what the model sees and when you need portability across providers. The Responses API reduces boilerplate and fits well when you want to prototype quickly or lean on OpenAI’s managed tooling. In this article we build the same conversational agent we built before — but with the Responses API driving state management.

First AI agent
#

The openai-go SDK covers both APIs under one package. The same client initialization you used for Chat Completions works here. To call the API, you need a secret key from platform.openai.com — navigate to the API Keys section, generate a key, and store it in an environment variable.

LLM and Go: Investigating OpenAI Chat Completions API

marko.milojevic@ompluscator.io (Marko Milojevic) — Fri, 06 Mar 2026 01:00:00 +0100

In the previous article I covered the fundamentals of the Chat Completions API: setting up a client, maintaining conversation history, and integrating tools. That was enough to build a working conversational agent. This article goes a level deeper — into the API parameters that shape what the model returns and how it thinks.

Two parameters stand out as particularly useful in production: response_format and reasoning_effort. The first gives you control over the structure of the model’s output. The second controls how much the model reasons before responding — which turns out to matter more than you might expect once you start caring about latency and cost.

Chat Completions API details
#

The Chat Completions API endpoint accepts a rich set of parameters. Most have sensible defaults and you will rarely touch them, but understanding what is available saves you from reaching for workarounds that already exist in the API. The table below covers the current non-deprecated parameters from the API reference:

Parameter	Type	Description
`model`	string	ID of the model to use
`messages`	array	Conversation history as an ordered list of messages
`response_format`	object	Output format: `text`, `json_object`, or `json_schema`
`reasoning_effort`	string	Reasoning intensity for reasoning models: `low`, `medium`, `high`
`temperature`	number	Sampling temperature from 0 to 2; higher values produce more random output
`top_p`	number	Alternative to temperature; nucleus sampling probability mass
`max_completion_tokens`	integer	Maximum tokens the model may generate in the response
`n`	integer	Number of completion choices to return
`stream`	boolean	Stream partial responses as server-sent events
`stop`	string/array	Sequences at which the API stops generating
`presence_penalty`	number	Penalises new tokens based on whether they appear in the text so far
`frequency_penalty`	number	Penalises new tokens based on their frequency in the text so far
`tools`	array	List of tools (functions) the model may call
`tool_choice`	string/object	Controls which tool the model calls
`seed`	integer	Seed for deterministic sampling
`user`	string	Unique identifier for the end user

In this article we focus on response_format and reasoning_effort — two parameters with a direct, visible impact on production systems.

Information extraction with response_format
#

The response_format parameter controls how the model structures its output. The default is plain text. Setting it to json_object tells the model to return valid JSON, but gives you no control over the schema. Setting it to json_schema goes further: you provide a JSON Schema document and the model guarantees its output will conform to it. OpenAI calls this structured output.

LLM and Go: OpenAI Integration via Chat Completions API

marko.milojevic@ompluscator.io (Marko Milojevic) — Thu, 05 Mar 2026 10:00:00 +0100

For most of my career, integrating external intelligence into an application meant calling a rules engine, training a custom classifier, or encoding business logic that someone had painfully documented in a spreadsheet. The idea that I could describe a task in plain language and have a model respond with genuine reasoning was not something I expected to become production-ready in my working life. Then GPT happened, and it changed what backend developers need to know.

This article is the first in a series on using LLMs in Go. We start with the OpenAI Chat Completions API — the stateless, request-based interface that gives you direct control over every aspect of the conversation. By the end, you will have a working conversational agent that can call external tools to answer questions it otherwise could not.

A short introduction to ChatGPT and OpenAI
#

The path to large language models runs through a decade of incremental progress in deep learning. Early models like word2vec and GloVe learned to embed words into dense vector spaces, capturing semantic relationships between terms. The transformer architecture, introduced by Google in 2017, changed the trajectory of the field — it processes sequences in parallel using attention mechanisms that capture long-range dependencies far more effectively than recurrent networks. This architectural shift made it practical to train models on orders of magnitude more data. GPT-1 in 2018 showed that large-scale unsupervised pre-training followed by fine-tuning could match or beat purpose-built models across a range of language tasks.

Understanding what these models actually do removes a lot of the mysticism around them. An LLM is, at its core, a next-token predictor. It takes a sequence of tokens as input and outputs a probability distribution over the vocabulary for the next token. The transformer’s attention mechanism allows every token in the input to attend to every other token, building a rich contextual representation before making that prediction. Training adjusts billions of parameters to minimise prediction error across enormous text corpora. What emerges is a model with broad world knowledge encoded in its weights — not because it was taught facts directly, but because predicting text well requires internalising the structure of the world that produced that text.

ChatGPT is OpenAI’s conversational product built on the GPT model series. What set it apart from raw GPT-3 was the addition of reinforcement learning from human feedback (RLHF) — a technique that fine-tunes the base model to follow instructions and produce responses that human raters judge as helpful and safe. When ChatGPT launched in late 2022, it became one of the fastest-adopted consumer products in history. For developers, the more relevant artefact is the API behind it — specifically the Chat Completions API, which gives programmatic access to the same models powering the product.

Go Tutorial: Iterators

marko.milojevic@ompluscator.io (Marko Milojevic) — Tue, 03 Mar 2026 10:00:00 +0100

Go 1.22 introduced range over functions, and Go 1.23 brought the iter package to go with it. Together they gave iterators a proper place in the language. Before that, iterating over custom data structures meant either returning slices upfront — loading everything into memory — or writing callback-based helpers that nobody could agree on naming. I have seen both approaches and neither felt right.

The core idea behind iterators is straightforward: instead of computing all values upfront and handing them back as a list, you compute each value on demand and yield it to the caller one at a time. The caller controls when to stop. This matters any time you are working with large or potentially infinite sequences.

This article walks through why iterators exist in Go, how the yield-based pattern works, what the iter package provides, and where the current limits of the feature sit.

Why do we need Iterators?
#

The simplest case for iteration is a slice of numbers. You range over it, print each value, move on.

func main() {
    numbers := []int{1, 2, 3, 4, 5}
    for _, i := range numbers {
        fmt.Println(i)
    }
}
// OUT:
// 1
// 2
// 3
// 4
// 5

That works fine until the collection gets large. If you need to generate a million numbers, you have to allocate memory for all of them before you can even start ranging.

func main() {
    n := 1_000_000
	numbers := make([]int, n)

	for i := range numbers {
		numbers[i] = i * 2
	}
	for _, i := range numbers {
		fmt.Println(i)
	}
}
// OUT:
// 1
// 2
// ...

You can always add a break once you hit your threshold, but the damage is already done — the entire slice was allocated upfront. In other cases, you might not even know how many items you will need. The for range loop can iterate for some time, until it reaches the breakpoint, depending on some value provided in the item. In such cases, the size of such a list must be not just too big, but absolutely unpredictable.

func main() {
    n := 1_000_000
	numbers := make([]int, n)

	for i := range numbers {
		numbers[i] = i * 2
	}
	for _, i := range numbers {
		fmt.Println(i)
		if i > 10 {
		    break
		}
	}
}
// OUT:
// 1
// 2
// 4
// 8
// 10
// 12

In a real application, the decision about when to stop often happens dynamically — driven by user input, a timeout, or a condition that evaluates to true before the fifth item. Allocating a million items and then breaking on the fifth is wasteful. This is exactly the problem iterators solve.

Golang Release 1.22: version

marko.milojevic@ompluscator.io (Marko Milojevic) — Sun, 02 Jun 2024 11:10:25 +0200

With the release of Go 1.22, the Go standard library introduced several new features. As you might have noticed in articles related to the previous release, here we mostly concentrate on the new exciting packages and features that they give us. This article will start this journey, by providing a deeper look into the implementation of the version package in Go.

Lang
#

The first function we are ready to examine is the Lang function. This function provides a cleaned, valid Go version as a string. In case it can’t determine the actual version, due to an invalid state of the string value, it will return an string as a result.

Lang function

func Lang(x string) string

As we can see the function signature above, function expects one argument, a string, that represents a Go version. An output should be also one value, a string, as a cleaned Go version.

Lang function examples

package main

import (
	"fmt"
	"go/version"
)

func main() {
	fmt.Println(version.Lang("go1.0"))      // go1
	fmt.Println(version.Lang("go1"))        // go1
	fmt.Println(version.Lang("go1.22.4"))   // go1.22
	fmt.Println(version.Lang("go1.22.3"))   // go1.22
	fmt.Println(version.Lang("go1.22.2"))   // go1.22
	fmt.Println(version.Lang("go1.22.rc1")) //
	fmt.Println(version.Lang("go1.22rc1"))  // go1.22
	fmt.Println(version.Lang("1.22"))       //
	fmt.Println(version.Lang("wrong"))      //
	fmt.Println(version.Lang(""))           //
}

In the example above, we can see how the Lang function adapt the Go version string. It removes all minor versions and appearance of “release candide” phrase, and present them in the end as an official Go versions that we experienced in the past (and we might experience in the future). In cases where we provided an invalid, or empty string, the ending result will be also an empty string, as the Lang function can’t find the actual version name.

One interesting point, not just for the Long function, but, as you will see, for all functions in this package, to consider some string as a valid Go version, it needs to have a prefix go.

IsValid
#

The next function we are examining is the IsValid function. This function checks a string with a potential Go version and returns a boolean result that tells us if the version is valid or not.

IsValid function

func IsValid(x string) bool

As we can see the function signature above, function expects one argument, a string, that represents a Go version. An output should be a bool value, which tells us if the Go version is valid or not.

Golang Release 1.21: slices - Part 2

marko.milojevic@ompluscator.io (Marko Milojevic) — Sun, 08 Oct 2023 16:10:25 +0200

With the release of Go 1.21, the Go standard library introduced several new features. While we’ve already discussed some of them in previous articles, in this episode, we’ll dive into more advanced enhancements. Naturally, we’ll focus on the new functions designed for sorting slices, which are part of the new slices package. This article will provide a deeper look into the implementation of these three new functions and touch on benchmarking as well.

Sort
#

The Sort function is the first one we’d like to explore. This implementation is built upon the enhanced Pattern-defeating Quicksort, positioning it as one of the best-known unstable sorting algorithms. Don’t worry; we will discuss this “instability” aspect in this article. But first, let’s take a look at the function’s signature:

Sort function

func Sort[S ~[]E, E cmp.Ordered](x S)

As we’ve seen in some other articles, nearly all improvements in the Go standard library are built upon generics, a feature introduced in Go version 1.18, almost three years ago. Similar to other functions, the Sort function also expects a slice of a generic type as an argument, where each item must adhere to the Ordered constraint. The function doesn’t return a new value but sorts the original slice in place. Below, you’ll find some basic examples:

Sort function examples

ints := []int{1, 2, 3, 5, 5, 7, 9}
slices.Sort(ints)
fmt.Println(ints)
// Output:
// 1 2 3 5 5 7 9

ints2 := []int{9, 7, 5, 5, 3, 2, 1}
slices.Sort(ints2)
fmt.Println(ints2)
// Output:
// 1 2 3 5 5 7 9

floats := []float64{9, 3, 5, 7, 1, 2, 5}
slices.Sort(floats)
fmt.Println(floats)
// Output:
// 1 2 3 5 5 7 9

strings := []string{"3", "9", "2", "5", "1", "7", "5"}
slices.Sort(strings)
fmt.Println(strings)
// Output:
// 1 2 3 5 5 7 9

In the example above, we can observe the result of the Sort method. All the outputs consist of sorted slices, arranged in ascending order. However, what makes this function particularly intriguing is its ability to handle various data types using a single function, distinguishing it from the implementations we already possess in the sort package. Now that we’ve examined the results, let’s proceed to compare the performance benchmarks with the existing package.

Benchmark
#

In this section, we aim to evaluate the performance of the new function by comparing it to the already existing sort package. Below, you’ll find the benchmark test results:

Golang Release 1.21: slices - Part 1

marko.milojevic@ompluscator.io (Marko Milojevic) — Fri, 06 Oct 2023 17:10:25 +0200

As part of the new Go release, several exciting changes have been introduced to the Go ecosystem. While we’ve explored some of these changes in other articles about the maps package and the cmp package, there’s much more to discover beyond these two packages.

In this article, we’ll focus on the first part of the slices package, specifically its new search functionality. Like many other updates and newly introduced packages, this one is also built upon the foundation of generics, which were introduced in Go 1.18.

BinarySearch and BinarySearchFunc
#

Let’s start by exploring the first pair of functions designed for efficiently searching a target value within sorted slices. In this context, we’re referring to the well-known Binary Search algorithm, which is renowned as one of the most significant algorithms and is frequently used in coding interviews. Below, you’ll find the signatures of both of these functions:

BinarySearch function

func BinarySearch[S ~[]E, E cmp.Ordered](x S, target E) (int, bool)

BinarySearchFunc function

func BinarySearchFunc[S ~[]E, E, T any](x S, target T, cmp func(E, T) int) (int, bool)

Looking at the signatures of both functions, we can identify some small differences between them, and these differences serve specific purposes. The first function, BinarySearch, expects two arguments. The first argument should be a slice of sorted items, and it must adhere to the Ordered constraint. When the items are ordered, the algorithm can efficiently compare them using the Compare function from the cmp package.

On the other hand, the second function, BinarySearchFunc, is more versatile. It allows searching within slices where the items don’t necessarily conform to the Ordered constraint. This flexibility is achieved by introducing a third argument, the comparison function. This function is responsible for comparing items and determining their order. It will be called by the BinarySearchFunc itself to make comparisons.

Both functions return two values. The first value is the index of the item within the slice, and the second is a boolean value indicating whether the item was found in the slice or not. Let’s explore some examples below:

BinarySearch examples

fmt.Println(slices.BinarySearch([]int{1, 3, 5, 6, 7}, 5))
// Output:
// 2 true
fmt.Println(slices.BinarySearch([]int{1, 3, 5, 6, 7}, 9))
// Output:
// 5 false
fmt.Println(slices.BinarySearch([]int{1, 3, 5, 6, 7}, -5))
// Output:
// 0 false

fmt.Println(slices.BinarySearch([]string{"1", "3", "5", "6", "7"}, "5"))
// Output:
// 2 true
fmt.Println(slices.BinarySearch([]string{"1", "3", "5", "6", "7", "8"}, "9"))
// Output:
// 6 false
fmt.Println(slices.BinarySearch([]string{"1", "3", "5", "6", "7"}, "4"))
// Output:
// 2 false

Take a close look at the results returned by the BinarySearch function, especially when the item doesn’t exist in the slice. In our examples, we encountered four such cases where the function returned 0, 2, 5, and 6. When the requested item isn’t present in the slice, the function indicates where it should be positioned if it were to be added to the slice. Since the slice is sorted, it’s possible to determine the appropriate position for the item within the slice.

Golang Release 1.21: cmp

marko.milojevic@ompluscator.io (Marko Milojevic) — Fri, 22 Sep 2023 17:46:25 +0200

As the new release of Go came this summer, many of us started to look for the improvements inside its ecosystem. Many new features were introduced, including updates to the tool command to support backward and forward compatibility. New packages appeared inside the Standard Library, including maps and slices. In this article we are covering improvements introduced with the new cmp package.

The new package offers three new functions. All of them rely on Generics, a feature introduced in Go version 1.18, which has opened up possibilities for many new features. The cmp package introduces new functions for comparing values of Ordered constraint.

Let’s dive into each of them.

Ordered constraint and Compare function
#

The constraint Ordered encompasses all types that support comparison operators for values, specifically, <, <=, >= and >. This includes all numeric types in Go, as well as strings.

Ordered Constraint

type Ordered interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 |
		~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr |
		~float32 | ~float64 |
		~string
}

Once we understand what the Ordered constraint includes, we can focus on the first function from the cmp package, which is the Compare function. Below, you can find its signature:

Compare Function

// Compare returns
//
//	-1 if x is less than y,
//	 0 if x equals y,
//	+1 if x is greater than y.
// ...
func Compare[T Ordered](x, y T) int

The signature, along with the function description, makes it much easier to understand. The Compare function expects two arguments of the same type, compares their values, and returns a result that represents the comparison status:

-1 if the first argument is less than the second.
0 if the arguments’ values are equal.
1 if the first argument is greater than the second.

Let’s prove such claim:

Compare numerals

fmt.Println(cmp.Compare(1, 2))
// Output:
// -1
fmt.Println(cmp.Compare(1, 1))
// Output:
// 0
fmt.Println(cmp.Compare(2, 1))
// Output:
// 1

Compare strings

fmt.Println(cmp.Compare("abc", "def"))
// Output:
// -1
fmt.Println(cmp.Compare("qwe", "qwe"))
// Output:
// 0
fmt.Println(cmp.Compare("abcde", "abcc"))
// Output:
// 1

Above, we can see practical examples of the Compare function for both numerals and strings. Indeed, the return values can only belong to the set of numbers {-1, 0, 1}, as defined in the description.

Function Less
#

In addition to the function Compare, we got another, similar function Less. Although it’s rather easy to understand what is used for, let’s check its signature:

Golang Release 1.21: maps

marko.milojevic@ompluscator.io (Marko Milojevic) — Thu, 21 Sep 2023 10:12:25 +0200

Not too long ago, we witnessed a new release of our favorite programming language. The Go team didn’t disappoint us once again. They introduced numerous new features, including updates to the tool command to support backward and forward compatibility. As always, the standard library has received new updates, and the first one we’ll explore in this article is the new maps package.

The new package offers only five new functions (two additional ones were removed from the package: Values and Keys), but they provide significant value. All of them rely on Generics, a feature introduced in Go version 1.18, which has opened up possibilities for many new features. The map package clearly provides new tools for Go maps. In this particular case, it introduces new functions for checking map equality, deleting items from maps, copying items into maps, and cloning maps.

Let’s dive into each of them.

Equal and EqualFunc
#

First, let’s examine the pair of functions used to check map equality: Equal and EqualFunc. The first one is a straightforward function that checks the equality of two provided maps as function arguments. The second one allows you to pass an additional argument that defines how you plan to examine the equality of values inside the maps. Here are their signatures:

Function Equal

func Equal[M1, M2 ~map[K]V, K, V comparable](m1 M1, m2 M2) bool

Function EqualFunc

func EqualFunc[M1 ~map[K]V1, M2 ~map[K]V2, K comparable, V1, V2 any](m1 M1, m2 M2, eq func(V1, V2) bool) bool

The Equal function is easier to understand. It simply defines two generic types, M1 and M2, which represent maps of two other generic types, K and V. Obviously, K is for map keys, and it allows any comparable value. The second type is V, representing map values, and it also allows being of a comparable type.

The EqualFunc function is slightly more complicated. First, it doesn’t assume that the values in the maps are of the same type, nor do they have to be comparable. For that reason, it introduces an additional argument, which is an equality function for the values in the maps. This way, we can compare two maps that have the same keys but not the same values, and we can define the logic for comparing if they are equal.

Simple usage of Equal function

first := map[string]string{
    "key1": "value1",
}
second := map[string]string{
    "key1": "value1",
}
fmt.Println(maps.Equal(first, second))
// Output:
// true

third := map[string]string{
    "key1": "value1",
}
fourth := map[string]string{
    "key1": "wrong",
}
fmt.Println(maps.Equal(third, fourth))
// Output:
// false

In the example above, there are no surprises. We use four maps to test the Equal function. In the first case, two maps are equal, but in the second case, their values are not the same. The following example is also easy.

Golang Tutorial: Contract Testing with PACT

marko.milojevic@ompluscator.io (Marko Milojevic) — Wed, 20 Sep 2023 18:11:01 +0200

My favorite part of software development is writing tests, whether they are unit tests or integration tests. I enjoy the process immensely. There’s a certain satisfaction in creating a test case that uncovers a function’s failure. It brings me joy to discover a bug during development, knowing that I’ve fixed it before anyone encounters it in a test environment or, worse, in production. Sometimes, I stay up late just to write more tests; it’s like a hobby. I even spent around 30 minutes on my wedding day writing unit tests for my personal project, but don’t tell my wife!

The only thing that used to bother me was dealing with integration issues between multiple Microservices. How could I ensure that two Microservices, each with specific versions, wouldn’t face integration problems? How could I be certain that a new version of a Microservice didn’t break its API interface, rendering it unusable for others? This information was crucial to have before launching extensive scenarios in our end-to-end testing pipeline. Otherwise, we’d end up waiting for an hour just to receive feedback that we’d broken the JSON schema.

Then, one day in the office, I heard a rumor that we were planning to use Contract Testing. I quickly checked the first article I found, and I was amazed. It was a breakthrough.

Contract Testing
#

There are many excellent articles about Contract testing, but the one I like the most is from Pactflow. Contract testing ensures that two parties can communicate effectively by testing them in isolation to verify if both sides support the messages they exchange. One party, known as the Consumer, captures the communication with the other party, referred to as the Provider, and creates the Contract. This Contract serves as a specification for the expected requests from the Consumer and the responses from the Provider. Application code automatically generates Contracts, typically during the unit testing phase. Automatic creation ensures that each Contract accurately reflects the latest state of affairs.

Contract testing

After the Consumer publishes the Contract, the Provider can use it. In its code, likely within unit tests, the Provider conducts Contract verification and publishes the results. In both phases of Contract testing, we work solely on one side, without any actual interaction with the other party. Essentially, we are ensuring that both parties can communicate with each other within their separate pipelines. As a result, the entire process is asynchronous and independent. If either of these two phases fails, both the Consumer and Provider must collaborate to resolve integration issues. In some cases, the Consumer may need to adapt its integrational code, while in others, the Provider may need to adjust its API.

Golang Tutorial: Generics with Gorm

marko.milojevic@ompluscator.io (Marko Milojevic) — Wed, 20 Sep 2023 14:15:01 +0200

After months and years of talking, trying things out, and testing, we’ve finally reached a big moment in our favorite programming language. The new Golang version, 1.18, is here. We knew it would bring significant changes to Go’s codebase, even before Generics was officially released. For a long time, when we wanted to make our code more general and abstract, we used code generators in Go. Learning what the “Go way” of doing things was challenging for many of us, but it also led to many breakthroughs. It was worth the effort. Now, there are new possibilities on the horizon.

Many new packages have emerged, giving us ideas on how we can improve the Go ecosystem with reusable code that makes life easier for all of us. This inspiration led me to create a small proof of concept using the Gorm library. Now, let’s take a look at it.

Source code
#

When I wrote this article, it relied on a GitHub Repository. The code served as a Go library proof of concept, with my intention to continue working on it. However, it was not yet suitable for production use, and I had no plans to offer production support at that time.

You can find the current features by following the link, and below, there is a smaller sample snippet.

Example Usage

package main

import (
  	"github.com/ompluscator/gorm-generics"
	// some imports
)

// Product is a domain entity
type Product struct {
	// some fields
}

// ProductGorm is DTO used to map Product entity to database
type ProductGorm struct {
	// some fields
}

// ToEntity respects the gorm_generics.GormModel interface
func (g ProductGorm) ToEntity() Product {
	return Product{
		// some fields
	}
}

// FromEntity respects the gorm_generics.GormModel interface
func (g ProductGorm) FromEntity(product Product) interface{} {
	return ProductGorm{
		// some fields
	}
}

func main() {
	db, err := gorm.Open(/* DB connection string */)
	// handle error

	err = db.AutoMigrate(ProductGorm{})
	// handle error

	// initialize a new Repository with by providing
	// GORM model and Entity as type
	repository := gorm_generics.NewRepository[ProductGorm, Product](db)

	ctx := context.Background()

	// create new Entity
	product := Product{
		// some fields
	}
	
	// send new Entity to Repository for storing
	err = repository.Insert(ctx, &product)
	// handle error

	fmt.Println(product)
	// Out:
	// {1 product1 100 true}

	single, err := repository.FindByID(ctx, product.ID)
	// handle error
	
	fmt.Println(single)
	// Out:
	// {1 product1 100 true}
}

Why have I picked ORM for PoC?
#

Coming from a background in software development with traditional object-oriented programming languages like Java, C#, and PHP, one of the first things I did was search Google for a suitable ORM for Golang. Please forgive my inexperience at the time, but that’s what I was expecting. It’s not that I can’t work without an ORM. It’s just that I don’t particularly like how raw MySQL queries appear in the code. All that string concatenation looks messy to me. On the other hand, I always prefer to dive right into writing business logic, with minimal time spent thinking about the underlying data storage. Sometimes, during the implementation, I change my mind and switch to different types of storage. That’s where ORMs come in handy.

Golang Tutorial: Unit Testing with Mocking

marko.milojevic@ompluscator.io (Marko Milojevic) — Wed, 20 Sep 2023 10:01:01 +0200

Unit testing has always been my thing, almost like a hobby. There was a time when I was obsessed with it, and I made sure that all my projects had at least 90% unit test coverage. You can probably imagine how much time it can take to make such a significant change in the codebase. However, the result was worth it because I rarely encountered bugs related to business logic. Most of the issues were related to integration problems with other services or databases.

Adding new business rules was a breeze because there were already tests in place to cover all the cases from before. The key was to ensure that these tests remained successful in the end. Sometimes, I didn’t even need to check the entire running service; having the new and old unit tests pass was sufficient.

Once, while working on a personal project, I had to write unit tests to cover numerous Go structs and functions—more than 100 in total. It consumed my entire weekend, and late on a Sunday night, before heading out on a business trip the next day, I set an alarm clock to wake me up. I had hardly slept that night; it was one of those restless nights when you dream but are also aware of yourself and your surroundings. My brain was active the entire time, and in my dreams, I kept writing unit tests for my alarm clock. To my surprise, each time I executed a unit test in my dream, the alarm rang. It continued ringing throughout the night.

And yes, I almost forgot to mention, for two years, we had zero bugs in production. The application continued to fetch all the data and send all the emails every Monday. I don’t even remember my Gitlab password anymore.

Unit Testing and Mocking (in general)
#

In Martin Fowler’s article, we can identify two types of unit tests:

Sociable unit tests, where we test a unit while it relies on other objects in conjunction with it. For example, if we want to test the UserController, we would test it along with the UserRepository, which communicates with the database.
Solitary unit tests, where we test a unit in complete isolation. In this scenario, we would test the UserController, which interacts with a controlled, mocked UserRepository. With mocking, we can specify how it behaves without involving a database.

Golang Tutorial: Generics

marko.milojevic@ompluscator.io (Marko Milojevic) — Tue, 19 Sep 2023 10:10:01 +0200

How often do we encounter significant changes in our preferred programming language? Some languages undergo frequent updates, while others remain traditional and stable. Go falls into the latter category, known for its consistency. “This is not the Go way!” is a phrase that often comes to mind. Most Go releases have focused on refining its existing principles. However, a major shift is on the horizon. The Go team has announced that Generics in Go are becoming a reality, moving beyond mere discussion and into implementation.

Brace yourselves, a revolution is coming.

What are Generics?
#

Generics allow us to parameterize types when defining interfaces, functions, and structs.

Generics is not a new concept. It has been used since the first version of Ada, through templates in C++, to its modern implementations in Java and C#. To illustrate without delving into complex definitions, let’s examine a practical example. Instead of having multiple Max or Min functions like this:

Without Generics

func MaxInt(a, b int) int {
	// some code
}

func MaxFloat64(a, b float64) float64 {
	// some code
}

func MaxByte(a, b byte) byte {
	// some code
}

we can declare now only one method, like this:

With Generics

func Max[T constraints.Ordered](a, b T) T {
	// some code
}

Wait, what just happened? Instead of defining a method for each type in Go, we utilized Generics. We used a generic type, parameter T, as an argument for the method. With this minor adjustment, we can support all orderable types. The parameter T can represent any type that satisfies the Ordered constraint (we will discuss constraints later). Initially, we need to specify what kind of type T is. Next, we determine where we want to use this parameterized type. In this case, we’ve specified that both input arguments and the output should be of type T. If we execute the method by defining T as an integer, then everything here will be an integer:

Execute Generic Function

func main() {
	fmt.Println(Max[int](1, 2))
}
//
// this code behaves exactly like method:
// Max(a, b int) int

And it doesn’t stop there. We can provide as many parameterized types as we need and assign them to different input and output arguments as desired:

Execute some complex Generic Function

func Do[R any, S any, T any](a R, b S) T {
	// some code
}

func main() {
	fmt.Println(Do[int, uint, float64](1, 2))
}
//
// this code behaves exactly like method:
// Do(a int, b uint) float64

Here we have three parameters: R, S, and T. As we can see from the any constraint (which behaves like interface{}), those types can be, well, anything. So, up to this point, we should have a clear understanding of what generics are and how we use them in Go. Let’s now focus on more exciting consequences.

Practical SOLID in Golang: Dependency Inversion Principle

marko.milojevic@ompluscator.io (Marko Milojevic) — Mon, 18 Sep 2023 19:36:01 +0200

Learning a new programming language is often a straightforward process. I often hear: “The first programming language you learn in a year. The second one in a month. The third one in a week, and then each next one in a day.” Saying that is an exaggeration, but it is not too distant from the truth in some cases. For example, jumping to a language relatively similar to the previous one, like Java and C#, can be a straightforward process. But sometimes, switching is tricky, even when we switch from one Object-Oriented language to another. Many features influence such transitions, like strong or weak types, if a language has interfaces, abstract classes, or classes at all. Some of those difficulties we experience immediately after switching, and we adopt a new approach. But some issues we experience later, during unit testing, for example. And then, we learn why The Dependency Inversion Principle is essential, especially in Go.

When we do not respect The Dependency Inversion
#

High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions.

Above is the definition of DIP as presented by Uncle Bob in his paper. There are also more details inside his blog. So, how can we understand this, especially in the context of Go? First, we should accept Abstraction as an object-oriented programming concept. We use this concept to expose essential behaviors and hide the details of their implementation.

Second, what are high and low-level modules? In the context of Go, high-level modules are software components used at the top of the application, such as code used for presentation. It can also be code close to the top level, like code for business logic or some use-case components. It is essential to understand it as a layer that provides real business value to our application. On the other hand, low-level software components are mostly small code pieces that support the higher level. They hide technical details about different infrastructural integrations. For example, this could be a struct that contains the logic for retrieving data from the database, sending an SQS message, fetching a value from Redis, or sending an HTTP request to an external API. So, what does it look like when we break The Dependency Inversion Principle, and our high-level component depends on one low-level component?

Practical SOLID in Golang: Interface Segregation Principle

marko.milojevic@ompluscator.io (Marko Milojevic) — Mon, 18 Sep 2023 19:11:01 +0200

When beginners embark on their programming journey, the initial focus is typically on algorithms and adapting to a new way of thinking. After some time, they delve into Object-Oriented Programming (OOP). If this transition is delayed, it can be challenging to shift from a functional programming mindset. However, eventually, they embrace the use of objects and incorporate them into their code where necessary, sometimes even where they’re not needed. As they learn about abstractions and strive to make their code more reusable, they may overgeneralize, resulting in abstractions applied everywhere, which can hinder future development. At some point, they come to realize the importance of setting boundaries for excessive generalization. Fortunately, The Interface Segregation Principle has already provided a guideline for this, representing the “I” in the word SOLID.

When we do not respect The Interface Segregation
#

Maintain small interfaces to prevent users from relying on unnecessary features.

Uncle Bob introduced this principle, and you can find more details about it on his blog. This principle clearly states its requirement, perhaps better than any other SOLID principle. Its straightforward advice to keep interfaces as small as possible should not be interpreted as merely advocating one-method interfaces. Instead, we should consider the cohesion of features that an interface encompasses.

Let’s analyze the code below:

User interface

type User interface {
	AddToShoppingCart(product Product)
	IsLoggedIn() bool
	Pay(money Money) error
	HasPremium() bool
	HasDiscountFor(product Product) bool
	//
	// some additional methods
	//
}

Let’s assume we want to create an application for shopping. One approach is to define an interface User, as demonstrated in the code example. This interface includes various features that a user can have. On our platform, a User can add a Product to the ShoppingCart, make a purchase, and receive discounts on specific Products. However, the challenge is that only specific types of Users can perform all of these actions.

Guest struct

type Guest struct {
	cart ShoppingCart
	//
	// some additional fields
	//
}

func (g *Guest) AddToShoppingCart(product Product) {
	g.cart.Add(product)
}

func (g *Guest) IsLoggedIn() bool {
	return false
}

func (g *Guest) Pay(Money) error {
	return errors.New("user is not logged in")
}

func (g *Guest) HasPremium() bool {
	return false
}

func (g *Guest) HasDiscountFor(Product) bool {
	return false
}

We have implemented this interface with three structs. The first one is the Guest struct, representing a user who is not logged in but can still add a Product to the ShoppingCart. The second implementation is the NormalCustomer, which can do everything a Guest can, plus make a purchase. The third implementation is the PremiumCustomer, which can use all features of our system.

Practical SOLID in Golang: Liskov Substitution Principle

marko.milojevic@ompluscator.io (Marko Milojevic) — Mon, 18 Sep 2023 18:38:01 +0200

I’m not really a fan of reading. Often, when I do read, I find myself losing track of the text’s topic for the past few minutes. Many times, I’ll go through an entire chapter without really grasping what it was all about in the end. It can be frustrating when I’m trying to focus on the content, but I keep realizing I need to backtrack. That’s when I turn to various types of media to learn about a topic. The first time I encountered this reading issue was with the SOLID principle, specifically the Liskov Substitution Principle. Its definition was (and still is) too complicated for my taste, especially in its formal format. As you can guess, LSP represents the letter “L” in the word SOLID. It’s not difficult to understand, although a less mathematical definition would be appreciated.

When we do not respect The Liskov Substitution
#

The first time we encountered this principle was in 1988, thanks to Barbara Liskov. Later, Uncle Bob shared his perspective on this topic in a paper and eventually included it as one of the SOLID principles. Let’s take a look at what it says:

Let Φ(x) be a property provable about objects x of type T. Then Φ(y) should be true for objects y of type S where S is a subtype of T.

Well, good luck with that definition.

No, seriously, what kind of definition is this? Even as I write this article, I’m still struggling to fully grasp this definition, despite my fundamental understanding of LSP. Let’s give it another shot:

If S is a subtype of T, then objects of type T in a program may be replaced with objects of type S without altering any of the desirable properties of that program.

Okay, this is a bit clearer now. If ObjectA is an instance of ClassA, and ObjectB is an instance of ClassB, and ClassB is a subtype of ClassA – if we use ObjectB instead of ObjectA somewhere in the code, the application’s functionality must not break. We’re talking about classes and inheritance here, two concepts that aren’t prominent in Go. However, we can still apply this principle using interfaces and polymorphism.

Wrong implementation of Update method

type User struct {
	ID uuid.UUID
	//
	// some fields
	//
}

type UserRepository interface {
	Update(ctx context.Context, user User) error
}

type DBUserRepository struct {
	db *gorm.DB
}

func (r *DBUserRepository) Update(ctx context.Context, user User) error {
	return r.db.WithContext(ctx).Delete(user).Error
}

In this code example, we can see one that’s quite absurd and far from best practices. Instead of updating the User in the database, as the Update method claims, it actually deletes it. But that’s precisely the point here. We have an interface, UserRepository, followed by a struct, DBUserRepository. While this struct technically implements the interface, it completely diverges from what the interface is supposed to do. In fact, it breaks the functionality of the interface rather than fulfilling its expectations. This highlights the essence of the Liskov Substitution Principle (LSP) in Go: a struct must not violate the intended behavior of the interface.

Practical SOLID in Golang: Open/Closed Principle

marko.milojevic@ompluscator.io (Marko Milojevic) — Mon, 18 Sep 2023 18:02:01 +0200

Many different approaches and principles can lead to long-term improvements in our code. Some of them are well-known in the software development community, while others remain somewhat under the radar. In my opinion, this is the case with The Open/Closed Principle, represented by the letter O in the word SOLID. In my experience, only those genuinely interested in SOLID principles tend to understand what this principle means. We may have applied this principle without even realizing it in some instances, such as when working with the Strategy pattern. However, the Strategy pattern is just one application of the Open/Closed Principle. In this article, we will delve into the full purpose of this principle, with all examples provided in Go.

When we do not respect the Open/Closed Principle
#

You should be able to extend the behavior of a system without having to modify that system.

The requirement for the Open/Closed Principle, as seen above, was provided by Uncle Bob in his blog. I prefer this way of defining The Open/Closed Principle because it highlights its full brilliance. At first glance, it may seem like an absurd requirement. Seriously, how can we extend something without modifying it? I mean, is it possible to change something without changing it? By examining the code example below, we can see what it means for certain structures not to adhere to this principle and the potential consequences.

The bad Authentication Service

type AuthenticationService struct {
	//
	// some fields
	//
}

func (s *AuthenticationService) Authenticate(ctx *gin.Context) (*User, error) {
	switch ctx.GetString("authType") {
	case "bearer":
		return c.authenticateWithBearerToken(ctx.Request.Header)
	case "basic":
		return c.authenticateWithBasicAuth(ctx.Request.Header)
	case "applicationKey":
		return c.authenticateWithApplicationKey(ctx.Query("applicationKey"))
	}

	return nil, errors.New("unrecognized authentication type")
}

func (s *AuthenticationService) authenticateWithApplicationKey(key string) (*User, error) {
	//
	// authenticate User from Application Key
	//
}

func (s *AuthenticationService) authenticateWithBasicAuth(h http.Header) (*User, error) {
	//
	// authenticate User from Basic Auth
	//
}

func (s *AuthenticationService) authenticateWithBearerToken(h http.Header) (*User, error) {
	//
	// validate JWT token from the request header
	//
}

The example presents a single struct, AuthenticationService. Its purpose is to authenticate a User from the web application’s Context, supported by the Gin package. Here, we have the main method, Authenticate, which checks for specific authentication type associated with the data within the Context. How User is retrieved from the Context may vary based on whether the User uses a bearer JWT token, basic authentication, or an application key.

Practical SOLID in Golang: Single Responsibility Principle

marko.milojevic@ompluscator.io (Marko Milojevic) — Mon, 18 Sep 2023 15:23:01 +0200

There aren’t too many opportunities for a breakthrough in software development. They usually arise from either rewiring our logic after initial misunderstandings or filling in gaps in our knowledge. I appreciate that feeling of deeper understanding. It can happen during a coding session, while reading a book or an online article, or even while sitting on a bus. An internal voice follows, saying, “Ah, yes, that’s how it works.”

Suddenly, all past mistakes seem to have a logical reason, and future requirements take shape. I experienced such a breakthrough with the SOLID principles, which were first introduced in a document by Uncle Bob and later expounded upon in his book, “Clean Architecture.” In this article, I intend to embark on a journey through all the SOLID principles, providing examples in Go. The first principle on the list, representing the letter ‘S’ in SOLID, is the Single Responsibility Principle.

When we do not respect Single Responsibility
#

The Single Responsibility Principle (SRP) asserts that each software module should serve a single, specific purpose that could lead to change.

The sentence above comes directly from Uncle Bob himself. Initially, its application was linked to modules and the practice of segregating responsibilities based on the organization’s daily tasks. Nowadays, SRP has a broader scope, influencing various aspects of software development. We can apply its principles to classes, functions, modules, and naturally, in Go, even to structs.

Some Frankenstein of EmailService

type EmailService struct {
	db           *gorm.DB
	smtpHost     string
	smtpPassword string
	smtpPort     int
}

func NewEmailService(db *gorm.DB, smtpHost string, smtpPassword string, smtpPort int) *EmailService {
	return &EmailService{
		db:           db,
		smtpHost:     smtpHost,
		smtpPassword: smtpPassword,
		smtpPort:     smtpPort,
	}
}

func (s *EmailService) Send(from string, to string, subject string, message string) error {
	email := EmailGorm{
		From:    from,
		To:      to,
		Subject: subject,
		Message: message,
	}

	err := s.db.Create(&email).Error
	if err != nil {
		log.Println(err)
		return err
	}
	
	auth := smtp.PlainAuth("", from, s.smtpPassword, s.smtpHost)
	
	server := fmt.Sprintf("%s:%d", s.smtpHost, s.smtpPort)
	
	err = smtp.SendMail(server, auth, from, []string{to}, []byte(message))
	if err != nil {
		log.Println(err)
		return err
	}

	return nil
}

Let’s analyze the code block above. In this code, we have a struct called EmailService, which contains only one method, Send. This service is intended for sending emails. Although it may seem okay at first glance, upon closer inspection, we realize that this code violates the Single Responsibility Principle (SRP) in several ways.

Practical DDD in Golang: Specification

marko.milojevic@ompluscator.io (Marko Milojevic) — Mon, 18 Sep 2023 11:47:01 +0200

There are not many code structures that bring me joy whenever I need to write them. The first time I implemented such code was with a lightweight ORM in Go, back when we didn’t have one. However, I used ORM for many years, and at some point, when you rely on ORM, using QueryBuilder becomes inevitable. Here, you may notice terms like “predicates”, and that’s where we can find the Specification pattern. It’s hard to find any pattern we use as Specification, yet we do not hear its name. I think the only thing harder is to write an application without using this pattern. The Specification has many applications. We can use it for querying, creation, or validation. We may provide a unique code that can do all this work or provide different implementations for different use cases.

For Validation
#

The first use case for the Specification pattern is validation. Typically, we validate data in forms, but this is at the presentation level. Sometimes, we perform validation during creation, such as for Value Objects. In the context of the domain layer, we can use Specifications to validate the states of Entities and filter them from a collection. So, validation at the domain layer has a broader meaning than for user inputs.

Base Product Specification

type Product struct {
	ID            uuid.UUID
	Material      MaterialType
	IsDeliverable bool
	Quantity      int
}

type ProductSpecification interface {
	IsValid(product Product) bool
}

A simple Product Specification

type HasAtLeast struct {
	pieces int
}

func NewHasAtLeast(pieces int) ProductSpecification {
	return HasAtLeast{
		pieces: pieces,
	}
}

func (h HasAtLeast) IsValid(product Product) bool {
	return product.Quantity >= h.pieces
}

In the example above, there is an interface called ProductSpecification. It defines only one method, IsValid, which expects instances of Product and returns a boolean value as a result if the Product passes validation rules. A simple implementation of this interface is HasAtLeast, which verifies the minimum quantity of the Product.

Function as a Product Specification

type FunctionSpecification func(product Product) bool

func (fs FunctionSpecification) IsValid(product Product) bool {
	return fs(product)
}

func IsPlastic(product Product) bool {
	return product.Material == Plastic
}

func IsDeliverable(product Product) bool {
	return product.IsDeliverable
}

More interesting validators are two functions, IsPlastic and IsDeliverable. We can wrap those functions with a specific type, FunctionSpecification. This type embeds a function with the same signature as the two mentioned. Besides that, it provides methods that respect the ProductSpecification interface. This example is a nice feature of Go, where we can define a function as a type and attach a method to it so that it can implicitly implement some interface. In this case, it exposes the method IsValid, which executes the embedded function.

Practical DDD in Golang: Repository

marko.milojevic@ompluscator.io (Marko Milojevic) — Mon, 18 Sep 2023 11:20:01 +0200

Today, it is hard to imagine writing an application without accessing some form of storage at runtime. This includes not only writing application code but also deployment scripts, which often need to access configuration files, which are also a type of storage in a sense. When developing applications to solve real-world business problems, connecting to databases, external APIs, caching systems, or other forms of storage is practically unavoidable. It’s no surprise, then, that Domain-Driven Design (DDD) includes patterns like the Repository pattern to address these needs. While DDD didn’t invent the Repository pattern, it added more clarity and context to its usage.

The Anti-Corruption Layer
#

Domain-Driven Design (DDD) is a principle that can be applied to various aspects of software development and in different parts of a software system. However, its primary focus is on the domain layer, which is where our core business logic resides. While the Repository pattern is responsible for handling technical details related to external data storage and doesn’t inherently belong to the business logic, there are situations where we need to access the Repository from within the domain layer.

Since the domain layer is typically isolated from other layers and doesn’t directly communicate with them, we define the Repository within the domain layer, but we define it as an interface. This interface serves as an abstraction that allows us to interact with external data storage without tightly coupling the domain layer to specific technical details or implementations.

A Simple Repository example

type Customer struct {
	ID uuid.UUID
	//
	// some fields
	//
}

type Customers []Customer

type CustomerRepository interface {
	GetCustomer(ctx context.Context, ID uuid.UUID) (*Customer, error)
	SearchCustomers(ctx context.Context, specification CustomerSpecification) (Customers, int, error)
	SaveCustomer(ctx context.Context, customer Customer) (*Customer, error)
	UpdateCustomer(ctx context.Context, customer Customer) (*Customer, error)
	DeleteCustomer(ctx context.Context, ID uuid.UUID) (*Customer, error)
}

The interface that defines method signatures within our domain layer is referred to as a “Contract.” In the example provided, we have a simple Contract interface that specifies CRUD (Create, Read, Update, Delete) methods. By defining the Repository as this interface, we can use it throughout the domain layer. The Repository interface always expects and returns our Entities, such as Customer and Customers (collections with specific methods attached to them, as defined in Go).

It’s important to note that the Entity Customer doesn’t contain any information about the underlying storage type, such as Go tags for defining JSON structures, Gorm columns, or anything of that sort. This kind of low-level storage configuration is typically handled in the infrastructure layer.

Practical DDD in Golang: Factory

marko.milojevic@ompluscator.io (Marko Milojevic) — Mon, 18 Sep 2023 10:52:01 +0200

When I wrote the title of this article, I was trying to remember the first design pattern I had learned from “The Gang of Four”. I think it was one of the following: Factory Method, Singleton, or Decorator. I am sure that other software engineers have a similar story. When they started learning design patterns, either Factory Method or Abstract Factory was one of the first three they encountered. Today, any derivative of the Factory pattern is essential in Domain-Driven Design, and its purpose remains the same, even after many decades.

Complex Creations
#

We use the Factory pattern for any complex object creation or to isolate the creation process from other business logic. Having a dedicated place in the code for such scenarios makes it much easier to test separately. In most cases, when I provide a Factory, it is part of the domain layer, allowing me to use it throughout the application. Below, you can see a simple example of a Factory.

Simple example

type Loan struct {
	ID uuid.UUID
	//
	// some fields
	//
}

type LoanFactory interface {
	CreateShortTermLoan(specification LoanSpecification) Loan
	CreateLongTermLoan(specification LoanSpecification) Loan
}

The Factory pattern goes hand-in-hand with the Specification pattern. Here, we have a small example with LoanFactory, LoanSpecification, and Loan. LoanFactory represents the Factory pattern in DDD, and more specifically, the Factory Method. It is responsible for creating and returning new instances of Loan that can vary depending on the payment period.

Variations
#

As mentioned, we can implement the Factory pattern in many different ways. The most common form, at least for me, is the Factory Method. In this case, we provide some creational methods to our Factory struct.

Loan Entity

const (
	LongTerm = iota
	ShortTerm
)

type Loan struct {
	ID            	      uuid.UUID
	Type          	      int
	BankAccountID 	      uuid.UUID
	Amount        	      Money
	RequiredLifeInsurance bool
}

Loan Factory

type LoanFactory struct{}

func (f *LoanFactory) CreateShortTermLoan(bankAccountID uuid.UUID, amount Money) Loan {
	return Loan{
		Type:          ShortTerm,
		BankAccountID: bankAccountID,
		Amount:        amount,
	}
}

func (f *LoanFactory) CreateLongTermLoan(bankAccountID uuid.UUID, amount Money) Loan {
	return Loan{
		Type:          	       LongTerm,
		BankAccountID: 	       bankAccountID,
		Amount:        	       amount,
		RequiredLifeInsurance: true,
	}
}

In the code snippet from above, LoanFactory is now a concrete implementation of the Factory Method. It provides two methods for creating instances of the Loan Entity. In this case, we create the same object, but it can have differences depending on whether the loan is long-term or short-term. The distinctions between the two cases can be even more complex, and each additional complexity is a new reason for the existence of this pattern.

Practical DDD in Golang: Aggregate

marko.milojevic@ompluscator.io (Marko Milojevic) — Mon, 18 Sep 2023 10:10:01 +0200

I have spent years understanding and practicing the DDD approach. Most of the principles were easy to understand and implement in the code. However, there was one that particularly caught my attention. I must say that the Aggregate pattern is the most critical one in DDD, and perhaps the entire Tactical Domain-Driven Design doesn’t make sense without it. It serves to bind business logic together. While reading, you might think that the Aggregate resembles a cluster of patterns, but that is a misconception. The Aggregate is the central point of the domain layer. Without it, there is no reason to use DDD.

Business Invariants
#

In the real business world, some rules are flexible. For example, when you take a loan from a bank, you need to pay some interest over time. The overall amount of interest is adjustable and depends on your invested capital and the period you will spend to pay the debt. In some cases, the bank may grant you a grace period, offer you a better overall credit deal due to your loyalty in the past, provide you with a once-in-a-lifetime offer, or require you to place a mortgage on a house.

All of these flexible rules from the business world are implemented in DDD using the Policy pattern. They depend on many specific cases and, as a result, require more complex code structures. In the real business world, there are also some immutable rules. Regardless of what we try, we cannot change these rules or their application in our business. These rules are known as Business Invariants. For example, nobody should be allowed to delete a customer account in a bank if any of the bank accounts associated with the customer has money or is in debt. In many banks, one customer may have multiple bank accounts with the same currency. However, in some of them, the customer is not allowed to have any foreign currency accounts or multiple accounts with the same currency. When such business rules exist, they become Business Invariants. They are present from the moment we create the object until the moment we delete it. Breaking them means breaking the whole purpose of the application.

Currency Entity

type Currency struct {
	id uuid.UUID
	//
	// some fields
	//
}

func (c Currency) Equal(other Currency) bool {
	return c.id == other.id
}

BankAccount Entity

Practical DDD in Golang: Module

marko.milojevic@ompluscator.io (Marko Milojevic) — Sun, 17 Sep 2023 22:50:01 +0200

At first glance, Modules may not seem like a typical software development pattern, especially when we often associate patterns with specific code structures or behaviors. This can be particularly confusing when considering Go Modules. These modules consist of closely related Go Packages, are versioned, and released together, serving as a form of dependency management in Go. Since both Go Modules and Packages impact the project’s structure, it raises the question of their relationship with the DDD pattern known as Module. Indeed, there is a connection between them.

The Structure
#

In Go, we use Packages to organize and group our code. Packages are closely tied to the folder structure within our projects, although there can be variations in naming. These variations arise because we have the flexibility to name our package differently than the actual folder it resides in.

Folder pkg/access/domain/model

package access_model

import (
	"github.com/google/uuid"
)

type User struct {
	ID uuid.UUID
	//
	// some fields
	//
}

Folder pkg/access/domain/service

package access_service

import (
	"project/pkg/access/domain/model"
)

type UserService interface {
	Create(user access_model.User) error
  	//
	// some methods
	//
}

In the example above, you can observe slight differences between folder and package naming. In some cases, when dealing with multiple model packages, I add prefixes from my DDD Modules to facilitate referencing these packages within the same file. Now, we can start to gain a better understanding of what a DDD Module would be in the previous example. In this context, the Module encompasses the access package along with all its child packages.

project
├── cmd
│   ├── main.go
├── internal
│   ├── module1
│   │   ├── infrastructure
│   │   ├── presentation
│   │   ├── application
│   │   ├── domain     
│   │   │   ├── service    
│   │   │   ├── factory    
│   │   │   ├── repository    
│   │   │   └── model  
│   │   └── module1.go
│   ├── module2
│   │   └── ...
│   └── ...
├── pkg
│   ├── module3
│   │   └── ...
│   ├── module4
│   │   └── ...
│   └── ...
├── go.mod
└── ...

The folder structure in the diagram above represents my preferred project structure for implementing Domain-Driven Design in Go. While I may create different variations of certain folders, I strive to maintain consistent DDD Modules.

In my projects, each Module typically consists of no more than four base packages: infrastructure, presentation, application, and domain. As you can see, I adhere to the principles of Hexagonal Architecture. In this structure, I place the infrastructure package at the top. This is because, by following Uncle Bob’s Dependency Inversion Principle, my low-level Services from the infrastructure layer implement high-level interfaces from other layers. With this approach, I ensure that I define a Port, such as the UserRepository interface, in the domain layer, while the actual implementation resides in the infrastructure layer. There can be multiple Adapters for this implementation, like UserDBRepository or UserFakeRepository.

Practical DDD in Golang: Domain Event

marko.milojevic@ompluscator.io (Marko Milojevic) — Sun, 17 Sep 2023 22:08:01 +0200

In many cases, Entities are the most effective means of representing elements in Domain-Driven Design. Together with Value Objects, they can provide a precise reflection of our Problem Domain. However, sometimes, the most apt way to depict a Problem Domain is by employing events that transpire within it. In my experience, I increasingly attempt to identify events and then discern the Entities associated with them. Although Eric Evans didn’t cover the Domain Event pattern in the first edition of his book, today, it’s challenging to fully develop the domain layer without incorporating events.

The Domain Event pattern serves as a representation of such occurrences within our code. We employ it to elucidate any real-world event that holds relevance for our business logic. In the contemporary business landscape, virtually everything is connected to some form of event.

It can be anything
#

Domain Events can encompass a wide range of occurrences, but they must adhere to certain rules. The first rule is that they are immutable. To support this characteristic, I consistently utilize private fields within Event structs, even though I’m not particularly fond of private fields and getters in Go. However, Events typically don’t require many getters. Additionally, a specific Event can only occur once. This implies that we can create an Order Entity with a particular Identity only once, and consequently, our code can only trigger the Event that describes the creation of that Order once. Any other Event related to that Order would be a different type of Event, pertaining to a distinct Order. Each Event essentially narrates something that has already taken place, representing the past. This means we trigger the OrderCreated Event after we have already created the Order, not before.

Global Events

type Event interface {
	Name() string
}

type GeneralError string

func (e GeneralError) Name() string {
	return "event.general.error"
}

Order Event

type OrderEvent interface {
	Event
	OrderID() uuid.UUID
}

type OrderDispatched struct {
	orderID uuid.UUID
}

func (e OrderDispatched) Name() string {
	return "event.order.dispatched"
}

func (e OrderDispatched) OrderID() uuid.UUID {
	return e.orderID
}

type OrderDelivered struct {
	orderID uuid.UUID
}

func (e OrderDelivered) Name() string {
	return "event.order.delivery.success"
}

func (e OrderDelivered) OrderID() uuid.UUID {
	return e.orderID
}

type OrderDeliveryFailed struct {
	orderID uuid.UUID
}

func (e OrderDeliveryFailed) Name() string {
	return "event.order.delivery.failed"
}

func (e OrderDeliveryFailed) OrderID() uuid.UUID {
	return e.orderID
}

The code example provided above demonstrates simple Domain Events. This code represents just one of countless ways to implement them in Go. In certain situations, such as with GeneralError, I have employed straightforward strings as Event representations. However, there are instances when I’ve utilized more complex objects or extended the base Event interface with a more specific one to introduce additional methods, as seen with OrderEvent.

Practical DDD in Golang: Domain Service

marko.milojevic@ompluscator.io (Marko Milojevic) — Sun, 17 Sep 2023 20:02:01 +0200

After discussing Entity and Value Objects, I will now introduce the third member of the group of Domain-Modeling patterns in this article: Domain Service. Domain Service is perhaps the most misunderstood DDD pattern, with confusion stemming from various web frameworks. In many frameworks, a Service takes on a multitude of roles. It’s responsible for managing business logic, creating UI components such as form fields, handling sessions and HTTP requests, and sometimes even serving as a catch-all “utils” class or housing code that could belong to the simplest Value Object.

However, almost none of the aforementioned examples should be a part of a Domain Service. In this article, I will strive to provide a clearer understanding of its purpose and proper usage.

Stateless
#

A critical rule for Domain Services is that they must NOT maintain any state.

Additionally, a Domain Service must NOT possess any fields that have a state.

While this rule may seem obvious, it’s worth emphasizing because it’s not always followed. Depending on a developer’s background, they may have experience in web development with languages that run isolated processes for each request. In such cases, it may not have been a concern if a Service contained state. However, when working with Go, it’s common to use a single instance of a Domain Service for the entire application. Therefore, it’s essential to consider the consequences when multiple clients access the same value in memory.

Use State in Entity

type Account struct {
	ID      uint
	Person  Person
	Wallets []Wallet
}

Use State in Value Object

type Money struct {
	Amount   int
	Currency Currency
}

DON’T use State in Domain Service

type DefaultExchangeRateService struct {
	repository      *ExchangeRateRepository
  	useForceRefresh bool
}

type CasinoService struct {
	bonusRepository BonusRepository
	bonusFactory    BonusFactory
	accountService  AccountService
}

As evident in the example above, both Entity and Value Object retain states. An Entity can modify its state during runtime, while Value Objects always maintain the same state. When we require a new instance of a Value Object, we create a fresh one.

In contrast, a Domain Service does not house any stateful objects. It solely contains other stateless structures, such as Repositories, other Services, Factories, and configuration values. While it can initiate the creation or persistence of a state, it does not retain that state itself.

Practical DDD in Golang: Entity

marko.milojevic@ompluscator.io (Marko Milojevic) — Sun, 17 Sep 2023 14:51:01 +0200

In the previous article, I attempted to provide insights into the Value Object design pattern and how we should apply it in Go. In this article, the narrative continues with the introduction of a design pattern called Entity. Many developers have heard about Entity countless times, even if they’ve never used the DDD approach. Examples can be found in PHP frameworks and Java. However, its role in DDD differs from its use elsewhere. Discovering its purpose in DDD marked a significant turning point for me. It seemed a bit unconventional, especially for someone with a background in PHP MVC frameworks, but today, the DDD approach appears more logical.

It is not part of ORM
#

As demonstrated in the examples for PHP and Java frameworks, the Entity often assumes the roles of various building blocks, ranging from Row Data Gateway to Active Record. Due to this, the Entity pattern is frequently misused. Its intended purpose is not to mirror the database schema but to encapsulate essential business logic. When I work on an application, my Entities do not necessarily replicate the database structure.

In terms of implementation, my first step is always to establish the domain layer. Here, I aim to consolidate the entire business logic, organized within Entities, Value Objects, and Services. Once I’ve completed and unit-tested the business logic, I proceed to create an infrastructural layer, incorporating technical details like database connections. As illustrated in the example below, we separate the Entity from its representation in the database. Objects that mirror database schemas are distinct, often resembling Data Transfer Objects or Data Access Objects.

Entity inside the Domain Layer

type BankAccount struct {
	ID       uint
	IsLocked bool
	Wallet   Wallet
	Person   Person
}

Repository interface inside the Domain Layer

// Repository interface inside domain layer
type BankAccountRepository interface {
	Get(ctx context.Context, ID uint) (*BankAccount, error)
}

Data Access Object inside the Infrastructure Layer

type BankAccountGorm struct {
	ID         uint       	`gorm:"primaryKey;column:id"`
	IsLocked   bool       	`gorm:"column:is_locked"`
	Amount 	   int        	`gorm:"column:amount"`
	CurrencyID uint 	    `gorm:"column:currency_id"`
	Currency   CurrencyGorm `gorm:"foreignKey:CurrencyID"`
	PersonID   uint       	`gorm:"column:person_id"`
	Person     PersonGorm 	`gorm:"foreignKey:PersonID"`
}

Concrete Repository inside the Infrastructure Layer

type BankAccountRepository struct {
	//
	// some fields
	//
}

func (r *BankAccountRepository) Get(ctx context.Context, ID uint) (*domain.BankAccount, error) {
	var dto BankAccountGorm
	//
	// some code
	//
	return &BankAccount{
		ID:       dto.ID,
		IsLocked: dto.IsLocked,
		Wallet:   domain.Wallet{
			Amount:   dto.Amount,
			Currency: dto.Currency.ToEntity(),
		},
		Person:   dto.Person.ToEntity(),
	}, nil
}

The example shown above is just one of the many variations we can implement. While the structure of both the Entity and DTO can vary depending on the specific business case (such as having multiple Wallets per BankAccount), the core concept remains consistent.

Practical DDD in Golang: Value Object

marko.milojevic@ompluscator.io (Marko Milojevic) — Sat, 16 Sep 2023 17:39:01 +0200

Saying that a particular pattern is the most important might seem like an exaggeration, but I wouldn’t even argue against it. The first time I encountered the concept of a Value Object was in Martin Fowler’s book. At that time, it seemed quite simple and not very interesting. The next time I read about it was in Eric Evans’ “The Big Blue Book.” At that point, the pattern started to make more and more sense, and soon enough, I couldn’t imagine writing my code without incorporating Value Objects extensively.

Simple but beautiful
#

At first glance, a Value Object seems like a simple pattern. It gathers a few attributes into one unit, and this unit performs certain tasks. This unit represents a particular quality or quantity that exists in the real world and associates it with a more complex object. It provides distinct values or characteristics. It could be something like a color or money (which is a type of Value Object), a phone number, or any other small object that offers value, as shown in the code block below.

Quantity

type Money struct {
  Value    float64
  Currency Currency
}

func (m Money) ToHTML() string {
  returs fmt.Sprintf(`%.2f%s`, m.Value, m.Currency.HTML)
}

Quality

type Color struct {
  Red   byte
  Green byte
  Blue  byte
}

func (c Color) ToCSS() string {
  return fmt.Sprintf(`rgb(%d, %d, %d)`, c.Red, c.Green, c.Blue)
}

Type extension


type Salutation string

func (s Salutation) IsPerson() bool {
  returs s != "company" 
}

Logical Group

type Phone struct {
  CountryPrefix string
  AreaCode      string
  Number        string
}

func (p Phone) FullNumber() string {
  returs fmt.Sprintf("%s %s %s", p.CountryPrefix, p.AreaCode, p.Number) 
}

In Golang, you can depict Value Objects by creating new structs or by enhancing certain basic types. In either scenario, the goal is to introduce specialized functionalities for that individual value or a set of values. Frequently, Value Objects can supply particular methods for formatting strings to determine how values should operate during JSON encoding or decoding. However, the primary purpose of these methods should be to maintain the business rules linked to that particular characteristic or quality in real life.

Identity and Equality
#

A Value Object lacks identity, and that’s its key distinction from the Entity pattern. The Entity pattern possesses an identity that distinguishes its uniqueness. If two Entities share the same identity, it implies they refer to the same objects. On the other hand, a Value Object lacks such identity. It only consists of fields that provide a more precise description of its value. To determine equality between two Value Objects, we must compare the equality of all their fields, as demonstrated in the code block below.

Golang on Ompluscator's Blog

LLM and Go: OpenAI integration via Responses API

Responses API #

First AI agent #

LLM and Go: Investigating OpenAI Chat Completions API

Chat Completions API details #

Information extraction with response_format #

LLM and Go: OpenAI Integration via Chat Completions API

A short introduction to ChatGPT and OpenAI #

Go Tutorial: Iterators

Why do we need Iterators? #

Golang Release 1.22: version

Lang #

IsValid #

Golang Release 1.21: slices - Part 2

Sort #

Benchmark #

Golang Release 1.21: slices - Part 1

BinarySearch and BinarySearchFunc #

Golang Release 1.21: cmp

Ordered constraint and Compare function #

Function Less #