Forem: Francis Awuor

The Two-Track Learning Method I’m Using to Actually Understand Web Development

Francis Awuor — Thu, 21 May 2026 20:57:40 +0000

There's a specific kind of confusion that doesn't show up in tutorials. It's not "I don't know the syntax." You can look up syntax. It's more like... you're using a library or a framework, things are working, and you still have this vague feeling that you don't really know what's going on.

I've been there more than I'd like to admit. I used React before I actually understood JavaScript. I used Go's context package while having basically no mental model of what context even was. I was driving the car with no idea what was under the hood. And it showed. Not always immediately, but the moment something broke in an unexpected way, or I tried to pick up something new, the gaps were obvious.

But I've been trying something lately that's been genuinely helping, and it’s been genuinely helping. I'm calling it the two-track method, though honestly it's less of a structured method and more of a habit I've been building. The idea is simple: before I reach for the abstraction, I build a tiny version of it myself first.

The Method

It doesn't have to be complete. Doesn't have to be good. Just functional enough that I've actually felt the problem the abstraction is solving.

That's the thing I keep coming back to. Abstractions are solutions to problems. But if I've never felt the problem, the solution feels arbitrary. I end up memorizing API surfaces instead of understanding them, and that only gets me so far.

So the two tracks look like this:

Track 1: Build the primitive myself. Keep it small. Get it working.

Track 2: Pick up the real library. See what's different.

I used to jump straight to Track 2. Spend weeks getting comfortable with a library, never really shake that feeling of depending on it without understanding it. Flipping the order, even just once, has made a noticeable difference for me. Something clicks that's hard to un-click.

Example 1: HTTP from scratch To net/http

A while back I implemented the HTTP protocol from scratch in Go. Not as a joke, as an actual exercise. I was parsing raw bytes off a TCP connection, pulling apart request lines, validating methods, checking HTTP versions. Stuff like this:

func parseRequestLine(b []byte) (*RequestLine, int, error) {
    idx := bytes.Index(b, SEPARATOR)
    if idx == -1 {
        return nil, 0, nil
    }
    startLine := b[:idx]
    parts := bytes.Split(startLine, []byte(" "))
    if len(parts) != 3 {
        return nil, 0, fmt.Errorf("invalid request line: %s; want 3 parts, have %d", startLine, len(parts))
    }
    // ...
}

It was tedious. Slightly painful. I had to actually think about what an HTTP request is made of at the byte level. Method, target, version, headers, body. All of it sitting in a raw buffer, waiting to be parsed.

So then when I picked up net/http, things that would have just been "okay I guess I just do it this way" suddenly had reasons behind them. What a Handler is actually doing. Why ResponseWriter is an interface. What's happening under the hood when a request comes in and gets routed somewhere. I wasn't guessing anymore. I had a mental model.

The part I didn't expect though: the knowledge transferred. Understanding HTTP at that level started showing up in other places. Writing command parsers. Understanding how the browser handles HTML. Things that look unrelated on the surface but share the same underlying ideas. Once you've seen the raw thing, you start recognizing its shape everywhere.

Example 2: Tiny context library To Go's context package

Context was one of those things that just wouldn't click for me. I'd see ctx context.Context in every function signature, pass it along like I was supposed to, and move on. I knew it had something to do with cancellation and deadlines. That was about it.

So I built a tiny version of it myself. And I mean tiny. A struct with a done channel, an error, a parent pointer, and a key-value pair. Then WithCancel, WithTimeout, WithValue. A goroutine watching for parent cancellation and propagating it down.

type MyContext struct {
    done     chan struct{}
    err      error
    parent   *MyContext
    key, val any
}

func WithCancel(parent *MyContext) (*MyContext, func()) {
    ctx := &MyContext{
        done:   make(chan struct{}),
        parent: parent,
    }
    go func() {
        if parent == nil {
            return
        }
        select {
        case <-parent.Done():
            ctx.cancel(fmt.Errorf("parent cancelled"))
        case <-ctx.Done():
            return
        }
    }()
    cancel := func() {
        ctx.cancel(fmt.Errorf("manually cancelled"))
    }
    return ctx, cancel
}

Then I wired up a little worker that listened on the done channel:

func worker(ctx *MyContext, id int) {
    for {
        select {
        case <-ctx.Done():
            fmt.Printf("Worker %d stopping: %v\n", id, ctx.Err())
            return
        default:
            fmt.Printf("Worker %d working...\n", id)
            time.Sleep(500 * time.Millisecond)
        }
    }
}

And let me tell you, this was a good idea. ctx context.Context started making a lot more sense. It's just a done channel, an error, and a chain of parents.

Example 3: Vanilla JS state management To React

This one was a big problem. I jumped into React pretty early. Like, embarrassingly early. I'd done a JavaScript tutorial, felt reasonably okay about it, and went straight into a React course. And I got through it. I could build things.

But I couldn't tell you what was React and what was just JavaScript. It was all one blur. When I'd write JSX I genuinely wasn't sure sometimes which bits were React magic and which bits were plain JS. That kind of confusion has a cost. It made me nervous about touching things I hadn't seen in a tutorial before. And it made me feel like switching to another framework would basically mean starting from scratch.

But lately I’ve been writing a lot of vanilla JavaScript. And at some point I’ve had to manually manage state for a small project. No libraries. Just me, some variables, and a lot of manual DOM updates whenever something changed. Not gonna lie, it hasn’t been particularly fun. But it’s been immensely useful.

React is starting to make a lot more sense now. Not just what it does, but why it exists. The problem it's solving isn't abstract anymore, I'm really feeling it. The state management, the re-rendering, the component model… all of it is suddenly clicking into place.

And the confidence thing is real. I feel like I could pick up Vue or Svelte or whatever comes next without too much trouble. Because I now understand what they're all fundamentally trying to solve.

It's Not Just Libraries

I want to mention something that's been running alongside all of this, because I think it's the same idea wearing different clothes.

A lot of the clarity I've been getting hasn't just come from building primitives of tools. It's come from learning the concepts underneath the concepts. The stuff that lives below the library layer entirely.

Take networking. I spent some time learning about the OSI model, how data actually moves across a network, what's happening at each layer. Dry stuff on the surface. But when I came back to HTTP after that, things that were previously just "that's how it works" had actual reasons behind them. The layers aren't arbitrary. TCP being reliable while UDP isn't is more than a trivia fact. It's a design decision that makes sense once you actually understand what problem each one is solving. That context made everything above it stickier.

Or memory. I did a little C specifically to understand how memory works. Pointers, the stack, the heap, manually allocating and freeing things. It was pretty weird to be honest. C will just let you access garbage memory.

Anyway though, when I came back to Go after that, I understood more deeply why slices behave the way they do. What the garbage collector is actually relieving you of. How goroutines sit in memory differently from OS threads.

Same with operating systems. I'm still pretty early on this one. But even a surface-level understanding of how an OS manages processes and schedules work has given me a better mental model for writing concurrent code. It's like the floor got more solid.

I think the pattern is the same one. Abstractions make more sense when you understand what they're abstracting. Whether that's a library abstracting over a protocol, or a language abstracting over memory management, or a runtime abstracting over the operating system. The further down you've looked, even just once, even just a little, the less arbitrary everything above it feels.

I'm not saying go learn C and then the Linux kernel before you write another line of JavaScript. That's not what this is. It's more that I've found it worth occasionally asking: what is this thing actually sitting on top of? And then going and poking at that layer, even briefly. It pays off in ways that are hard to predict in advance.

Conclusion

I'm still in the middle of all this, to be clear. There's a long list of things I haven't built from scratch yet and probably won't for a while. I'm not trying to re-implement the entire stack before I'm allowed to use a library.

But the ones I have done? I can feel the difference. It's hard to describe precisely, but it's somewhere between confidence and calm. Not "I know everything about this tool" confidence. More like "I'm not just hoping this works" confidence. There's a solidity to it.

I think that's what this method is really about, underneath everything. It's not about being the person who built a router from scratch. It's about not feeling like you're guessing. Because there's a real difference between using a tool and understanding a tool. One of them means you're dependent on things staying familiar. The other means you can move around, adapt, pick things up, put things down.

I stumbled into this backwards, through confusion and frustration more than any deliberate plan. The HTTP implementation wasn't a grand learning strategy, it was an exercise that turned out to matter more than I expected. Same with context, same with vanilla JS state. I just kept noticing that the things I'd felt the pain of first were the things that stuck.

So that's what I'm doing now. Trying to feel the problem before I reach for the solution. It's slower in the short term. But I'm finding it's a lot faster than going back to fill in gaps later.

Go Idioms I Wish I Knew Earlier

Francis Awuor — Thu, 21 May 2026 18:39:02 +0000

I've been writing Go for a while now, and somewhere along the way something shifted.

My code started feeling less like "code that happens to be in Go" and more like... Go code. Hard to explain, but you notice it when it happens.

Go has patterns. Not rules exactly, but ways of doing things that show up everywhere across the language and the ecosystem. Error handling. Naming. Control flow. The way you structure types. You start picking them up gradually, and when you finally start using them yourself, your code starts to feel right in a way that's difficult to articulate.

This article is just me sharing the ones that clicked for me. Some are well-known idioms. Some are just habits I picked up from reading enough Go code written by people who clearly knew what they were doing.

This isn’t the official take though. For that, go read Effective Go. It's from the Go team and it's genuinely good. Think of this as the stuff I wish I'd come across earlier.

Okay. Let's get into it.

1. Go Makes You Deal With Uncertainty Explicitly

One of the first things that hits you when you start writing Go is that its error handling is very explicit.

Two patterns show up everywhere, and once you understand what they're actually doing, a huge chunk of Go code starts making sense.

`err != nil` : the error check you'll write a thousand times

In most languages, errors get thrown and caught somewhere up the chain. Go doesn't do that. Functions that can fail return the error directly, and you check it right there.

user, err := getUserByID(id)
if err != nil {
    return err
}

At first this feels repetitive. You write if err != nil so many times you start doing it in your sleep. But that's kind of the point. There's no hidden control flow. No wondering where an exception might surface. The error is right there, and you deal with it or you pass it up. It’s your call.

What makes it even nicer is redeclaration. If you're chaining multiple calls, you don't need a new err variable each time. Go lets you reuse the one err variable with := as long as at least one variable on the left is new:

user, err := getUserByID(id)
if err != nil {
    return err
}

profile, err := getProfile(user.ID)
if err != nil {
    return err
}

Same err, reassigned each time. You just keep going down the chain, handling as you go.

The comma-ok idiom: "does this even exist?"

The other pattern is comma-ok. You see it when reading from a map, doing a type assertion, or receiving from a channel:

value, ok := someMap[key]
if !ok {
    // key doesn't exist
}

The second value, ok , is just a boolean. It's Go's way of saying: this operation might not give you anything useful, here's how you check.

It’s really the same idea as err != nil. Go doesn't like silent failures. It hands you the result and the signal that tells you whether it’s safe to use.

This has been pretty good for me, cause before Go I tended to skip error checks and just sort of assume things exist.

2. Naming Things the Go Way

Go is pretty opinionated about names. Not in a loud way, just in a "this is how we do it here" way. Two things tripped me up early on.

Package-scoped names

When I started out I was writing things like jobs.JobsService and companies.CompaniesService. Felt thorough. Felt descriptive. Also felt redundant the moment someone pointed it out to me.

The package name is already doing half the work. jobs.Service says exactly the same thing as jobs.JobsService, just without the stutter. Go leans on this everywhere. You're not writing the type in isolation, you're writing it in context. Let the package carry its weight.

Once I internalized this, I started catching myself doing it with other things too. jobs.JobFilter becoming jobs.Filter. users.UserStore becoming users.Store. Much cleaner, much simpler… don’t you think?

Interface names: Reader, Writer, and friends

This one confused me for longer than I'd like to admit.

Go's convention is to name interfaces after what they do, usually as a single word with an -er suffix. Reader. Writer. Stringer. Handler. It sounds simple but it's actually a really clean system once it clicks. If your type has a Read method, it's a Reader. That's it.

The practical payoff is standard library function signatures become much easier to read and understand. When you see a function that accepts an io.Writer, you immediately know: anything with a Write method works here. os.File, bytes.Buffer, http.ResponseWriter. They all qualify.

3. Writing Clean Control Flow

This section is about the stuff that makes Go code easy to read top to bottom. The patterns here are some of my favorite, even though they’re much more convenience type patterns than patterns that have a lot to do with whether your program runs correctly.

Early returns instead of if-else chains

I used to write a lot of this:

if condition {
    // do thing
} else if other condition {
    // do other thing
} else {
    // fallback
}

Go developers tend to flip that around. Handle the bad cases first, return early, and let the happy path sit at the bottom with no indentation:

if !condition {
    return err
}

if !otherCondition {
    return err
}

// happy path here

It’s a small shift, but one that I think makes a big difference. With this pattern, you don’t need to mentally track multiple branches. You just read down.

Chaining calls with redeclaration

This one I use constantly. We already mentioned it a little. When you're making multiple calls that can fail, you don't need a fresh err variable each time. Go lets you reuse it with := as long as at least one variable on the left side is new:

user, err := getUserByID(id)
if err != nil {
    return err
}

profile, err := getProfile(user.ID)
if err != nil {
    return err
}

posts, err := getPostsByUser(user.ID)
if err != nil {
    return err
}

Same err the whole way down. It keeps things clean and you're never managing a bunch of err1, err2, err3

Only take what you need from a range loop

If you're ranging over a slice and you only need the index, you don't have to assign the value at all:

for i := range someSlice {
    // just the index
}

No need for the _ placeholder.

4. Working With Types Intentionally

Go's type system is one of the things I've come to genuinely appreciate. It nudges you toward writing code that's flexible but safe.

Interfaces for swappability

An interface in Go is just a contract. If your type has these methods, it satisfies the interface. That's it.

The reason this matters practically is swappability. Say you have a service that depends on a repository. If that repository is a concrete type, you're locked in. If you want to, for example, swap it out in tests, you can’t easily do that. Not without a refactor. But if you depend on an interface instead:

type UserRepository interface {
    GetByID(id int) (User, error)
    Create(u User) error
}

Now anything that implements those methods works. Your real database repository. A mock for tests. Whatever.

I use this pattern constantly in my projects now. It keeps things separate in a way that actually helps when things get complicated.

Small pure functions, orchestrated by bigger ones

Not exclusively a Go thing. More a general organizational pattern, but I’ve been doing it a lot in Go.

The idea is simple. Write small functions that do one thing and don't touch anything outside themselves. Then write a bigger function whose only job is calling those smaller ones in the right order.

func processJob(job Job) error {
    if err := validateJob(job); err != nil {
        return err
    }

    normalized := normalizeJob(job)

    if err := saveJob(normalized); err != nil {
        return err
    }

    return nil
}

validateJob, normalizeJob, saveJob , each one does its thing. processJob just calls and organizes them. When something breaks, you know exactly where to look.

`make` for slices when you know the size

If you know upfront how many elements a slice will have, initialize it with make:

results := make([]Job, len(input))

for i, item := range input {
    results[i] = process(item)
}

Without make, you'd have to append each element, and you lose the ability to assign by index directly.

Embedding

Honestly, I don’t use this one that often. But when I do come across the need, it’s very useful.

Embedding lets one struct inherit the fields and methods of another by simply listing it in the inheriting struct:

type Animal struct {
    Name string
}

func (a Animal) Speak() string {
    return a.Name + " makes a sound"
}

type Dog struct {
    Animal
    Breed string
}

Dog gets Speak() for free

5. Concurrency: Getting a Response Back

Go's concurrency model is one of its best features. Goroutines are cheap, channels are elegant, and the whole thing just makes sense once it clicks. Most of the time when you spin up a goroutine you're firing something off and not waiting for a response. But sometimes you need one.

The pattern I've used for this is adding a result channel directly to the struct:

type Client struct {
    conn    net.Conn
    msgCh   chan string
    resultCh chan error
}

When the goroutine finishes its work, it sends the result down resultCh. The caller is sitting on the other end waiting for it:

go client.handleMessage(msg)

if err := <-client.resultCh; err != nil {
    log.Println("something went wrong:", err)
}

I ran into this pattern building a netcat group chat app. Multiple clients, concurrent connections, and I needed to know when something failed. Passing the result channel on the struct kept everything organized without having to thread channels through every function signature.

Wrapping Up

Here's the thing about idiomatic Go. Nobody sits down and studies it all at once. You pick it up gradually. You read someone else's code and think "oh, that's a cleaner way to do that." You get a review comment. You break something and figure out why. Slowly your code starts looking more like the language it's written in.

The patterns in this article are just the ones that stuck for me. Error handling that forces you to be explicit. Naming that lets the package do the talking. Control flow that reads like a straight line. Types that stay flexible without getting complicated.

None of it is revolutionary. That's kind of the point. Go is not a revolutionary language. It's a deliberate one. And the more you write it, the more you realize that the "boring" choices are usually the right ones.

If you want the proper, structured breakdown of idiomatic Go, go read Effective Go. It's from the people who built the language. This was just me passing on the stuff I wish I'd had earlier.

Now go write some Go. You'll figure the rest out.

Go Gotchas That Cost Me Hours (Learn From My Pain)

Francis Awuor — Wed, 20 May 2026 19:46:53 +0000

Go has burned me more than once. With bugs that felt like the language was glitching:

Channels that blocked after I’d “fixed” the blocking. Functions that kept running after hitting an error. Slices that printed data that seemingly came out of nowhere.

But as I’ve come to learn, every single time, Go was doing exactly what I asked. I just didn’t fully understand what I was asking for.

So in this article I want to share some of the “gotchas” that have cost me an embarrassing amount of time, simply because I didn’t fully understand how the language and its idioms worked.

I hope they save you some hours of pain.

Gotcha 1: Channels don't eliminate blocking. They move it.

A little while ago, I was building a mini tool that turns Linux’s Netcat into a group chat tool. Simple enough idea: multiple clients connect, one sends a message, everyone gets it. Like a mini-terminal-based WhatsApp group.

The problem with that is I ended up writing to multiple network connections (i.e., ”sending messages”) in my main loop. Which runs the risk of a slow client blocking the whole server.

func broadcast(clients []*Client, msg string) {
    for _, client := range clients {
        // writing directly to the network connection
        // a slow client blocks everyone behind it
        fmt.Fprintln(client.conn, msg)
    }
}

So I did what felt like the obvious fix: give each client their own messages channel. That way I'm not writing to slow network connections in the main loop anymore.

type Client struct {
    conn     net.Conn
    messages chan string
}

Each client handler reads from its channel and writes to the connection. No blocking in the main loop.

Or so I thought.

Turns out however, a slow client could still block my server.

Here's why. The channel I created was unbuffered:

messages: make(chan string)

An unbuffered channel blocks the sender until the receiver reads from it. So if a client handler was slow writing to the network, it stopped reading from the channel. Which meant the main loop sending to that channel blocked. Which meant every other client stalled too.

I'd just pushed the blocking one step further. From the network write, into the channel send.

// main loop broadcasting to all clients
for _, client := range clients {
    client.messages <- msg // still blocks if the client handler is slow
}

To really fix it, I had to

Give the channel a reasonable buffer size (so it could accept multiple messages without blocking)

messages: make(chan string, 10)

Add a timeout for really slow clients (cause buffers can still get full)

select {
case client.messages <- msg:
    // sent
case <-time.After(time.Second):
    // client too slow, skip or disconnect
}

Channels are great for avoiding race conditions when you’ve got concurrent code. But they, and goroutines, don’t magically fix bottlenecks.

I’d basically been running a sort of mental shortcut where goroutines + channels = fast safe code.

But that gets you into issues like this.

Gotcha 2: Slicing doesn't copy. And that will ruin your day.

This one made me want to pull my hair out. I spent a whole hour, in a coding test, staring at my code, running it again and again, trying to figure out why I was getting weird outputs.

See what I’d done was something like this:

alt := rev1[:by]
rev1 = rev1[by:]

I split a slice in two. And then later looped through my rev1 slice while appending to alt.

for _, v := range rev1 {
    alt = append(alt, v)
}

But here’s the thing.

Slicing in Go doesn’t make a copy. It just creates a small header pointing to the same underlying array. So alt and rev1 were sharing memory.

original := []int{1, 2, 3, 4, 5}
alt := original[:2]  // [1, 2] — but still pointing at the same array
rev1 := original[2:] // [3, 4, 5] — same array, different window

So when I appended to alt, Go wrote into the array that rev1 was also pointing at. Which meant the slice I was iterating over was being modified while I was iterating over it.

So the values kept changing.

Leading to my weird outputs.

The fix is to force each slice onto its own backing array. The cleanest way to do that is to append data from one slice into the other. append() copies data from one slice to the other, giving each slice its own backing array. It’s own chunk of memory, if you will.

alt := append([]int{}, rev1[:by]...)

It's one of those things that makes total sense once you understand how slices work under the hood. But until you do, it’s a head-scratcher.

Gotcha 3: `make()` with a length isn't an empty slice.

This one got me twice. Same bug, same confusion, different day.

I needed a slice to collect some values, so I did what felt natural:

results := make([]int, 3)

Then later appended to it:

results = append(results, 42)

And ended up with:

[0, 0, 0, 42]

Not [42]. Not what I wanted.

Here's the thing. make([]int, 3) doesn't give you an empty slice with room for 3 elements. It gives you a slice with 3 elements already in it, all set to their zero value. When you append, Go doesn't replace those zeros. It adds your values after them.

If you want an empty slice with preallocated capacity, the second argument to make is length, and there's a third for capacity:

results := make([]int, 0, 3) // length 0, capacity 3
results = append(results, 42) // [42]

Or just use a nil slice if you don't need to preallocate:

var results []int
results = append(results, 42) // [42]

The distinction between length and capacity can be a somewhat unclear at first. Length is how many elements are in the slice right now. Capacity is how much room the underlying array has before Go needs to allocate a new one.

Gotcha 4: Forgetting to `return` after handling an error.

This one is less of a language quirk and more of a habit you have to build. But it's bitten me enough times to earn its spot here.

It goes like this. You're in an error block, you do something (log it, append to a slice, whatever) and then you just move on, forget to add a return statement.

func process(data []string) ([]Result, error) {
    var results []Result

    parsed, err := parse(data)
    if err != nil {
        log.Println("parse error:", err)
        // forgot to return here
    }

    // keeps running with a broken `parsed`
    for _, item := range parsed {
        results = append(results, transform(item))
    }

    return results, nil
}

The function keeps running with broken state. And then something fails way down the line in a completely different function, and you spend twenty minutes tracing backwards trying to figure out why.

The fix is just the habit. return is part of the error block, always:

if err != nil {
    log.Println("parse error:", err)
    return nil, err
}

Same thing applies with break and continue in loops. If your logic depends on stopping or skipping after a condition, make sure you're actually telling Go to stop or skip.

Truth be told though, even with this warning, this one will probably still get you a few times before your OCD finally kicks in and forces you to check every every error block you write.

Ones I Caught Before They Caught Me

These two didn't burn me the way the others did. I came across them early enough to file them away before making the mistake. I’m passing them on for the same reason.

Loop variable capture in goroutines

If you spin up goroutines inside a loop and reference the loop variable inside them, all the goroutines might end up using the same value, i.e., the final one the loop landed on.

items := []string{"book", "pen", "eraser"}

for _, v := range items {
    go func() {
        fmt.Println(v) // all goroutines might print "eraser"
   }()
}

This happens because the goroutines close over v itself (see closures), not its value at the time the goroutine was created. By the time they run, the loop may have already finished.

The fix is to pass the value as an argument:

for _, v := range items {
    go func(val string) {
        fmt.Println(val) // each goroutine gets its own copy
    }(v)
}

Worth knowing: Go 1.22 changed loop variable semantics so each iteration gets its own variable. If you're on a recent version this is less of a landmine. But a lot of codebases are still on older versions, so it's worth understanding either way.

`defer` in a loop

defer doesn't run at the end of each loop iteration. It runs when the surrounding function returns.

for _, path := range files {
    f, err := os.Open(path)
    if err != nil {
        continue
    }
    defer f.Close() // won't close until the whole function exits
}

If you're opening files in a loop and deferring their close, you'll hold all of them open until the function returns. On a long-running loop that's a resource leak waiting to happen.
The fix is to wrap the body in a helper function, so defer behaves the way you intended:

func processFile(path string) error {
    f, err := os.Open(path)
    if err != nil {
        return err
    }
    defer f.Close() // now closes when processFile returns
    // ...
}

for _, path := range files {
    processFile(path)
}

These won't be the last ones.

Go has a way of humbling you just when you think you've got a handle on it. I've fixed these bugs, written them down, but I'm certain there's a new one waiting for me in code I haven't written yet.

But while every one of these cost me time, but they also left me with a clearer picture of how the language actually works under the hood. The slice bug taught me more about memory than any article I'd read on the topic. The channel bug forced me to actually think about concurrency instead of just reaching for goroutines by habit.

So if you're hitting weird bugs in Go right now, good. Trace through them. Write them down. They're likely teaching you something.

And if you've got your own, comment them below. I'm still collecting.

Thinking in Pipelines: A Better Way to Structure Go Systems

Francis Awuor — Sun, 03 May 2026 16:55:14 +0000

I was working on a personal project recently.

A job scraper.

And in the process, I came across a pattern that’s genuinely changed how I think about structuring backend systems in Go.

It's called the Pipeline Pattern. And as it turns out, it actually shows up in a lot of places - payments, analytics, APIs, etc.

In this article, I’ll be walking you through it using my job scraper project. Which is actually a perfect use case for this pattern, as you’ll see.

The Mess We're Trying to Avoid

Now before I show you the pattern, let me show you what the code could look like without it.

Now essentially what my scraper does is this:

Scrape job listings from multiple sources
Normalize them (i.e., clean them up)
Score them based on keywords (The most relevant to my skillset get the highest scores)
Save them to a database.

So initially what I might have done, was something like this (simplified):

for _, raw := range rawJobs {
    // normalize
    raw.Title = strings.TrimSpace(raw.Title)
    raw.Location = strings.ReplaceAll(raw.Location, "NYC", "New York")

    // score
    score := 0
    for _, keyword := range keywords {
        if strings.Contains(raw.Title, keyword) {
            score++
        }
    }

    // save
    s.Repo.Create(raw.Title, raw.Location, score)
}

Which technically works. But it creates a few problems:

No clear stages. Where does normalization end and scoring begin? You have to read everything to understand anything.
Hard to test. How do you test just the scoring logic? You can't. It's glued to everything else inside that loop.
Hard to change. Want a new scoring rule? You're digging through the loop, touching normalization, maybe breaking the save logic. Everything is coupled.
Hard to reuse. If you need that normalization logic somewhere else, you have to copy-paste it. And now you’re duplicating code.
Concurrency feels impossible. Now imagine you want to process jobs concurrently. Where do you even start? The loop? The scoring part? The saving part? Everything is tangled, so it’s hard to determine what to run concurrently.

The Realization

Now here’s the thing you might notice when you look at that loop.

It's not really one problem. It's the same set of steps, repeated for every job. Scrape a job, clean it up, evaluate it, save it. Every single time.

So the question becomes — what if we made those steps explicit?

The Pipeline

That's the core idea. Instead of one big loop doing everything, you break the work into stages:

Scrape → Normalize → Score → Store

Each stage does one thing. Data flows through, gets transformed, moves on.

Here's what that looks like in practice. This is the actual pipeline from my scraper:

type Pipeline struct {
    scorer         scoring.Scorer
    jobService     JobService
    companyService CompanyService
    logger         *slog.Logger
}

func NewPipeline(
    scorer scoring.Scorer,
    jobService JobService,
    companyService CompanyService,
    logger *slog.Logger,
) *Pipeline {
    return &Pipeline{
        scorer:         scorer,
        jobService:     jobService,
        companyService: companyService,
        logger:         logger,
    }
}

Notice what's happening in NewPipeline. You're not hardcoding any specific scraper or store. You're passing them in. We'll come back to why that matters in a second.

Now here's the Run() method. This is where the actual pipeline executes:

func (p *Pipeline) Run(ctx context.Context, scraper Scraper) error {
    // 1. Scrape
    rawJobs, err := scraper.Scrape(ctx)
    if err != nil {
        return fmt.Errorf("scraping %s: %w", scraper.Source(), err)
    }

    for _, rawJob := range rawJobs {
        // 2. Normalize
        normalizedJob, err := normalize.Normalize(rawJob)
        if err != nil {
            failed++
            continue
        }

        // 3. Score
        job.Score = p.scorer.Score(job)

        // 4. Save
        if err := p.jobService.Save(ctx, job); err != nil {
            failed++
            continue
        }
        saved++
    }
    return nil
}

Same logic as the messy version. But now every stage is cleanly separated into it’s own separate function.

You can read this top to bottom as it is now and immediately understand what the system does. Scrape, normalize, score, save. No digging or guessing. The structure tells you the story.

And that's before we even get to the best part.

Swappability

Here's where it gets interesting.

Because each stage is separate and wired through interfaces, you can swap any part of the pipeline without touching the rest. Think about what that means in practice.

Swap the scraper. During testing, I use a FakeScraper that returns hardcoded jobs. In production, that becomes a real scraper hitting actual job sites.

// testing
scraper := &FakeScraper{}

// production
scraper := &RemotiveScraper{}

The pipeline doesn't change. Not a single line.

Swap the store. In development, an in-memory store is fast and easy to work with. In production, that's a real database.

// development
store := NewInMemoryStore()

// production
store := NewPostgresStore()

Same pipeline. Different backend.

Swap the scorer. Right now I'm using a simple keyword-based scorer. Later, that could become something smarter. Maybe ML-based, maybe something else entirely.

scorer := &KeywordScorer{keywords: []string{"Go", "backend", "remote"}}

// later...
scorer := &MLScorer{}

Still the same pipeline.

This really made it click for me: You don’t rewrite the system. You just swap parts. Go back to that messy loop for a second. Try swapping the scraper there. You can't. The logic is baked in, everything depends on everything, there's no clean boundary to swap across.

The pipeline gives you those boundaries.

Concurrency - The Worker Pool

So now the system is clean and flexible. But what about performance?

Right now, everything runs one job at a time. Scrape one, normalize it, score it, save it. Then move to the next. For small datasets that's fine. For a thousand jobs, that's slow.

So let's level it up.

The idea is simple: instead of processing one job at a time, spin up a pool of workers (goroutines) and let them process jobs concurrently. If you haven't used goroutines before, they're basically lightweight threads in Go. You can spin up many of them without much overhead. The key word there is many, not unlimited. More on that in a second.

Here's the shape of it:

func (p *Pipeline) Run(ctx context.Context, scraper Scraper, numWorkers int) error {
    rawJobs, err := scraper.Scrape(ctx)
    if err != nil {
        return fmt.Errorf("scraping %s: %w", scraper.Source(), err)
    }

    jobs := make(chan RawJob)
    var wg sync.WaitGroup

    // spin up workers
    for i := 0; i < numWorkers; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for raw := range jobs {
                // normalize, score, save
            }
        }()
    }

    // feed jobs into the channel
    for _, raw := range rawJobs {
        jobs <- raw
    }
    close(jobs)

    wg.Wait()
    return nil
}

Think of it like a queue and a team. The channel is the queue. Raw jobs go in one end, workers pull from the other. Each worker runs a job through the pipeline stages independently. sync.WaitGroup just makes sure we don't return until every worker is done.

The numWorkers parameter is the important part. You decide how many workers run. Not Go, not the runtime. You. That matters because unbounded concurrency has a real cost. A thousand goroutines all trying to write to your database at the same time will hurt more than help. Three to ten workers, controlled, is usually the right call.

The pipeline didn't change conceptually. It just runs in parallel now.

Pipelines Are Everywhere

Now what’s interesting… once you internalize this pattern, you start seeing it everywhere.

Payments: validate the card → charge it → save the transaction. Analytics: collect the event → clean it → store it. APIs: receive the request → process it → send the response.

Different domains, same shape. Data comes in, moves through stages, comes out the other side transformed. That's the pipeline pattern. And the reason it keeps showing up is because it maps well onto how a lot of real work actually flows, i.e., step by step, with clear handoffs between stages.

Which means if you learn to recognize it, you can apply it. Not just in job scrapers, but anywhere you find yourself writing code that takes something, does a series of things to it, and produces a result.

So, Why Bother?

You could write a system without any of this. Plenty of working software is just one big loop doing everything. And honestly, for something small and throwaway, that's fine.

But the moment your system needs to grow, that big loop starts fighting you. You want to add a new data source, but the scraping logic is tangled with the normalization. You want to test scoring in isolation, but it's buried three levels deep. You want to swap your in-memory store for a real database, but there's no clean seam to grab onto.

I’ve run into all this while working on my scraper and other recent builds. And the pipeline pattern has made those problems manageable.

That's really what this is about. Not clean code for the sake of clean code. But about building something you can actually come back to, change, and grow without it fighting you the whole way.

The four ideas worth keeping:

Break into stages. Each stage does one thing.
Keep stages focused. If a stage is hard to name, it's probably doing too much.
Make parts swappable. Wire through interfaces, not concrete types.
Control concurrency. A worker pool, not unlimited goroutines.

Thinking in pipelines, I feel, makes a system easier to reason about. Which matters a lot when you’re in the middle of building something or making updates.

That's the pattern. Hope it's useful.

Where Does This Code Go? Layers in Go

Francis Awuor — Wed, 18 Mar 2026 19:20:41 +0000

Until not too long ago, when I wanted to change one thing in my code, I'd end up having to touch a bunch of other things. Or I'd be staring at a function trying to figure out why it's doing three completely different jobs.

Turns out there's a name for what I was doing wrong, and a pattern that fixes it.

This article is essentially what I wish someone had shown me earlier. We're going to walk through a way of organising your Go code into three layers: Service, Repository, and Delivery…

So that each part of your code has one job, and changing one thing doesn't ripple into everything else.

I'll be using two of my own projects as examples: a netcat-based group chat app, and a URL shortener.

What is Separation of Concerns?

Before we get into the layers, it's worth naming the idea behind all of this.

Separation of concerns basically means: each part of your code should have one clear job, and should know as little as possible about everything else. That's it.

The reason this matters is that when one part of your code knows too much about another part, they get tangled. And tangled code is code that's hard to change. You touch one thing and break another.

The three-layer pattern we're about to walk through is one concrete way to apply this idea in a Go backend. Each layer gets one job. Each layer talks to the next one through a clean boundary. That boundary is what keeps things from bleeding into each other.

The Three Layers

Here's the model we need to internalize before we get into the details:

Service - this is what your app does. Your business rules. The reason the app exists. If someone asked "what does this app actually do?", the answer lives here.

Repository - this is where your app stores and retrieves data. It doesn't care about business rules. It just reads and writes.

Delivery - this is how users interact with your app. An HTTP server, a CLI, a netcat listener. It receives input, calls the service, and returns a response. It's the outermost layer, the plumbing that connects your app to the outside world.

Each layer only talks to the one below it. Delivery calls the service. The service calls the repository. None of them reach past their neighbour, and that constraint is exactly what keeps your code clean.

We'll start with the most important one: the service layer.

The Service Layer

The service layer is the core of your app. It's where your business rules live (the logic that makes your app what it is, not just plumbing or storage.)

A good way to think about it: if someone asked "what does this app actually do?", the service layer is where you'd point them.

Here's what my group chat service handles:

Registering clients when they connect
Creating groups and letting clients join them
Broadcasting messages to everyone in a group
Unregistering clients when they disconnect
Keeping a chat history per group, and sending it to new clients when they join
Notifying everyone when someone joins or leaves

All of that is business logic. Those are decisions the app makes. Not the database, not the HTTP handler.

Here's the public surface of that service:

func (s *Service) Register(client *Client) error
func (s *Service) Unregister(client *Client)
func (s *Service) Broadcast(sender *Client, content string)
func (s *Service) Rename(client *Client, newName string) error
func (s *Service) JoinGroup(client *Client, groupName string) error

Notice what's missing. There's no mention of netcat, no mention of how the client is connected, no mention of how messages are being sent over the wire. The service just does the work. How users are actually reaching the app is someone else's problem, i.e., the delivery layer's problem, which we'll get to.

One thing worth pointing out about this particular service: it uses channels and a Run() loop internally for concurrency safety, which is pretty idiomatic Go for this kind of problem. That's an implementation detail though. The outside world just calls Register, Broadcast, JoinGroup and so on. It has no idea what's happening inside.

That's the point. The service's internals are its own business.

The Repository Layer

The repository layer handles storage. Reading, writing, that's it. The service doesn't care how data is stored. It just calls clean, intention-revealing methods and expects results back.

Here's the Store interface from the URL shortener:

type Store interface {
    Save(link ShortLink) error
    Get(id string) (ShortLink, error)
    IncrementHits(id string) error
}
}

The service calls Save. The service calls Get. It has no idea whether that's hitting a Postgres database or an in-memory map. That's the whole point of defining it as an interface.

And here's what makes that useful in practice. I actually have two implementations of this interface. An in-memory one:

func (store *MemStore) Save(link ShortLink) error { ... }
func (store *MemStore) Get(id string) (ShortLink, error) { ... }
func (store *MemStore) IncrementHits(id string) error { ... }

And a Postgres one:

func (store *PGStore) Save(link ShortLink) error { ... }
func (store *PGStore) Get(id string) (ShortLink, error) { ... }
func (store *PGStore) IncrementHits(id string) error { ... }

Both implement the same interface. Both are completely valid stores as far as the service is concerned. The service just calls Save. It doesn't know and doesn't care which one it's talking to. So you can easily swap one for another, or even swap in a mock version for tests.

We'll see how you actually swap between them in a minute. But first, the delivery layer.

The Delivery Layer

The delivery layer is the outermost layer. It's how users actually reach your app, e.g., via an HTTP server, a CLI, a netcat listener. Its job is simple: receive input, call the service, return a response.

That's it. It should contain no business logic.

A useful test for this: if you replaced your HTTP server with a CLI tomorrow, would you need to rewrite this code? If yes, that logic belongs in the service, not here.

Here's what a handler in my URL shortener looks like:

func (h *Handler) HandleShorten(w http.ResponseWriter, r *http.Request) {
    var req ShortenRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        http.Error(w, "invalid request", http.StatusBadRequest)
        return
    }

    link, err := h.shortener.Shorten(req.URL)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(link)
}

The handler decodes the request, calls h.shortener.Shorten(), and writes the response. That's all it does. It has no idea how the shortener generates a short code, which store it's using, or any of the logic involved. It just calls the service and handles the result.

Things the delivery layer should not be doing:

Generating short codes
Validating business rules (e.g., checking if a URL already exists)
Knowing what database you're using
Knowing how the service implements anything internally

If you catch yourself writing that kind of logic in a handler, it's a sign it belongs one layer down.

Interfaces: The Glue That Makes It Work

We've mentioned interfaces a couple of times now. Let's actually talk about why they matter here.

In Go, an interface defines what something can do, without caring about what it is. And that distinction is what makes the whole swappability idea practical rather than theoretical.

Here's the Store interface again:

type Store interface {
    Save(link ShortLink) error
    Get(id string) (ShortLink, error)
    IncrementHits(id string) error
}

The service depends on this interface. Not on MemStore. Not on PGStore. It just knows it's talking to something that can Save, Get, and IncrementHits. What that something actually is, is decided elsewhere.

Here's what the shortener (service) constructor looks like:

func NewShortener(store Store, generator IDGenerator) *Shortener {
    return &Shortener{store: store, generator: generator}
}

It takes a Store. Not a *MemStore. Not a *PGStore. A Store. So you can pass in either, and it'll work exactly the same.

This is sometimes called programming to an interface rather than an implementation. The service doesn't care what's behind the interface, and that's precisely why you can swap things out without touching the service at all.

Encapsulation: A Goal, Not a Side Effect

There's another benefit to this pattern that's worth naming explicitly, because it's easy to miss.

When each layer only exposes a clean interface to the layer above it, the internals of each layer are hidden. And that's not just a nice accident. I’d say it’s something we should be actively aiming for.

Here's why it matters practically: if your service hides its internals, you can refactor it freely. Change how you generate short codes, swap out your concurrency strategy, restructure your internal logic, etc. None of that affects the delivery layer, because the delivery layer only ever saw the interface. It never knew what was inside.

Same goes for the repository. You could migrate from Postgres to SQLite, and as long as your new implementation satisfies the Store interface, nothing else in your codebase needs to change.

Your teammates (or future you), can work on one layer without needing to understand or touch the others. I think that's a genuinely good thing to have, even on small projects.

Putting It All Together

Here's where it all clicks. Look at the main.go from the URL shortener:

// store := shorten.NewMemStore()
store := shorten.NewPGStore(sqlDB)
generator := shorten.NewBase62Generator()
shortener := shorten.NewShortener(store, generator)

mux := http.NewServeMux()
shorten.RegisterRoutes(mux, shortener)

server := http.Server{
    Addr:    ":8080",
    Handler: mux,
}

This is the wiring. main.go is where all three layers meet (and it's really the only place they meet.)

Notice the commented out line at the top. Switching from in-memory storage to Postgres is literally a one line change. That's the payoff of having defined a Store interface and having both implementations satisfy it.

The flow is:

main creates a store and passes it to the service
main creates the service and passes it to the delivery layer
The delivery layer handles requests and calls the service
The service does the work and calls the repository
Nobody reaches past their neighbour

Each layer was built independently. Each layer can be changed independently. And main is just the place that plugs them all together.

Conclusion

So to recap. Three layers, three jobs:

Service: what your app does
Repository: where your app stores data
Delivery: how users reach your app

Each layer talks to the one below it through a clean boundary. None of them know more than they need to. That's separation of concerns in practice.

The payoff isn't always obvious on a small project. But even on small projects, I've found it makes the code easier to reason about, easier to change, and easier for someone else to pick up. You always know where something belongs. And when you need to change something, you know exactly where to go.

It's one of those things that feels like a bit of extra work upfront, but saves you a lot of pain later.

A Beginner’s Guide to Testing in Go

Francis Awuor — Wed, 11 Feb 2026 19:33:37 +0000

I’ve been writing tests in Go for a few weeks now. And I’ve had more than a few moments of uncomfortable confusion.

So here’s a few things I wish someone had told me upfront.

Examples are in Go, but the ideas aren’t really language dependent.

Tests Enforce Contracts

Now right off the bat, you don’t want to get this wrong.

When writing tests, I’ve found the key thing to keep in mind is we should treat what we’re testing like a black box.

Give it specific inputs, expect specific outputs. For example, let’s take a look at function I had in a recent project (simplified). The project was a simple URL shortener I built.

func Create(url string) (shortCode string, err error)

The idea is, the function should take a URL string, e.g., https://exampleurl.com/this/is/really/long. That’s the input.

And it should return a short code that represents the long URL, e.g., bdcagl. Or an error if things go wrong. Those are the outputs.

That right there, that’s the contract. We’re saying if you give me a URL (a valid one), I should give you back a short code. Unless something goes wrong. In which case, I should give you an error.

This is what we test. So our test might look like this:

t.Run("Valid URL", func(t *testing.T) {
    url := "https://example.com"

    shortCode, err := Create(url)
    if err != nil {
        t.Fatalf("expected nil err, got %v", err) // if there's an unexpected error, fail the test
    }

    // Check that shortCode was generated
    if shortCode == "" {
        t.Error(`expected short code, got ""`) // after Creation, short code should not be empty
    }
})

Now the test above is what we call the happy path. It’s what we expect to happen when everything goes right. But what happens if something goes wrong?

Errors Are Part of the Contract Too

Of the outputs we expect, specific error cases are included.

What I mean is, if, for example, I pass in bad input, I should get back one error. But if something fails internally, I should get back a different error.

This is part of the contract. And it took me quite a while to realize.

Cause see what I’d often do is, in cases where I expected an error, I’d simply check for the presence of errors, e.g.,

url := "https:invalid-url//example./com" // invalid input should fail and return an error

shortCode, err := Create(url)
if err == nil {
        t.Fatalf("expected error, got nil") // if there's no error where you expect one, fail the test
    }

This is not enough!

I’ve since found that a better way to handle this, would be to check for specific errors, e.g,

if !errors.Is(err, ErrInvalidURL) { // Check for invalid url error
        t.Fatalf("expected ErrInvalidURL, got %v", err)
}

The contract should specify what error you get back.

NOTE: Testing error cases is just as important as testing happy paths. DO NOT sleep on it.

And we’re not done yet. Cause important as it is to have this mental model of contracts, it’s even more essential to understand how to structure our tests.

But in order to understand that, I have to first clear up what a unit test is. Cause it is not what I thought it was.

What Even Is a Unit?

For this section, it’s useful to quickly outline a commonly recommended structure for backend systems:

(We organize our HTTP server into layers)

HTTP Request
     |
   v
Handlers → receive HTTP requests and send responses
   |
   v
Services → apply business rules and coordinate work
   |
   v
Repository → reads and writes data in the database
   |
   v
Database

Now back to unit tests.

You might have heard of unit tests before. And if not, you’ll be glad you read this.

Cause see for a long time, when I heard “unit test”, I thought that referred to testing a function.

So if I had three functions, I thought that was three separate units to test.

I was wrong.

In our code, a unit is actually a “cohesive chunk of behavior, with one responsibility, that can be reasoned about independently.”

Which sounds fancy, but it really just means, if I have a service like this:

type Shortener struct {
    store Store // where you store the generated short code and its associated long URL
    gen   Generator // consider this a function that generates the short code
}

func (s *Shortener) Create(url string) (string, error) {
    // generates short code and saves it
}

func (s *Shortener) Resolve(shortCode string) (string, error) {
    // looks up original URL
}

func (s *Shortener) Stats(shortCode string) (int, error) {
    // returns hit count for a short code
}

Then that entire struct — the Shortener plus all its public methods (Create, Resolve , Stats) is ONE unit.

Not three units. One.

So when I write tests for Create, Resolve, and Stats, I’m just testing different behaviors of the same unit.

A way to say it that helped me understand better is:

A unit is the smallest part of your code where you can say: “If this breaks, I know exactly what kind of problem it is. Failures don’t blur together.”

This matters because once I understood this, test organization made way more sense.

So let’s get to it shall we? How to structure our tests.

Good Test Structure

See after writing a bunch of messy tests, I found a structure that works:

Setup → Subject → Assertion

Setup

Here you get everything ready for the test.

Say you want to test the Create function above. Well you need a generator, and a store. The Shortener’s Create function uses the generator to generate short codes, and the store to store the generated codes alongside the original URLs. This is the setup stage. You have to prepare what the element being tested needs, e.g.,:

// Setup
store := NewMockStore()
gen := NewMockGenerator()
service := NewShortener(store, gen)

Subject

The thing you’re actually testing. Call the method, trigger the behavior, e.g.,

// Subject
shortCode, err := service.Create("https://example.com")

Assertion

Verify the contract holds. Check outputs, check errors, check side effects. (Side effects are tricky though. We’ll talk about them in a bit)

Example:

// Assertion
if err != nil {
    t.Fatalf("Expected no error, got %v", err)
}

if shortCode != "abc123" {
    t.Errorf("Expected abc123, got %s", shortCode)
}

And one critical thing to keep in mind (trust me, I made this mistake quite a few times): If setup fails, fail the test immediately. E.g.,:

func TestCreate(t *testing.T) {
    store := NewMockStore()
    if store == nil {
        t.Fatal("Failed to create mock store") // t.Fatal() stops the test here
    }

    service := NewShortener(store, mockGenerator)
    if service == nil {
        t.Fatal("Failed to create service") // stops test here
    }

    // Now do the actual test...
}

There’s a simple reason why, i.e., if setup fails and you keep going, you’ll likely get misleading errors. The test will fail at unexpected points, and it’ll be a nightmare to debug.

And here’s where the bit about what a unit is gets particularly interesting.

See while working on my shortener, I had cases like this:

func TestResolve(t *testing.T) {
    service := NewShortener(mockStore, mockGen)

    // SEE THIS? We need to use Create for setup, cause to resolve (i.e., get the URL a short code points to), we need to have created the short code
    shortCode, err := service.Create("https://example.com")
    if err != nil {
        t.Fatalf("Setup failed: %v", err) // fail fast if setup fails
    }

    // Now test Resolve
    url, err := service.Resolve(shortCode)
    if err != nil {
        t.Errorf("Resolve failed: %v", err)
    }

    if url != "https://example.com" {
        t.Errorf("Expected https://example.com, got %s", url)
    }
}

It’s a case where we have to use the Create function to setup tests for the Resolve function. Because to resolve (i.e., get the URL a short code points to), we need to have created the short code.

Which seems reasonable enough. Until we, for example, go a level up and have a handler that needs another handler for setup. Here’s a snippet:

func TestHandleRedirect_OK(t *testing.T) {
// Setup
    // We would call HandleShorten() here, which creates a short code given the URL to shorten
    handler.HandleShorten(rr, req)

// Subject (the thing we're testing)
// Create a mock request specifically for testing
        req := httptest.NewRequest(http.MethodGet, "/"+shortCode, nil) // NOTICE the short code?
    rr := httptest.NewRecorder()

// Given a short code, HandleRedirect redirects to the URL the short code represents. It internally calls Resolve() to get this done.
    handler.HandleRedirect(rr, req)

    res := rr.Result()
    res.Body.Close()

    if res.StatusCode != http.StatusFound {
        t.Fatalf("expected status 302, got %d", res.StatusCode)
    }
}

Like the test for Resolve() earlier, we need the short code in order to test HandleRedirect. But in order to get the short code, we’d either have to call another handler, HandleShorten , to generate the short code for us…

Or we’d have to reach into the service and call service.Create().

So which approach is better?

Using Other Functions for Test Setup

The key principle I found to deal with these kinds of test setup issues is: A test should not depend on the behavior of another unit.

The key issue here, is unit boundaries. (See? Units came back)

See calling HandleShorten to set up HandleRedirect might feel symmetrical, but it’s actually the wrong move.

This is cause handlers are separate units.

If the HandleRedirect test failed, you wouldn’t be able to easily tell what broke. Was it HandleRedirect or HandleShorten? It messes with failure attribution.

HandleRedirect should not have to depend on HandleShorten to work.

The better approach, would be to reach down, not sideways.

func TestHandleRedirect_OK(t *testing.T) {
    service := NewShortener(mockStore, mockGen)
    handler := NewHandler(service)

    // Setup: reach down to the service
    shortCode, err := service.Create("https://example.com") // We have Create from the service setting up HandleRedirect
    if err != nil {
        t.Fatalf("Setup failed: %v", err)
    }

    // Subject
    req := httptest.NewRequest(http.MethodGet, "/"+shortCode, nil)
    rr := httptest.NewRecorder()

    handler.HandleRedirect(rr, req)

    res := rr.Result()
    res.Body.Close()

    if res.StatusCode != http.StatusFound {
        t.Fatalf("expected status 302, got %d", res.StatusCode)
    }
}

This is better because:

You’re testing one handler
Setup uses lower-level implementation
No handler depends on another handler’s behavior
If the test fails, we know where to look

And if service.Create breaks, the handler test should fail. Because in the real app, the handler relies on the service. It’s honest dependency.

However, it’s pretty important to note that the earlier example of using Create to set up Resolve, is different.

That’s perfectly fine, because

Create and Resolve belong to the same unit.
If Create is broke, Resolve is broken too.

A single service is a single unit. Handlers don’t have that relationship.

A “rule of thumb” of sorts that helps me with this is (and this ties back to the backend layers idea):

A test can depend on lower layers, but it shouldn’t depend on same layer entities unless it’s from the same unit.

However do note that an exception to this is the Service layer. For the service layer, you don’t want to call lower layer functions (from repository/db layer) directly for setup in your service tests, cause you’d be bypassing business rules, which is the core of your application. It’s at a base level, what your application should do.

And now one last thing I mustn’t forget to mention: Side Effects.

Side Effects Are Tricky

I say they’re tricky cause, a side effect is something your function changes internally, that’s not part of its return value.

My service.Resolve function, for example, internally increments a hits counter for a URL every time someone requests that URL.

“hits”, however, is not part of its return values, so you have to observe or test hits separately, for example by creating a separate function for metrics (e.g., my service.Stats function), through database queries, etc.

Key Takeaways

A unit is a cohesive module with a single responsibility, not a single function. (Think, “if something fails, can I tell what kind of problem it is?” - Clear failure attribution)
Tests enforce contracts - Specific inputs → Specific outputs
A reasonable test structure: Setup → Subject → Assertion
Fail fast on setup failures (t.Fatal() ) to avoid misleading errors
Side effects need indirect observation