Go on

Lesson 10: Zero Values Are Useful — Go types that work before you touch them

Mon, 09 Mar 2026 00:00:00 +0000

In most languages, a freshly declared variable is either uninitialized garbage you can’t touch safely, or it needs a constructor call before it does anything useful. Go takes a different approach: every variable always has a value. When you don’t provide one, Go assigns the zero value for the type. What makes this interesting is that Go’s standard library is full of types designed so that their zero value is immediately useful — no constructor required.

Lesson 12: Value vs Pointer Receivers — The method that silently does nothing

Mon, 23 Feb 2026 00:00:00 +0000

Value vs pointer receivers is one of those topics that seems like a style preference until it silently breaks your program. The tell is a method that looks like it mutates a struct, compiles without complaint, but the mutations simply don’t persist. You add a log line, the value is right inside the method — and wrong the moment the method returns.

The Problem

A value receiver operates on a copy. Every time you call the method, Go copies the entire struct and passes the copy to the method. Mutations happen on the copy, which gets discarded when the method returns. The original is untouched.

Lesson 28: Production Concurrency Architecture — Putting it all together

Fri, 20 Feb 2026 00:00:00 +0000

This is the lesson I wish existed when I started. Not “here’s how channels work” or “here’s a simple worker pool” — but the full picture: how you take everything you’ve learned about goroutines, channels, contexts, rate limiting, idempotency, observability, and graceful shutdown and assemble it into a service that actually belongs in production. One that handles failures, recovers gracefully, doesn’t leak resources, and gives you the visibility to understand what it’s doing.

Lesson 9: Testing with Real Databases — Mocking sql.DB is lying to yourself

Wed, 18 Feb 2026 00:00:00 +0000

For years, the standard advice for testing Go database code was to use sqlmock — a library that intercepts database calls and lets you assert which queries were run. I used it for a while. Then I started finding production bugs that my sqlmock tests were actively hiding: constraint violations that only happen with real Postgres, query plan differences, JSON operator behavior, NULL handling edge cases, transaction isolation behavior. sqlmock tests were passing while the same code was failing in production. That’s worse than no tests at all.

Lesson 19: Table-Driven Tests — One test function, fifty test cases

Mon, 09 Feb 2026 00:00:00 +0000

Most engineers know to write tests. Fewer think about how the test code itself should scale. When you need to cover thirty input variations of a function, duplicating the test body thirty times produces something that’s painful to read, painful to extend, and painful to debug when it fails. Table-driven tests are the pattern that scales. A slice of cases, one loop — your test code stays as clean as your production code.

Lesson 27: Idempotency in Concurrent Systems — Assume everything runs twice

Sun, 08 Feb 2026 00:00:00 +0000

Every distributed system I’ve worked on eventually ran something twice. A retry after a timeout. A duplicate webhook delivery. A job that got processed by two workers simultaneously because of a clock skew issue in the claim timeout logic. A user who double-clicked a submit button. Systems aren’t gentle about this — they don’t ask “are you sure?” before running your code again. They just run it. The question isn’t whether your code will ever run twice. It’s whether running it twice causes a problem.

Lesson 8: Migrations Without Downtime — ALTER TABLE can lock your entire database

Tue, 27 Jan 2026 00:00:00 +0000

The first time I caused a production outage with a database migration, I was adding a NOT NULL column to a table. The migration looked innocent. It ran fine on staging with 1,000 rows. In production with 40 million rows, it locked the entire table for 11 minutes while Postgres rewrote every row. Every write to that table failed with a lock timeout. We rolled back the app but couldn’t roll back the migration. It was a terrible morning.

Lesson 22: Small Packages Win — One package, one job

Mon, 26 Jan 2026 00:00:00 +0000

There is a particular kind of Go codebase that’s immediately recognizable as written by someone still thinking in another language. It has a utils package. Maybe a common package. Possibly a helpers folder with a file called misc.go. Every function that doesn’t obviously belong somewhere ends up there, and over time these packages become the junk drawers of the codebase — bloated, unfocused, and imported by everything.

Go has a better way. Small packages with narrow responsibilities. One package, one idea.

Lesson 26: Safe Background Jobs in Web Servers — Don''t spawn goroutines in handlers

Fri, 23 Jan 2026 00:00:00 +0000

The first time I saw go func() inside an HTTP handler, I thought it was clever. Fire off the slow work in the background, respond to the client fast, everybody wins. Then I watched what happened when we deployed a new version: the server started shutting down, half the background goroutines got killed mid-operation, we had partial writes in the database and no way to know which ones had completed. The “clever” optimization had created a correctness nightmare. The real problem wasn’t the goroutine — it was that it was invisible to the server’s shutdown lifecycle.

Lesson 25: Observability for Concurrency — You can''t fix what you can''t see

Thu, 15 Jan 2026 00:00:00 +0000

The goroutine leak doesn’t announce itself. It just slowly inflates your memory graph — 50MB, 80MB, 150MB — until either your alerting fires or the OOM killer shows up. Then you’re staring at a core dump or (if you’re lucky) a live process trying to figure out which of the 10,000 goroutines running in your service is the culprit. I’ve been there. It’s not fun. The difference between spending 20 minutes diagnosing a leak and spending 4 hours diagnosing a leak is almost entirely whether you invested in observability before the incident.

Lesson 7: Slices Are Views, Not Arrays — Mutations you didn''t ask for

Mon, 12 Jan 2026 00:00:00 +0000

If you’re coming from Python, JavaScript, or Java, slices look familiar enough that you’ll assume you understand them. That assumption will hold right up until something mutates data you didn’t expect to be mutable, or a change you made inside a function mysteriously doesn’t show up outside it. Both surprises have the same root cause: a slice is not a copy of its data, it’s a window into an underlying array that may be shared with other slices.

Lesson 24: Testing Concurrent Code — Flaky tests mean flaky design

Tue, 30 Dec 2025 00:00:00 +0000

A flaky test is a lie your codebase tells you. It says “this sometimes works and sometimes doesn’t” and if you’re honest with yourself, you already know what that means: there’s a race condition somewhere, and the test is just unlucky enough to expose it occasionally. I used to mark flaky tests with t.Skip("flaky, fix later") and move on. I stopped doing that when a race condition that a flaky test was hinting at caused a double-charge bug in production. Now I treat every flaky test as a production incident waiting to happen.

Lesson 25: Simplicity Is a Language Feature — Why Go says no so you can ship

Mon, 29 Dec 2025 00:00:00 +0000

Every Go design decision that looks like a missing feature is actually a deliberate choice to remove cognitive overhead. No method overloading. No implicit conversions. One canonical formatter. Generics that arrived late and deliberately. Go’s simplicity is not an accident — it’s a feature, and one that pays compounding dividends as a codebase and team grow.

The Problem

Languages that offer maximum expressiveness also offer maximum inconsistency. In Java or C++, method overloading sounds convenient:

Lesson 7: The N+1 Problem — One query per row is a performance bug

Thu, 25 Dec 2025 00:00:00 +0000

The N+1 problem is the most common database performance issue I find when reviewing Go code, and it’s especially sneaky because it looks totally fine in development. You have a list of 10 users, you fetch their orders, 11 queries, no problem. You deploy to production, the table has 50,000 users, your endpoint suddenly takes 40 seconds, and you get a 3am page. The queries were always there — you just didn’t notice them until the data grew.

Lesson 23: Distributed vs Local Concurrency — Channels don''t cross process boundaries

Mon, 22 Dec 2025 00:00:00 +0000

There’s a particular kind of confidence that comes after you’ve spent a few months writing Go. You’ve learned channels, you understand the happens-before guarantees, you’ve built a worker pool that hums along beautifully. Then someone says “we need to scale this across multiple pods” and you think: easy, I’ll just make the channels bigger. That thought has caused more production incidents than I care to remember — including one where we lost about 3,000 job records because a pod restarted mid-processing and nobody had thought about what “at-least-once delivery” actually means.

Lesson 17: select Is Elegant — Waiting on multiple futures without blocking

Mon, 15 Dec 2025 00:00:00 +0000

Every non-trivial concurrent program eventually needs to wait on more than one thing at a time. Maybe you’re waiting on a job channel but also need to respond to cancellation. Maybe you want to fetch from a channel but bail out after a timeout. Sequential channel receives can’t do this — they block on one thing and miss everything else. select is the solution, and it’s more powerful than it looks.

Lesson 22: Rate Limiting and Load Shedding — Say no before you fall over

Wed, 10 Dec 2025 00:00:00 +0000

The most honest thing a server can do is say “no.” Not crash, not time out after 30 seconds, not queue work indefinitely until memory explodes — just return a clean 503 and let the caller decide what to do. I spent a long time thinking rate limiting was about protecting users from themselves. Then I got paged at midnight because a misbehaving client hammered an endpoint, the service queued everything politely, RAM climbed to the ceiling, and the process died. The fix wasn’t more memory. It was teaching the service to refuse work it couldn’t handle.

Lesson 6: Context with Database Queries — Every query needs a timeout

Wed, 03 Dec 2025 00:00:00 +0000

We once had a query that ran for 47 minutes. I’m not joking. A reporting query that worked fine on the test dataset decided to do a full sequential scan on a 200M-row table in production because someone dropped an index by accident the night before. The query just ran. And ran. And ran. The connection was held the whole time, blocking the pool. New requests started queuing. Within 10 minutes, the service was effectively down — not because of an error, but because every database connection was held by queries waiting for that one slow one to finish.

Lesson 9: range Gotchas — The loop variable that bit every Go team

Mon, 01 Dec 2025 00:00:00 +0000

range looks harmless. Index and value, loop over a slice — what could go wrong? Quite a bit, it turns out. Some of the most insidious bugs I’ve seen in Go codebases come from assumptions about range that seem obvious but are wrong. One was painful enough that Go 1.22 changed the fundamental loop semantics to fix it. Let’s walk through each gotcha and the correct pattern to use.

The Problem

The classic range bug — the one that famously broke production code at teams large and small for years — is the loop variable capture problem. In Go versions before 1.22, every iteration of a range loop reused the same loop variable. Taking its address multiple times gave you the same address every time.

Lesson 21: Supervisor Patterns — Let it crash, then restart it

Tue, 25 Nov 2025 00:00:00 +0000

Erlang got famous for the “let it crash” philosophy. The idea is that trying to handle every possible error in every possible place produces fragile, complicated code. It’s often better to let a process crash cleanly and have a supervisor restart it. The supervisor knows how to bring the process back to a known-good state. The process itself just needs to do its job and fail fast when something’s wrong.

Lesson 24: Prefer Plain Structs — Boring code is correct code

Mon, 17 Nov 2025 00:00:00 +0000

There is a particular brand of cleverness that feels deeply satisfying to write and deeply painful to maintain. The AbstractServiceProviderFactory. The builder that returns a builder that configures a builder. The generic interface so abstract it could model anything and therefore models nothing well. Go’s culture pushes back hard against this tendency, and for good reason: I’ve seen more bugs traced to abstraction layers than to simple structs.

The Problem

The most common form of over-engineering in Go is attempting to import Java-style construction patterns. Go doesn’t have constructors, so engineers invent them — and the result is code that’s harder to configure, not easier:

Lesson 20: Profiling Contention — pprof knows where your goroutines sleep

Thu, 13 Nov 2025 00:00:00 +0000

You’ve added goroutines, you’ve got worker pools, you’ve written careful concurrent code — and the service is still slower than expected. Maybe goroutine count is climbing in your metrics dashboard. Maybe p99 latency has a long tail you can’t explain. Maybe a throughput test plateaus at 40% of what you thought the hardware should support.

This is where guessing stops and profiling starts. Go ships world-class concurrency profiling tools in the standard library — mutex profiles, block profiles, goroutine dumps, and the execution tracer. Most engineers know about the CPU and memory profiler. Far fewer use the concurrency-specific profiles, which is a shame because they find the exact thing that’s wrong in minutes instead of days.

Lesson 11: Nil Slice vs Empty Slice — Same length, different meaning

Mon, 03 Nov 2025 00:00:00 +0000

Go has two ways to have a slice with zero elements, and they are not the same thing. Developers coming from Python, Ruby, or JavaScript expect an empty collection to just be an empty collection. In Go, the distinction between a nil slice and an empty slice is subtle enough that you can miss it for months — right up until a frontend engineer files a bug because your API is returning null instead of [].

Lesson 19: Ordering vs Throughput — You can have fast or ordered, pick one

Fri, 31 Oct 2025 00:00:00 +0000

Here’s a tension that comes up in almost every real concurrent system: you want to process things fast, which means doing them in parallel, but the output needs to come out in the same order the input arrived. These two goals are in direct conflict. Parallel execution means things finish in unpredictable order. Ordered output means you have to wait for the slowest thing in each batch.

The engineers who understand this tension build systems that make the trade-off explicitly. The engineers who don’t notice it build systems that either throttle themselves to single-goroutine throughput “to preserve order” or silently return results in the wrong order and wonder why tests fail non-deterministically.

Lesson 5: sqlc vs ORM vs Raw SQL — Pick your tradeoff, not your religion

Wed, 29 Oct 2025 00:00:00 +0000

Every time someone asks “should I use GORM or raw SQL?” a flame war breaks out. I’ve been on both sides of that argument, and I’ve shipped production systems using all four approaches — raw SQL, GORM, sqlc, and Ent. My opinion now is boring: each one is the right choice in a specific context, and none of them is universally correct. The question isn’t which one is best, it’s which tradeoffs you’re signing up for.

Lesson 18: sync.Mutex Is Often Simpler — Not everything needs a channel

Mon, 20 Oct 2025 00:00:00 +0000

After you absorb the Go concurrency philosophy — share memory by communicating — there’s a temptation to reach for channels every time two goroutines need to share data. Resist that. Channels are for coordination and ownership transfer. For shared mutable state that multiple goroutines read and write, a mutex is usually clearer, simpler, and faster. Using a channel where a mutex belongs is one of those things that looks idiomatic but isn’t.

Lesson 18: Backpressure Design — Slow down or blow up

Sun, 19 Oct 2025 00:00:00 +0000

Every system has a throughput ceiling. The question isn’t whether your service can be overwhelmed — it can. The question is what happens when it is. Does it slow down gracefully, maintaining correctness and giving the caller a clear signal? Or does it blow up — OOM-killed, goroutines piling up, latency spiking to infinity while requests pile up in an unbounded queue?

Backpressure is the mechanism that answers that question. It’s how a component communicates to its upstream: “I’m full — slow down.” Without it, fast producers eat slow consumers alive. In Go, backpressure is naturally expressed through blocking channel sends — and understanding when to block versus when to drop is one of the more interesting design decisions in concurrent systems.

Lesson 17: Go Scheduler Behavior — M:N scheduling is not magic

Wed, 08 Oct 2025 00:00:00 +0000

Most Go developers write concurrent code for years without thinking about the scheduler. That’s by design — the scheduler is supposed to be invisible. But eventually you’ll hit a situation where goroutines aren’t running when you expect them to, CPU cores are idle while goroutines pile up, or a CPU-bound workload is somehow slower with more goroutines. At that point you need a mental model of what’s actually happening under the hood.

Lesson 3: Multiple Return Values — Go functions don't hide their failures

Mon, 06 Oct 2025 00:00:00 +0000

In most languages, a function returns one thing and communicates failure through a side channel — an exception, a null, a magic sentinel value. Go’s approach is different: functions can return multiple values, and the convention is to use that to make failure explicit in the signature itself. Once you’ve used it for a while, hiding failures in side channels starts to feel dishonest.

The Problem

Sentinel values are the old-school way to signal failure from a function. You pick some value that “shouldn’t” appear in normal results and treat it as an error signal:

Lesson 4: The Repository Pattern — Sometimes a function is enough

Thu, 02 Oct 2025 00:00:00 +0000

The repository pattern is one of those ideas that sounds great in an architecture talk and causes real pain when applied indiscriminately to a Go codebase. I’ve seen teams add a UserRepository interface with five methods, a concrete postgresUserRepository implementation, and a mockUserRepository for tests — and then wonder why everything takes three times as long to write. I’ve also seen teams skip the pattern entirely and end up with *sql.DB threaded through 40 different functions, impossible to test without a real database.

Lesson 29: sync.Cond — The coordination primitive nobody teaches

Wed, 01 Oct 2025 00:00:00 +0000

Every Go concurrency course covers goroutines, channels, mutexes, WaitGroups, and maybe semaphores. Very few touch sync.Cond. It’s either treated as advanced or dismissed as unnecessary because “just use channels.” But there’s a whole class of coordination problem where channels are the wrong tool and sync.Cond is exactly right. Once you see the pattern, you’ll recognize it everywhere — and you’ll stop reaching for time.Sleep polling loops when you shouldn’t.

This is a bonus lesson. Not because the topic is minor, but because it builds on mutexes (Lesson 6) and you really need to understand lock ownership before sync.Cond clicks.

Lesson 16: Atomic Operations — Lock-free when you can, mutex when you must

Mon, 29 Sep 2025 00:00:00 +0000

The first time I looked at sync/atomic, it felt like a niche tool for systems programmers writing lock-free data structures. Turns out it’s one of the most practically useful packages in the standard library — and most Go developers reach for it way too late, after they’ve already built something with a mutex and then profiled it into submission.

Atomic operations are CPU-level instructions that read or modify memory as a single, indivisible unit. There’s no scheduler window between the read and the write. That means multiple goroutines can operate on the same memory location without a lock — and without any blocking. When your shared state is a counter, a flag, or a single configuration value, atomics are almost always the right tool.

Lesson 13: iota for Enums — Constants that count themselves

Mon, 22 Sep 2025 00:00:00 +0000

Go doesn’t have a built-in enum keyword. What it has is iota, a constant counter that resets to zero at the start of each const block and increments with every constant declaration. It sounds underwhelming. In practice it gives you typed enums, bitmask permissions, and self-maintaining constant sequences — all without any runtime overhead.

The Problem

The naive approach to enums in Go is plain integer constants or string constants. Both work, but neither gives you type safety:

Lesson 15: Semaphores for Concurrency Limits — A channel with a size is a semaphore

Thu, 18 Sep 2025 00:00:00 +0000

There’s a class of production bugs I see over and over — and the cause is almost always the same: nothing is telling the program to slow down. A spike in traffic arrives, every goroutine blasts outbound, and suddenly you’ve got five hundred simultaneous connections against a Postgres instance that’s configured for a hundred. The database starts rejecting connections. The application throws errors. Everyone’s paged at 2am.

The fix isn’t complicated. It’s a semaphore — a primitive that limits how many concurrent operations are in flight at once. Go doesn’t ship a dedicated semaphore type, but it doesn’t need to. A buffered channel of the right size is a semaphore, and that insight unlocks a whole class of resource-limiting patterns.

Lesson 20: internal Package Is Underrated — Compiler-enforced privacy for free

Mon, 08 Sep 2025 00:00:00 +0000

Go has two visibility levels: exported (starts with a capital letter) and unexported (doesn’t). Most engineers use only these two. But there’s a third option that the language gives you for free, and it’s more useful than most people realize. The internal directory enforces that certain packages can only be imported by code within your own module — and the compiler, not documentation or convention, does the enforcing.

Exported symbols are API commitments. Once something is exported and external code is depending on it, changing it is a breaking change. The internal package is the escape hatch: share code across multiple packages in your own codebase without accidentally publishing an API surface you’ll have to maintain forever.

Lesson 3: Transactions That Don't Bite — Begin, defer rollback, commit

Sun, 07 Sep 2025 00:00:00 +0000

Transactions are the part of database programming where “it’s fine most of the time” really isn’t good enough. A buggy SELECT just returns wrong data. A buggy transaction can leave your database in a half-written state — an order placed without inventory decremented, money debited without the transfer completing, a user created without their profile record. The bugs are subtle, often don’t manifest in testing, and only show up in production when two things happen at the same time.

Lesson 14: errgroup for Structured Concurrency — All succeed or all cancel

Tue, 02 Sep 2025 00:00:00 +0000

There’s a pattern that comes up constantly in backend services: make N concurrent calls, collect all their results, and if any one of them fails, cancel the rest and return the error. This is the “all succeed or all cancel” pattern — and before errgroup, implementing it correctly required a non-trivial amount of boilerplate involving WaitGroup, error channels, and manual context cancellation. People got it wrong often enough that errgroup was created specifically to handle it.

Lesson 13: Timeouts Everywhere — Unbounded waits are production bugs

Tue, 26 Aug 2025 00:00:00 +0000

I have a strongly held opinion about timeouts: if you’re making a network call, a database query, or waiting on any external resource without a timeout, you’ve written a production bug. It just hasn’t fired yet. The network will eventually hang. The database will eventually have a slow query. The external API will eventually stop responding. And when it does, your goroutine will wait. And wait. And wait — holding a connection, a file descriptor, a slot in your worker pool — until the process runs out of resources or someone restarts it.

Lesson 5: Implicit Interfaces — The best decoupling you'll never declare

Mon, 25 Aug 2025 00:00:00 +0000

In Java or C#, you declare that a class implements an interface. You write implements Runnable, and the compiler ties that class to that interface forever. Go doesn’t work that way. A type satisfies an interface the moment it has the right methods — no declaration, no explicit relationship. This sounds like a minor syntactic difference, but it changes how you design systems in ways that compound over time.

The Problem

When interfaces are declared by the implementor (the Java way), you end up with a few recurring problems.

Lesson 12: Leak Prevention — Every goroutine must have an exit

Fri, 15 Aug 2025 00:00:00 +0000

Goroutine leaks are the memory leaks of concurrent Go. They’re slow, invisible, and tend to surface only under load — or worse, only after days of continuous running when the service has accumulated tens of thousands of stuck goroutines. I’ve debugged two production incidents that traced back to leaks in code that had been in production for months, completely unnoticed during normal load.

The root cause is almost always the same: someone started a goroutine and didn’t give it a way to exit. Not a way to exit eventually — a way to exit in every possible code path.

Lesson 15: Goroutines Are Cheap, Not Free — 2KB that can eat your server

Mon, 11 Aug 2025 00:00:00 +0000

“Goroutines are cheap” is something you read in every Go introduction. It’s true. A goroutine starts with a 2KB stack and the runtime handles scheduling. Spinning up a thousand of them is trivial. The part the introductions leave out is that “cheap” is not “free,” and goroutines that you start and never stop are a leak — one that doesn’t crash your program, just slowly eats your memory and degrades your scheduler until something gives.

Lesson 2: Connection Pool Tuning — Your pool config is probably wrong

Fri, 08 Aug 2025 00:00:00 +0000

Here’s a scenario that played out for me once: service is running fine for weeks, then we double traffic, and suddenly requests start timing out. Not all of them — maybe 10%. The logs show pq: sorry, too many clients already. Postgres is refusing connections. But we have a connection pool — that’s the whole point, right? Why is Postgres seeing more connections than it can handle?

Because database/sql’s default pool settings are almost certainly wrong for production, and most people never change them.

Lesson 11: Graceful Shutdown — Stop accepting, finish what you started

Sun, 03 Aug 2025 00:00:00 +0000

Most Go services handle startup carefully and shutdown carelessly. The startup code has retries, health checks, dependency validation. The shutdown code is os.Exit(0) or — if the developer was feeling generous — nothing at all, just letting the process get killed. That’s how you get dropped HTTP connections, half-written database records, uncommitted Kafka offsets, and on-call alerts at 3am.

Graceful shutdown has one principle: stop accepting new work, finish what you already started. That’s it. But implementing it correctly requires knowing the shutdown order, wiring up OS signals properly, and draining workers before pulling the plug.

Lesson 23: Error Values, Not Exceptions — Errors you can actually inspect

Mon, 28 Jul 2025 00:00:00 +0000

In most languages, errors are events — they get thrown, they propagate up the call stack, and you catch them somewhere above. Go rejects this model entirely. In Go, an error is a value, just like an integer or a string. You pass it around, inspect it, wrap it with context, and check it right where it happens. Ignore it and your code doesn’t crash loudly; it quietly does the wrong thing, and you’ll find out at the worst possible moment.

Lesson 10: Pipelines and Stage Isolation — Each stage owns its output channel

Thu, 17 Jul 2025 00:00:00 +0000

A pipeline is how you turn a stream of work into a sequence of transformations without writing a single monolithic function that does everything. Each stage reads from one channel, does its thing, and writes to another. Stages compose. Stages are independently testable. And because each stage runs concurrently with every other stage, the whole pipeline processes multiple items simultaneously — like an assembly line rather than a factory worker doing each product start to finish.

Lesson 1: Error Handling — Your code is lying if it ignores errors

Mon, 14 Jul 2025 00:00:00 +0000

If you’re coming from Python, Java, or JavaScript, Go’s error handling will feel strange at first. There’s no try/catch. No exceptions bubbling up the call stack. Instead, errors are just values — and you deal with them right where they happen. Ignore them and your code doesn’t crash loudly; it quietly lies to you, and you won’t find out until 2am when production is on fire.

The Problem

The blank identifier _ is the most dangerous character in Go. Here’s what it looks like when engineers first start writing Go:

Lesson 6: Agent Architectures — Building autonomous agents in Go

Thu, 10 Jul 2025 00:00:00 +0000

An agent is a loop: observe, think, act, repeat. The LLM is the “think” step — it decides what to do next given the current state. Your Go code handles “observe” (gathering context), “act” (executing tool calls), and the loop control that keeps everything running. I’ve built agents that write and execute code, agents that browse the web, and agents that orchestrate multi-step data pipelines. The underlying architecture is always the same few patterns, and Go’s concurrency makes the execution layer clean and fast.

Lesson 9: Worker Pools — Bounded concurrency or bust

Thu, 10 Jul 2025 00:00:00 +0000

Production Go codebases that run fine in staging will sometimes crater under real traffic. More often than not, the cause is unbounded goroutine creation. Some background job processor spins up a goroutine per message. The queue backs up. Suddenly there are 50,000 goroutines fighting for CPU, exhausting file descriptors, allocating gigabytes of stack space. The service falls over. The incident post-mortem says “we didn’t expect this load.” The real cause: no worker pool.

Lesson 1: database/sql Done Right — The stdlib is better than you think

Tue, 08 Jul 2025 00:00:00 +0000

I spent a long time reaching for third-party database libraries in Go before I actually read the database/sql docs. When I finally did, I was embarrassed — the stdlib had everything I needed and I’d been adding dependencies for no reason. The problem isn’t that database/sql is limited. The problem is that it has a handful of non-obvious behaviors that, if you don’t know about them, will burn you in production. Once you internalize those, you’ll write better database code than most people using ORMs.

Lesson 8: strings and bytes Builders — Stop concatenating in loops

Sat, 05 Jul 2025 00:00:00 +0000

String concatenation with + is one of the most common performance bugs I see in Go code reviews. Not because developers are careless, but because the bug is invisible — the code looks clean and correct. result += piece is obvious. The quadratic memory behavior that follows is not.

The strings and bytes packages are where Go provides the right tools for this job. strings.Builder and bytes.Buffer are both efficient for incremental string construction, but they’re not the same type and the choice between them matters in specific cases. Beyond building strings, these packages contain functions that have non-obvious but significant performance implications: strings.Contains vs strings.Index, strings.Split vs strings.SplitN, and the ones people reach for that they shouldn’t.

Lesson 10: Over-Engineering CRUD — Not every API needs a hexagonal architecture

Wed, 02 Jul 2025 00:00:00 +0000

There is a category of service that I have built many times and will build many more times: an API that creates, reads, updates, and deletes records in a relational database, with some validation and authentication. There is nothing glamorous about it, and there is nothing architecturally complex about it either. The correct implementation is straightforward, fast to build, easy to test, and easy to read. The over-engineered implementation has event sourcing, CQRS, a message bus, six layers of abstraction, and takes three months to build something that the straightforward implementation would have shipped in two weeks.

Lesson 2: defer for Cleanup — Put the cleanup next to the mess

Mon, 30 Jun 2025 00:00:00 +0000

Every time you open a file, acquire a lock, or start a database transaction, you’ve created a resource that needs to be released when you’re done with it. In most languages you manage this with finally blocks or RAII patterns. Miss one cleanup and you’ve got a leak. Go has defer, and once it clicks, you’ll wonder how you ever coded without it.

The Problem

Here’s what resource cleanup looks like without defer. Real code, the kind that ships:

Lesson 8: Fan-Out / Fan-In — Distribute, collect, don''t leak

Tue, 24 Jun 2025 00:00:00 +0000

There’s a moment in every Go developer’s journey where the serial loop stops being acceptable. You’ve got 200 URLs to fetch, 500 records to transform, 50 API calls to make — and you’re doing them one at a time. The fix feels obvious: spin up goroutines. But spin them up without a plan and you’ve traded one problem for three.

Fan-out / fan-in is the pattern that makes parallel work manageable. Fan-out means distributing a stream of work across multiple goroutines. Fan-in means collecting their results into a single channel. Simple in concept, surprisingly easy to get wrong in practice.

Lesson 10: The Complete Go Service — HTTP + DB + workers + shutdown in 200 lines

Fri, 20 Jun 2025 00:00:00 +0000

Every lesson in this series has been a piece of a puzzle. HTTP routing, middleware, validation, error responses, pagination, idempotency, timeouts, rate limiting, config management — each one addresses a specific concern in isolation. This final lesson puts them together into a single, production-shaped service that you can actually use as a starting point.

The goal is not a complete application. It is a skeleton that demonstrates how all the pieces wire together in main.go and what a well-structured Go service looks like before you add your business logic.

Lesson 6: API Gateway Patterns — One entry point, many backends

Wed, 18 Jun 2025 00:00:00 +0000

The first time I connected a mobile frontend directly to 11 microservices, I created 11 places for the mobile team to integrate, 11 different auth schemes to understand, 11 different error formats to handle, and a situation where a single product screen required 6 parallel API calls because the data was spread across 6 services. An API gateway solves all of this: one URL, one auth scheme, one error format, and the ability to aggregate multiple service responses into a single response the client actually needs.

Lesson 14: context.Context — The parameter every function should take first

Mon, 16 Jun 2025 00:00:00 +0000

Without context.Context, a function that makes a database call, fires an HTTP request, or runs a long computation has no way to be told to stop. The caller times out, the user closes the browser tab, the load balancer kills the connection — and your function keeps running, consuming CPU and holding database connections, doing work that nobody will ever see. context.Context is how Go solves this.

The Problem

A function with no context cannot be cancelled. It runs until it finishes, or until the process dies. In an HTTP server handling hundreds of requests per second, this accumulates fast:

Lesson 8: Zero-Downtime Deploys — Rolling updates without dropping requests

Sun, 15 Jun 2025 00:00:00 +0000

The first rolling deployment I did without graceful shutdown handling produced about 200 errors for in-flight requests. Kubernetes sent SIGTERM to the old pods, the Go process exited immediately, and every active request was terminated mid-flight. The users got 502s. The monitoring dashboard lit up red for about 30 seconds per deploy, every time.

Kubernetes’s rolling update strategy replaces pods one at a time and can achieve zero request drops — but only if your application cooperates. The contract is: Kubernetes sends SIGTERM, your application finishes in-flight requests, then exits. If you ignore SIGTERM and exit immediately, Kubernetes kills you with SIGKILL after the grace period anyway, and you drop the requests. The work is in your application code, not in the Kubernetes config.

Lesson 8: Production Error Architecture — Designing the error system for a real service

Sat, 14 Jun 2025 00:00:00 +0000

This is the lesson where everything comes together. Over the previous seven lessons we’ve looked at sentinels and typed errors, wrapping strategy, error classification, where to log, how to translate at layer boundaries, and when panic is actually defensible. Now I want to show you what all of that looks like assembled into a complete, production-ready error system for a real API service.

I’m going to build the full error architecture for a hypothetical orders API. By the end you’ll have a template you can adapt directly — the error type hierarchy, the middleware, the structured logging, and the client-facing error codes. This is the code I wish I’d had when I started building services in Go.

Lesson 7: Race Conditions and the Go Memory Model — The bug you can't reproduce

Thu, 12 Jun 2025 00:00:00 +0000

Race conditions are the category of bug that makes senior engineers paranoid and junior engineers dismissive. They don’t reproduce consistently. Your tests pass. Your staging environment looks fine. Then, in production, under a specific load pattern at a specific time, two goroutines read and write the same memory address with no synchronization, and you get corrupted data — or a panic — or silently wrong results that sit in your database for three weeks before someone notices. Understanding why they happen at the language level is what separates engineers who prevent them from engineers who just get lucky.

Lesson 7: go:generate and Code Generation — Let the machine write the boring code

Tue, 10 Jun 2025 00:00:00 +0000

go:generate is Go’s mechanism for attaching arbitrary code generation commands to your source files. It is not magic — it is a convention that tells go generate which commands to run and where. When you run go generate ./..., the tool reads every //go:generate comment in your source tree and executes the commands they reference. What those commands produce is up to you: String() methods for enum types, serialization code, mock implementations, database query functions, or anything else you can express as a code generator.

Lesson 8: Packaging and Distributing — GoReleaser, Homebrew, and getting your tool to users

Thu, 05 Jun 2025 00:00:00 +0000

Building a great CLI tool is half the job. The other half is getting it to users without making them compile it from source, navigate a GitHub releases page manually, or run a curl-pipe-to-bash script from an unverified URL. Distribution is where many Go projects stop short: the binary exists, the README says go install, and that is considered “distributed.”

go install is fine for Go developers. It is not acceptable for operators, system administrators, and end users who reasonably expect brew install or apt install. GoReleaser closes this gap by automating the full release pipeline — cross-compiled binaries, checksums, GitHub releases, Homebrew formulas, Debian packages, Docker images — from a single configuration file and one git push --tags.

Lesson 21: Composition Over Inheritance — Small pieces, loosely joined

Mon, 02 Jun 2025 00:00:00 +0000

If you’ve come from Java or C++, you’re probably waiting for Go to show you its inheritance model. Where’s the extends keyword? Where are the base classes? There aren’t any — Go made a deliberate choice to leave them out. After writing a few thousand lines of Go, most people agree it was the right call.

The Problem

Object-oriented languages lean heavily on the “is-a” relationship. A Dog is-a Animal. A Manager is-a Employee. This sounds elegant until real-world complexity enters the picture: is a FlyingFish a Fish or a Bird? Now you’re in multiple inheritance territory and things get messy fast. And in Go, the instinct to fake it with named fields creates its own noise:

Lesson 8: Linting with golangci-lint — Automate what reviewers shouldn''t waste time on

Sun, 01 Jun 2025 00:00:00 +0000

I made a rule for myself a few years ago: if I leave a code review comment about something a tool could have caught, I’ve wasted both the author’s time and mine. A linter can catch unused variables, missing error checks, shadowed variables, inefficient string concatenation, and dozens of other patterns automatically — in seconds, every commit, without reviewer fatigue. The code review should be about design and correctness, not about whether someone forgot to handle an error returned by rows.Close().

Lesson 6: Mutexes Done Right — The boring tool that actually works

Sat, 31 May 2025 00:00:00 +0000

Channels get the spotlight in Go talks and blog posts — they’re the shiny, idiomatic, philosophically interesting tool. Mutexes feel like the C and Java baggage everyone was supposed to leave behind. But here’s what I’ve learned after several years of writing concurrent Go: mutexes are often the right tool, especially when you’re protecting shared state, and the problems you see in production are almost never “we should’ve used channels” — they’re “we copied the mutex” or “we forgot to narrow the critical section.” Learn to use mutexes properly and stop apologizing for them.

Lesson 7: context Internals — How cancellation propagates under the hood

Thu, 22 May 2025 00:00:00 +0000

context.Context is the most important type in Go’s standard library that most people use by convention without fully understanding. You pass it as the first argument to functions. You check ctx.Done() in goroutines. You create derived contexts with context.WithTimeout. It works — until it doesn’t, and you have a goroutine that doesn’t cancel when the parent context does, or a context that leaks forever because you forgot to call the cancel function.

Lesson 5: sync.WaitGroup — Wait for everyone, then move on

Wed, 21 May 2025 00:00:00 +0000

sync.WaitGroup is one of the first concurrency primitives you reach for in Go, and also one of the first you misuse. The API looks deceptively simple — three methods, twenty minutes of reading, you think you’ve got it. Then you hit a negative counter panic in production, or you find out your Wait() returned while goroutines were still running, and you spend an afternoon learning the rules you thought you already knew.

Lesson 9: Fake Clean Architecture — Layers without purpose are just folders

Tue, 20 May 2025 00:00:00 +0000

I cloned a Go repository that was described to me as a “clean architecture” implementation. It had six layers: handler, usecase, service, repository, model, and dto. Every user-related operation required touching at least four files across four packages. When I added a new field to the user profile, I updated the database schema, the model.User, the dto.UserDTO, the repository.UserRepository, the service.UserService, the usecase.UserUseCase, and the handler.UserHandler. Eight files for one field. The indirection was total, the business logic was nowhere — it was scattered across the layers in thin delegating functions that called the layer below and returned the result.

Lesson 4: The comma ok Idiom — Two returns that save you from panics

Mon, 19 May 2025 00:00:00 +0000

There are three places in Go where a missing second return value means your program either silently does the wrong thing or blows up entirely: reading from a map with a missing key, asserting a type on an interface, and receiving from a closed channel. The language’s answer to all three is the same — a boolean second return that tells you whether the operation actually succeeded. This is the comma-ok idiom, and you’ll use it constantly.

Lesson 5: Embedding and Vector Search — Semantic search in Go without Python

Sun, 18 May 2025 00:00:00 +0000

For a long time, embedding-based semantic search felt like Python territory. The tutorials all pointed to LangChain, FAISS, and numpy. But the actual operations — generate an embedding vector, store it in a database, query for nearest neighbors — map directly onto Go’s strengths: clean HTTP client code for the embedding API, pgx for PostgreSQL with pgvector, and fast concurrent query pipelines. I’ve built production semantic search systems entirely in Go and they’re fast, maintainable, and don’t require a Python sidecar.

Lesson 8: gRPC Basics and Streaming — Protobuf on the wire, types in your code

Thu, 15 May 2025 00:00:00 +0000

My team migrated a set of internal service APIs from JSON over HTTP/1.1 to gRPC roughly two years ago. The motivating factors were type safety across service boundaries, binary serialization that was 5-10x smaller on the wire, and bidirectional streaming that HTTP/1.1 can’t do at all. The migration took about a week per service and the performance improvements were immediately visible in our latency percentiles.

gRPC is a Remote Procedure Call framework that runs over HTTP/2. The interface is defined in Protocol Buffers — a language-neutral schema language — and the gRPC toolchain generates client and server stubs in Go. You call a method; the framework handles serialization, connection management, and streaming.

Lesson 7: Panic, Recover, and When They're Actually Justified — Panic is not error handling

Tue, 13 May 2025 00:00:00 +0000

I’ve seen panic(err) used as error handling more times than I’d like to admit — including in codebases I helped build. The reasoning always sounds logical at the time: “this error should never happen, and if it does, the program state is corrupt anyway, so why not just panic?” The problem is that “should never happen” is a statement about your expectations, not about reality. And “program state is corrupt” is almost never true — one request failed, the other thousand are still fine.

Lesson 4: Buffered vs Unbuffered Channels — Buffering hides bugs

Mon, 12 May 2025 00:00:00 +0000

The first time someone tells you that buffered channels are faster, you believe them — and you spend the next year throwing make(chan T, 100) at every performance complaint, wondering why your system still deadlocks sometimes, and why those deadlocks disappeared when you bumped the buffer to 200. The buffer wasn’t fixing anything. It was delaying the problem. Understanding why requires actually thinking about what buffering changes — not at the performance level, but at the coordination level.

Lesson 9: Config Management — Twelve-factor or twelve headaches

Sat, 10 May 2025 00:00:00 +0000

I have seen configuration managed in at least ten different ways across the Go projects I have worked on: hardcoded constants, config structs passed around by pointer, global variables read at startup, YAML files baked into Docker images, environment variables with no validation, and one particularly creative approach involving a shared Google Sheet. Every one of those had the same core problem: the configuration was not treated as a first-class part of the application.

Lesson 8: Designing Interfaces for Libraries — Libraries export interfaces, apps consume them

Thu, 08 May 2025 00:00:00 +0000

Writing a library for other Go developers is a fundamentally different design problem than writing application code. In an application, you control every call site. If an interface needs to change, you update all the callers. In a library, your callers are other people, other teams, other binaries you have never seen — and when you change a public interface, you break them all in ways you cannot fix yourself. This constraint forces a discipline that makes library-authored Go interfaces among the most carefully designed in the ecosystem.

Lesson 16: Channels Are for Coordination — Stop using channels as fancy mutexes

Mon, 05 May 2025 00:00:00 +0000

Channels are Go’s most recognizable concurrency feature, and also one of the most misused. The moment engineers learn about them, there’s a strong temptation to reach for a channel every time two goroutines need to interact. That instinct is wrong about half the time. Channels are for coordination — signaling events, distributing work, collecting results. They are not a universal replacement for shared state.

Rob Pike’s line from his 2012 talk sums it up: “Do not communicate by sharing memory; share memory by communicating.” That’s a guiding philosophy, not an absolute rule.

Lesson 9: Dependency Scanning — govulncheck before you deploy

Mon, 05 May 2025 00:00:00 +0000

The security posture of your Go application is not just about the code you write — it is also about the code you import. A typical Go microservice will have dozens of direct and transitive dependencies. Any one of them might have a known vulnerability in the specific version you are using. Unlike the bugs in your own code, these vulnerabilities are publicly catalogued, exploits are often published, and attackers scan for them at scale.

Lesson 3: Channel Ownership Rules — Who closes the channel?

Fri, 25 Apr 2025 00:00:00 +0000

At some point, you’re going to close a channel twice and the runtime is going to panic with close of closed channel. Or you’re going to close a channel from the wrong goroutine and send a value into it right after, and the runtime is going to panic with send on closed channel. These aren’t subtle race conditions that only show up under load — they’re logic errors that exist because nobody in the codebase agreed on who owns the channel. That agreement is the whole game.

Lesson 8: Capacity Matters — The allocation tax you''re paying without knowing

Mon, 21 Apr 2025 00:00:00 +0000

There’s a one-line fix that will make your hot paths faster, use less memory, and reduce GC pressure. It costs you nothing in readability. Most Go programmers know about it. Far fewer actually do it consistently. The fix is telling Go how big a slice is going to be before you start filling it.

The Problem

This is the pattern you reach for by reflex, especially if you’ve come from languages where dynamic arrays just grow as needed:

Lesson 6: Error Boundaries Across Layers — Translate at the border, don't leak internals

Sat, 19 Apr 2025 00:00:00 +0000

One of the most subtle security issues I’ve encountered in Go APIs isn’t an authentication bug or a missing authorization check — it’s a SQL error message showing up in a JSON response. Something like {"error": "pq: duplicate key value violates unique constraint \"users_email_key\""}. The frontend is now showing your users your database schema. Not great.

This happens because somewhere between the repository and the HTTP response, someone got lazy with error translation. The raw database error bubbled all the way up and got written directly into the response. Error boundaries exist to prevent exactly this — they’re the translation points between layers, where internal implementation details get converted to appropriate external representations.

Lesson 5: Saga Pattern — Distributed transactions without two-phase commit

Fri, 18 Apr 2025 00:00:00 +0000

Two-phase commit is theoretically elegant and operationally painful. I’ve seen it cause system-wide deadlocks during network partitions, coordinator failures that required manual database recovery, and deployment coupling so tight that every service had to be upgraded in lockstep. The saga pattern is the alternative — it trades atomicity for availability, compensates for failures with explicit rollback actions, and keeps each service’s transactions entirely local. It’s the pattern I reach for whenever I need “all of this must succeed together” across more than one database.

Lesson 8: String Internals — Immutable, backed by bytes, cheaper than you think

Tue, 15 Apr 2025 00:00:00 +0000

I used to reach for []byte over string in performance-sensitive code, assuming strings were somehow more expensive because “immutability must cost something.” That intuition was wrong. Understanding what a string actually is — a read-only slice header — corrected my assumptions and simplified a lot of code I had unnecessarily complicated.

The Problem

Strings in Go are everywhere, and most developers use them without thinking about what they are at the memory level. This leads to a few common mistakes:

Lesson 2: Cancellation with context.Context — Every goroutine needs a kill switch

Sun, 13 Apr 2025 00:00:00 +0000

Without context.Context, you have goroutines running long after the user who triggered them gave up, HTTP connections burning server resources for requests nobody’s waiting for, and database queries executing on behalf of clients that disconnected ten seconds ago. Context is the mechanism Go gives you to propagate “I changed my mind” — and most engineers don’t use it until something in production embarrasses them into learning it properly.

The Problem

Let’s start with the most common mistake — blocking on a slow operation with no timeout:

Lesson 7: Profiling in Containers — pprof works in Kubernetes too

Sat, 12 Apr 2025 00:00:00 +0000

The first time I needed to profile a Go service in production, I assumed I’d have to deploy a special build, reproduce the problem locally, or use some heavyweight APM product. Then I learned that Go’s net/http/pprof package can serve live profiling data from a running process via HTTP — in a container, in Kubernetes, right now, without redeployment.

pprof is the built-in Go profiler. It can capture CPU profiles (what functions are consuming CPU time), heap profiles (what’s allocated in memory and by whom), goroutine profiles (how many goroutines exist and what they’re doing), and block/mutex profiles (where goroutines are waiting). All of this is available as HTTP endpoints that you can scrape with go tool pprof from your laptop.

Lesson 8: Avoiding Premature Optimization — Measure first, optimize never (usually)

Thu, 10 Apr 2025 00:00:00 +0000

I’ve spent time in this series showing you how to make Go programs faster — escape analysis, stack allocation, pre-sizing data structures, zero-copy string handling, benchmarking discipline, pprof profiling, CPU vs memory tradeoffs. Every technique is real and useful. And every single one of them has been misapplied, including by me, when applied before understanding whether they were needed. The last lesson isn’t another technique. It’s the discipline that makes all the other techniques worth using: measure first, understand where the actual cost is, and optimize only there.

Lesson 6: Avoiding Reflection — Generics and code generation often win

Tue, 08 Apr 2025 00:00:00 +0000

After spending several lessons on what reflection can do, it is worth turning the question around: when should you specifically choose not to use reflection, even when it would work? The answer is almost always “when you have a statically typed alternative,” because statically typed code is faster, catches errors at compile time rather than runtime, and is easier for both humans and tools to reason about.

Go 1.18 added generics, which eliminated one of the most common justifications for reflection: writing algorithms that work on slices, maps, or other containers of unknown element type. Code generation eliminates another: producing type-specific serializers, converters, and mappers that are faster than reflection can ever be. Knowing when to reach for these alternatives instead of reflection is part of writing mature Go.

Lesson 6: Accept Interfaces, Return Structs — Flexibility in, certainty out

Mon, 07 Apr 2025 00:00:00 +0000

Here’s a mistake I see in almost every Go codebase written by people coming from Java or C#: they accept concrete types everywhere and return interfaces from constructors. It feels “enterprise-y”. It’s actually backwards. The idiomatic Go version is the opposite — accept the smallest interface that does the job, return the richest concrete type you have.

The Problem

Most of the pain comes from accepting concrete types. Once you lock a function to a specific concrete type, every caller that doesn’t have exactly that type is stuck. Tests become integration tests. Swapping implementations requires rewriting functions. And the function itself becomes harder to compose.

Lesson 1: Goroutine Lifecycle Management — Who owns this goroutine?

Sun, 06 Apr 2025 00:00:00 +0000

Nobody tells you that the first goroutine you “fire and forget” in production is the one that eventually takes down your service at 3 AM. You start it, it runs, and everything looks fine — until requests pile up, memory climbs, and your dashboards turn red because five hundred goroutines are blocked waiting on a channel that’ll never receive another value. The problem isn’t that goroutines are dangerous. It’s that nobody taught you to think about who owns them.

Lesson 7: Build Flags and ldflags — Inject version info at compile time

Sat, 05 Apr 2025 00:00:00 +0000

A CLI tool that cannot tell you what version it is running is a frustrating tool to operate. When something breaks, the first question is “which version?” Without a proper answer, debugging becomes archaeology. The good news is that Go’s build system provides two mechanisms for injecting metadata at compile time — ldflags for injecting variable values from the shell, and build constraints for including or excluding code based on the build context — and both are straightforward once you understand their syntax.

Lesson 8: Premature Abstraction — Wrong abstraction costs more than duplication

Wed, 02 Apr 2025 00:00:00 +0000

There is a principle in software development — “Don’t Repeat Yourself” — that is so widely known it gets abbreviated to DRY and invoked to justify almost any abstraction. The problem is that DRY is a principle about knowledge, not syntax. Two pieces of code that look the same but represent different concepts should stay separate. Two pieces of code that represent the same concept should indeed be unified. Most premature abstractions happen when developers see syntactic similarity and immediately reach for abstraction, before they understand whether the similarity is incidental or fundamental.

Lesson 7: Kill the Utils Package — util.go is where code goes to hide

Tue, 01 Apr 2025 00:00:00 +0000

Every Go codebase I’ve worked on for more than a year has a util package. Some have a helpers package. Some have both. I’ve seen common, shared, misc, and once, memorably, stuff. These packages are where code goes when a developer doesn’t know where it belongs — which means they’re the first place reviewers stop reading carefully, the last place new engineers look when they can’t find something, and the primary location of dead code in any codebase over 18 months old.

Lesson 10: Test Architecture — Tests that survive refactoring

Tue, 25 Mar 2025 00:00:00 +0000

Every test suite starts clean. Then the codebase grows, the team grows, deadlines hit, and gradually the tests become the thing you dread touching. You add a feature and a hundred tests break — not because the feature is wrong, but because the tests were coupled to implementation details. You rename a method and spend more time updating tests than writing the feature. Sound familiar? The problem isn’t the tests themselves. It’s the architecture — the structure, the layering, and the principles that determine whether your test suite stays an asset or becomes a liability.

Lesson 6: sync Package Complete Guide — Mutex, Once, Pool, Map — when to use each

Sat, 22 Mar 2025 00:00:00 +0000

The sync package is where Go’s concurrency tools live when channels aren’t the right answer. sync.Mutex, sync.RWMutex, sync.WaitGroup, sync.Once, sync.Pool, sync.Map — each one solves a specific problem, and using the wrong one is a reliable way to introduce bugs or performance regressions. I’ve misused all of them at various points.

The general guidance is channels for communication, mutexes for protecting shared state. But within the mutex family, the choice between Mutex, RWMutex, and sync.Map has performance implications that matter in hot paths. And sync.Pool is frequently misunderstood — it’s not a general-purpose object pool; it’s a GC-aware buffer recycler.

Lesson 7: Outbox Pattern — Reliable events without distributed transactions

Thu, 20 Mar 2025 00:00:00 +0000

Here’s a bug that’s bitten almost every distributed system I’ve worked on: a service saves a record to the database and then publishes an event to Kafka. The record is saved. The process crashes before the publish. Now the database says the order exists, but the fulfillment service never heard about it. The order sits in limbo forever.

The naive fix — wrapping both operations in a transaction — doesn’t work because Kafka isn’t a participant in your database transaction. You can’t two-phase commit across Postgres and Kafka without a distributed transaction coordinator, and nobody wants to operate one of those in production.

Lesson 5: Logging vs Returning — Log at the boundary, return everywhere else

Mon, 17 Mar 2025 00:00:00 +0000

There’s a smell I encounter in almost every codebase I’ve reviewed — including ones I wrote early in my Go career. Someone discovers that err != nil and, out of an abundance of caution, they log it right there. Then return it. Then the caller logs it again. Then the middleware logs it a third time. By the time a single failed database query reaches the response, it’s appeared in the logs four times with slightly different messages and you can’t tell whether four things failed or one thing failed four times.

Lesson 8: Rate Limiting — Say no before you break

Sat, 15 Mar 2025 00:00:00 +0000

A service I was running had no rate limiting. One night, a script that a client was testing started sending requests in a tight loop — about 4,000 requests per second. The database connection pool saturated within seconds. Other clients started seeing timeouts. By the time I woke up and deployed a fix, we had been degraded for forty minutes. A single 429 Too Many Requests response would have stopped the script cold in seconds.

Lesson 4: Tool Calling Patterns — Letting the LLM invoke your Go functions

Wed, 12 Mar 2025 00:00:00 +0000

Tool calling is where LLM integrations get genuinely powerful. Without tool calling, you’re limited to asking the model to generate text. With tool calling, you can build a conversational interface where the model decides which of your functions to call, calls them, incorporates the results into its reasoning, and decides whether to call more tools or return a final answer. I’ve used this to build support assistants that query databases, coding assistants that run test suites, and research tools that fetch live web content — all driven by the model’s judgment about which tools to invoke.

Lesson 8: Secure HTTP Defaults — Your production server needs these headers

Mon, 10 Mar 2025 00:00:00 +0000

When I run the Go HTTP server in the standard library with no configuration, it does a lot of things right — it is fast, it handles HTTP/2, it is well-tested. But it also does a handful of things that are wrong for production: no timeouts, no response headers that protect against common browser-based attacks, and server identification information in responses. These are not bugs in the standard library; they are defaults appropriate for development that need to be changed before you deploy.

Lesson 7: The io.Reader/Writer Ecosystem — The most powerful 2-method interfaces in Go

Sat, 08 Mar 2025 00:00:00 +0000

If you want to understand what makes Go interfaces powerful, do not start with your own code. Start with io.Reader. It is one method — Read(p []byte) (n int, err error) — and it is the foundation of an entire ecosystem that spans files, network connections, HTTP bodies, compressed streams, encrypted data, buffered reads, pipes, test helpers, and dozens of third-party libraries. Everything that produces bytes implements io.Reader. Everything that consumes bytes accepts one.

Lesson 7: The Complete Observability Stack — Logs, metrics, traces, profiles — wired together

Wed, 05 Mar 2025 00:00:00 +0000

We have covered each signal in isolation — structured logs, Prometheus metrics, OpenTelemetry traces, correlation IDs, pprof profiles, and latency distributions. The preceding six lessons described the individual instruments. This one is about wiring them together into a system that actually works during an incident, not just in a demo.

The goal is this: when something breaks in production, you should be able to answer four questions within five minutes: Is it broken? Who is affected? Where in the system did it break? What is the root cause? Logs, metrics, traces, and profiles each answer one of those questions. The wiring between them — shared trace IDs, consistent service names, deployment markers on dashboards — is what lets you move between signals without losing context.

Lesson 5: What's New in Go 1.25–1.26 — Swiss table maps, weak pointers, and the future

Sun, 02 Mar 2025 00:00:00 +0000

Every major Go release follows a rhythm: one or two headline language features, a handful of standard library additions, and a runtime improvement you probably do not notice directly but that makes your services run better in aggregate. Go 1.23 and 1.24 brought the iterator protocol, go tool improvements, and the unique package. Go 1.25 and 1.26 continued this pattern with Swiss table map internals, a production-ready weak pointer API, and improvements to the toolchain that affect how you build, ship, and profile Go binaries.

Lesson 7: Values Copy vs Share — When Go copies and when it doesn't

Sat, 01 Mar 2025 00:00:00 +0000

Early in my Go career I had a bug where I modified a slice inside a function expecting the caller’s slice to remain unchanged — and it did. Then I had a different bug where I expected the opposite and the caller’s slice was modified. I had no mental model for predicting which would happen. Building that model is what this lesson is about.

The Problem

Go passes everything by value. That’s the official line, and it’s true. But “by value” means different things for different types:

Lesson 4: Operational vs Domain Errors — Not all errors deserve the same treatment

Fri, 28 Feb 2025 00:00:00 +0000

One of the more expensive lessons I learned was treating all errors the same. When a database connection drops, you retry. When a user sends an invalid email address, you return a 400 and explain what’s wrong. When someone tries to access a resource that doesn’t belong to them, you return a 403. These are completely different situations — different causes, different remedies, different communication needs — and collapsing them into a single err != nil branch produces services that retry permanent failures, expose internal details to users, and log noise that drowns out real alerts.

Lesson 7: go.work and Workspace Mode — Developing multiple modules without replace hacks

Tue, 25 Feb 2025 00:00:00 +0000

Before go.work existed, developing across multiple local Go modules was genuinely painful. You were working on a library in one directory and an application that depended on it in another. Every time you changed the library, you had to add a replace directive to the application’s go.mod, run your tests, and then remember — always remember — to remove the replace before committing. I have seen replace directives committed to production go.mod files more times than I would like to admit.

Lesson 7: CPU vs Memory Tradeoffs — Cache it or compute it, pick one

Thu, 20 Feb 2025 00:00:00 +0000

Every performance optimization ultimately makes the same trade: you’re giving up memory to gain CPU time, or giving up CPU time to reduce memory usage. There’s no free lunch. The skill isn’t knowing that the tradeoff exists — it’s knowing which side of it you’re on, and making the choice consciously rather than accidentally. I’ve optimized for memory when the bottleneck was CPU, and optimized for CPU when memory was the problem. Both directions are wrong when you pick them without data.

Lesson 7: Panic as Error Handling — Panic is for bugs, not business logic

Tue, 18 Feb 2025 00:00:00 +0000

I have reviewed Go code from developers who learned other languages where exceptions are the primary error handling mechanism. In Ruby, Python, or Java, you throw an exception and it propagates up the stack until something catches it. In Go, the analogous mechanism — panic — has a very different contract. A panic that is not recovered crashes the entire process. In a web server, that means every in-flight request dies. In a worker process, that means all queued work is dropped.

Lesson 9: Flaky Test Control — A flaky test is worse than no test

Sat, 15 Feb 2025 00:00:00 +0000

A flaky test is a test that sometimes passes and sometimes fails with no code change in between. It sounds like a minor annoyance. It’s actually corrosive. Once your team learns that the test suite sometimes fails for “no reason,” they start merging on red. They start dismissing failures. They lose trust in the test suite as a signal. A single reliably-failing test is informative; a dozen flaky tests teach your team to ignore failures. I’ve seen this destroy test suite culture on multiple teams.

Lesson 6: Race Detector in CI — Run -race on every PR or ship bugs

Wed, 12 Feb 2025 00:00:00 +0000

A data race is a memory safety bug. Two goroutines access the same variable without synchronization, at least one is writing, and the Go memory model makes no guarantees about what happens. In practice: values get corrupted, counters drift, maps panic at runtime. These bugs are intermittent — they appear under load, on fast machines, during deploys — and they’re nearly impossible to reproduce deterministically.

The Go race detector is one of the most powerful debugging tools in any language ecosystem. It instruments every memory access at the compiler level and reports races precisely: the exact goroutine stacks at the moment of the conflicting accesses. But it only helps if you run it. Most teams run it once after a bug report. The right approach is running it on every PR, in CI, before the code is ever merged.

Lesson 5: Validation Frameworks — Reflect once, validate everywhere

Mon, 10 Feb 2025 00:00:00 +0000

Input validation is one of those problems that looks solved until you realize you are writing the same type of check — not nil, min length, valid email format, required when other field is set — dozens of times across dozens of handlers. Centralizing these rules without reflection means either a massive switch statement or hand-writing a validation function for every struct in your application. Reflection makes it possible to declare validation rules once, at the struct, and enforce them automatically everywhere that struct is validated.

Lesson 6: Package Cohesion — Everything in a package should belong together

Thu, 06 Feb 2025 00:00:00 +0000

Go packages are the primary unit of code organization. They determine what’s visible to whom, what gets compiled together, and — most importantly — they communicate intent to every engineer who reads the codebase. A package with high cohesion says something true and useful: “everything here is about orders” or “everything here handles HTTP middleware.” A package with low cohesion says nothing — it’s a filing cabinet where things went when nobody knew where else to put them.

Lesson 6: Embedding Assets — embed.FS puts files inside your binary

Wed, 05 Feb 2025 00:00:00 +0000

Before Go 1.16, embedding static assets in a Go binary required either a code generation tool that converted files to byte arrays, a third-party library like packr or statik, or shipping the files alongside the binary and reading them from disk at runtime. Each approach had real costs: generated code bloated repositories, third-party tools had to be installed separately, and shipping separate files broke the “single binary” distribution story.

The //go:embed directive in Go 1.16 solved this cleanly. Files, directories, and whole asset trees can be embedded directly into the binary with a single comment and a variable declaration. Templates, SQL migrations, web assets, default configs — everything your binary needs can travel with it.

Lesson 3: Wrapping Strategy — Every wrap should add context, never noise

Tue, 04 Feb 2025 00:00:00 +0000

There’s a certain kind of error message I’ve come to dread in production logs: auth: db: sql: connection refused. Technically, it contains the full path from the handler down to the socket. Practically, it tells me nothing I couldn’t figure out from the stack trace — and it takes ten seconds to parse. That error message is the output of wrapping done wrong: every layer added its name reflexively, without thinking about what the reader actually needs.

Lesson 7: Timeouts and Retries — Your client needs a deadline, your server needs a budget

Sat, 01 Feb 2025 00:00:00 +0000

I once watched a service die in slow motion. An upstream dependency started responding slowly — not failing, just slow. Within minutes, all request goroutines were blocked waiting for the upstream. New requests kept arriving. Goroutines piled up. Memory climbed. Eventually the process was killed by the kernel. The upstream recovered in about thirty seconds. My service was down for twelve minutes. Every second of that outage was caused by the absence of a single line: a timeout.

Lesson 4: Distributed Tracing — Follow the request across 5 services

Tue, 28 Jan 2025 00:00:00 +0000

Debugging a microservices system with only logs is like debugging a multi-threaded program with only print statements — possible, but painful in ways that are entirely avoidable. The first time I had to trace a slow request through six services using log grep, I understood why distributed tracing exists. An hour of log correlation that should have been a 10-second click on a flame chart. Distributed tracing gives you that flame chart.

Lesson 6: Eventual Consistency — Your data will be wrong, temporarily

Sat, 25 Jan 2025 00:00:00 +0000

I used to believe that eventual consistency was an exotic property of distributed databases that I’d only encounter at Google scale. Then I added a Redis cache to a simple CRUD service and immediately had a bug where users couldn’t see their own updates. Welcome to eventual consistency — it shows up the moment you have two places that store the same data.

Eventual consistency means that if you stop writing to a system, all replicas will eventually converge to the same value. The word “eventually” can mean milliseconds or minutes, depending on the system. The hard part isn’t the definition — it’s designing application code that works correctly even when replicas haven’t converged yet.

Lesson 5: os and filepath — Cross-platform file operations that actually work

Wed, 22 Jan 2025 00:00:00 +0000

Go’s os and path/filepath packages are among the most underappreciated in the standard library. Most developers know os.Open, os.Create, and os.ReadFile. Far fewer know os.MkdirAll, os.CreateTemp, filepath.WalkDir, or the difference between path and path/filepath — which is the difference between code that works everywhere and code that silently breaks on Windows.

I maintain a CLI tool that runs on macOS, Linux, and Windows. The file operation bugs I’ve shipped have taught me exactly which parts of these packages require care.

Lesson 8: Race-Aware Tests — If it passes without -race, it hasn't passed

Mon, 20 Jan 2025 00:00:00 +0000

A test suite that passes without -race is not a clean bill of health. It’s a test suite that hasn’t checked one of the most insidious categories of bugs in Go: data races. I’ve shipped code that passed every test, passed code review, and then caused memory corruption in production because two goroutines were reading and writing a map concurrently. The race detector would have found it in under a second. We just never ran it.

Lesson 7: JWT Caveats — JWTs are not sessions

Sat, 18 Jan 2025 00:00:00 +0000

JWT has become the default answer to “how should I handle authentication tokens?” in the Go community. I have shipped JWTs in production and I have also shipped systems that would have been much simpler and more secure with server-side sessions. The point of this lesson is not that JWTs are bad — it is that they carry specific security risks that are easy to overlook, and they solve a specific problem (stateless authentication across services) that not every application actually has.

Lesson 6: Debugging Latency and Leaks — Your p99 is lying to you

Wed, 15 Jan 2025 00:00:00 +0000

We had a service whose p99 latency was 800ms. The p50 was 12ms. The SLA was 200ms at p99. All our dashboards showed the p99 breaching during peak traffic, but the service felt fine to most users. We added caching. We optimized the slow database query. We bumped the CPU allocation. The p99 barely moved.

Three weeks of tuning later, a colleague asked me to show him the raw histogram buckets. We looked at the actual distribution: 98% of requests were under 15ms. The remaining 2% were all clustered around 900ms, nearly a bimodal distribution. This was not a “slow” service — it was a service with two distinct response time populations, and the p99 was sampling from the slow population. The fix had nothing to do with the code on the hot path.

Lesson 6: Swallowing Errors — The silent failure that cost us 3 hours

Sun, 12 Jan 2025 00:00:00 +0000

We had a deployment where user preferences stopped being saved. New preferences were accepted by the API — the endpoint returned 200 — but nothing was written to the database. After three hours of debugging we found it: a defer rows.Close() inside a transaction helper that was discarding the error from tx.Commit(). The commit was failing silently, the defer returned without error, and the handler sent a success response. The only indication anything was wrong was a metrics counter nobody had set up an alert for.

Lesson 2: errors.Is and errors.As — Matching errors through the wrapping chain

Thu, 09 Jan 2025 00:00:00 +0000

Go 1.13 shipped what I consider the most important error-handling improvement the language has had: errors.Is, errors.As, and the %w verb. Before that, wrapping errors with context meant breaking the ability to inspect them. You’d wrap with fmt.Errorf("context: %v", err) and then the original error was gone — you could log it, but you couldn’t match it. Callers would resort to string matching or just give up and let every error map to a 500.

Lesson 6: Memory Alignment and Struct Padding — Field order affects struct size

Wed, 08 Jan 2025 00:00:00 +0000

I once reviewed a PR where someone had defined a struct with a bool field between two int64 fields, resulting in a 24-byte struct instead of the 17 bytes you might naively calculate. When I pointed it out, the response was “the compiler should handle that.” It doesn’t. Go respects the field order you give it, and it inserts padding to satisfy alignment requirements. Knowing the rules means you write efficient structs by default.

Lesson 6: Testability Without Over-Mocking — Fakes beat mocks every time

Mon, 06 Jan 2025 00:00:00 +0000

Mock frameworks are a seductive solution to a real problem. You have a dependency — a database, an email service, an HTTP client — and you need your tests to run without it. A mock framework promises to solve this with generated code and assertion APIs. In my experience, what actually happens is that the tests become tightly coupled to implementation rather than behavior, they break whenever you refactor internals, and maintaining the mock library becomes a part-time job.

Lesson 6: pprof Deep Dive — CPU, memory, goroutine — read all three

Sun, 05 Jan 2025 00:00:00 +0000

When I first learned about pprof, I thought it was a single tool that told you “what’s slow.” It took me an embarrassingly long time to understand that it’s actually a family of profilers — CPU, heap, allocs, goroutine, mutex, block — each answering a completely different question. Reading one profile and ignoring the others is like diagnosing engine trouble by only checking the oil. You might find something. You’ll definitely miss something. The profilers are designed to work together, and once you start reading all three, performance diagnosis goes from guesswork to diagnosis.

Lesson 6: Dependency Direction — Always depend inward, never outward

Thu, 02 Jan 2025 00:00:00 +0000

We fixed cycles in lesson 2. But removing cycles is a necessary condition for good architecture, not a sufficient one. You can have a perfectly cycle-free dependency graph where every arrow points in the wrong direction, and the result is still a system that is painful to test, extend, and reason about.

Dependency direction is about more than just “does A import B.” It is about which layer owns the core business rules and which layers are allowed to know about which other layers. Get this wrong and your domain logic ends up tangled with your database driver. Get it right and you can replace your entire HTTP layer, or swap Postgres for a different store, without changing a single line of business logic.

Lesson 3: Streaming Responses — Token-by-token output without buffering the whole response

Wed, 18 Dec 2024 00:00:00 +0000

If you’ve ever used a non-streaming LLM endpoint in a user-facing feature, you know the experience it creates: the user submits a question, watches a spinner for 8 seconds, then suddenly gets a wall of text. Streaming changes this completely — the user sees output appearing word by word, which feels responsive and alive even when the total time-to-complete is identical. In Go, streaming LLM responses means reading Server-Sent Events (SSE) from the API and piping them to the client in real time. It’s genuinely one of the nicer concurrency patterns I’ve implemented.

Lesson 5: CI/CD for Go — GitHub Actions that actually catch bugs

Sun, 15 Dec 2024 00:00:00 +0000

I’ve set up CI pipelines for Go services about a dozen times, and every iteration taught me something about what the pipeline should actually catch. The first version ran go test ./... and called it done. That caught compilation errors and test failures, but not data races, not staticcheck warnings, not formatting drift, not license issues, not security vulnerabilities in dependencies. Each of those failure categories has caused a production incident at some point. The current version catches most of them before the PR is merged.

Lesson 1: Sentinel vs Typed Errors — Know your error before you handle it

Sat, 14 Dec 2024 00:00:00 +0000

When I first started writing Go seriously, I treated errors like fire: try to avoid them, and when you can’t, put them out as fast as possible with an if err != nil { return err }. It took a few production incidents — and a lot of reading other people’s codebases — before I understood that errors aren’t just signals. They’re data. And how you design that data determines how well your callers can respond to failures.

Lesson 4: Structured Logging with slog — The stdlib logger Go always needed

Thu, 12 Dec 2024 00:00:00 +0000

I have switched logging libraries in Go more times than I care to admit. Started with the standard log package — fine for scripts, useless in production because you cannot query plain text logs efficiently. Moved to logrus because everyone was using it. Switched to zap when I needed better performance. Considered zerolog when I wanted allocation-free hot paths. Each migration meant updating every file that imported the old library, convincing teammates, and writing bridge adapters for third-party code that used a different logger.

Lesson 5: Cross-Compilation — Build for Linux from your Mac in one command

Tue, 10 Dec 2024 00:00:00 +0000

One of Go’s most practical superpowers is that cross-compilation is a first-class feature, not an afterthought. Two environment variables — GOOS and GOARCH — are all you need to produce a Linux binary from macOS, a Windows executable from Linux, or an ARM binary from an x86 machine. No Docker containers required, no cross-compilation toolchain setup, no linker flags hunting. Just GOOS=linux GOARCH=amd64 go build and you have a production-ready binary for the target platform.

Lesson 6: Idempotency in APIs — Every POST should be safe to retry

Sun, 08 Dec 2024 00:00:00 +0000

A client sends a payment request. The network times out. The client does not know if the payment was processed. Should it retry? If it retries and the payment already went through, the customer gets charged twice. If it does not retry and the payment failed, the order never ships. Without idempotency, there is no safe answer to this question.

This is not a theoretical concern. It happens every time a mobile app retries a failed request, every time a message queue delivers a message at least once, every time a load balancer retries on a 503.

Lesson 5: Small Functions Win — If you can''t name it clearly, it does too much

Fri, 06 Dec 2024 00:00:00 +0000

There is a simple test I apply to any function I’m about to merge: can I name it clearly without using “and”? If the most honest name for a function is validateAndSaveAndNotifyUser, the function is three functions pretending to be one. The naming test doesn’t lie — it’s a direct readout of the function’s responsibility. I’ve seen this test convince engineers who were unmoved by SOLID principles or Uncle Bob quotes, because it’s visceral: if you can’t say what the function does in a few words, you already know something is wrong.

Lesson 7: Golden File Testing — Store expected output, compare on run

Thu, 05 Dec 2024 00:00:00 +0000

Some functions produce output that’s too large or too structured to assert inline. A template renderer, a code generator, a JSON serializer for a deeply nested type, a CLI help text formatter — any of these can produce hundreds of lines of output that you need to verify is correct. Hardcoding that expected output inside the test function creates a wall of string literals. The golden file pattern solves this by storing the expected output in a file, comparing against it at test time, and offering a flag to regenerate it when the output intentionally changes.

Lesson 6: Password Hashing — bcrypt or argon2, nothing else

Mon, 02 Dec 2024 00:00:00 +0000

Password hashing is one of those topics where the correct answer is short and clear, the wrong answers are numerous and subtle, and developers who confidently implement one of the wrong answers often do not know they did anything wrong until a database is leaked and journalists start writing about it. I have sat in a post-mortem where the words “we were using MD5” were spoken in a conference room full of very quiet people. That was not my code, but I understood how it happened — MD5 was the “hash function” the developer knew, and they did not realize it was entirely unsuitable for passwords.

Lesson 5: Profiling in Production — pprof is not just for development

Sun, 01 Dec 2024 00:00:00 +0000

I used to think profiling was something you did when you had a performance problem: reproduce it locally, run pprof, stare at the flame graph, fix the hot path. A fire-fighting tool, not an always-on system.

Then we had a memory leak in production that we couldn’t reproduce locally. The heap grew by about 50 MB per hour under real traffic patterns, causing an OOM every eight hours and a rolling restart across the fleet. Our staging environment used synthetic load that didn’t trigger the leak. We had no profile data from when the leak was building — only from after the crash, when the heap had already been cleared.

Lesson 4: Building a Serializer — encoding/json under the hood

Thu, 28 Nov 2024 00:00:00 +0000

encoding/json is Go’s most-used package and one of its most instructive implementations. Under the hood it is almost entirely reflection: it inspects struct field types, reads json tags, handles pointer dereferences, recurses into nested structs, and handles special cases like time.Time and json.Marshaler interface implementations. Building a simplified version of a struct serializer from scratch is the best way to understand both how reflection works in practice and why encoding/json makes the design choices it does.

Lesson 5: Ignoring Context — The cancellation nobody checked

Fri, 22 Nov 2024 00:00:00 +0000

I spent a Tuesday afternoon tracking down why our service continued doing expensive database work after clients had long since disconnected. An HTTP client with a 3-second timeout would cancel the request, but our handler would still run three downstream database queries that together took 8 seconds. The handler was checking for errors but never checking the context. By the time it finished, the client had retried twice, and we were now running three copies of the same 8-second work simultaneously.

Lesson 2: gRPC-Based Plugin Architecture — How Terraform and Vault do plugins

Thu, 21 Nov 2024 00:00:00 +0000

After I understood how hashicorp/go-plugin worked with net/rpc, the next question was obvious: how does Terraform manage hundreds of community-contributed providers, written by different teams, evolving on different schedules, sometimes in languages other than Go? The answer is gRPC. Terraform’s provider protocol is a protobuf schema, communicated over the same subprocess-plus-RPC architecture from Lesson 1 — but with gRPC instead of net/rpc. That substitution buys you schema evolution, multi-language support, streaming, and a strongly-typed IDL. This lesson shows you how to build a plugin system using that pattern.

Lesson 5: Message Queues in Go — NATS, RabbitMQ, Kafka — pick your tradeoff

Wed, 20 Nov 2024 00:00:00 +0000

I’ve integrated all three of these systems in production Go services, and the question I get most often is: “Which one should I use?” The honest answer is that it depends on what guarantee you actually need — and most engineers pick based on familiarity or hype rather than requirements. NATS, RabbitMQ, and Kafka solve meaningfully different problems, and choosing the wrong one creates operational pain that no amount of clever application code can fix.

Lesson 4: time Package Gotchas — Timezones, monotonic clocks, and the bug in your cron

Mon, 18 Nov 2024 00:00:00 +0000

The time package looks straightforward right up until the moment a bug report arrives saying “the nightly job didn’t run last Sunday.” It never runs on the Sunday when daylight saving time ends. Because that Sunday has 25 hours, and the cron expression fires twice at the ambiguous time, and the second firing is skipped because the code thinks it already ran. I’ve debugged this exact bug, and the root cause is always the same: someone — usually me — assumed time is simpler than it is.

Lesson 8: When Duplication Is Better Than Abstraction — Bad abstraction costs more than repeated code

Sun, 17 Nov 2024 00:00:00 +0000

I want to end this course with the idea I wish I’d understood at the start — not just intellectually, but in my gut. It’s this: duplication is a problem you can see. Bad abstraction is a problem you can’t see until it’s too late.

Duplicated code is visible. You grep for it, you find it, you fix it. It’s annoying, but it’s honest. Bad abstraction hides behind clean-looking code. It’s the function that requires fifteen minutes of context to understand, the type parameter that nobody knows how to satisfy, the constraint that’s technically correct but practically useless. It costs you in onboarding, in debugging, in every change that touches it for the rest of the codebase’s life.

Lesson 5: GC Behavior and Tuning — GOGC and GOMEMLIMIT changed the game

Fri, 15 Nov 2024 00:00:00 +0000

For years, tuning Go’s GC meant tweaking GOGC and hoping for the best. I operated on vibes and guesswork. Then Go 1.19 introduced GOMEMLIMIT — a hard memory limit that fundamentally changed how I reason about GC tuning. Suddenly I had a second axis of control that actually matched how production memory is constrained. This lesson is the mental model I wish I had from day one.

The Problem

Go uses a concurrent, tri-color mark-and-sweep garbage collector. “Concurrent” means most of the GC work happens while your program is running, not in stop-the-world pauses. This is generally excellent, but the GC needs to be triggered somehow, and the default trigger can be surprising.

Lesson 5: Composition with Embedding — Small interfaces compose into powerful contracts

Tue, 12 Nov 2024 00:00:00 +0000

One of the things that surprised me most about Go when I came from Python was that Go has no inheritance. No base classes, no method overriding, no type hierarchies. What it has instead is embedding — the ability to include one type inside another so that the outer type promotes the inner type’s methods. Combined with interface composition, this gives you something more flexible than inheritance: you can build complex behaviors from simple, testable pieces without the fragility that comes from deep class trees.

Lesson 5: Benchmarking Done Right — testing.B is not what you think

Sun, 10 Nov 2024 00:00:00 +0000

Writing a Go benchmark feels simple. You drop Benchmark in front of a function name, loop from 0 to b.N, run go test -bench=., and get a number. The number feels authoritative. I spent about a year trusting benchmark numbers that were wrong — not wrong because of bugs, but wrong because of how the benchmark was written. The Go benchmark framework is excellent, but it has sharp edges that will mislead you until you learn to see them.

Lesson 5: Monolith vs Multi-Module — One go.mod or many? It depends.

Fri, 08 Nov 2024 00:00:00 +0000

When I first started structuring larger Go projects, I defaulted to what felt natural: one repository, one go.mod. It worked for a long time. Then I joined a project with four services in a single repo, each with different dependency requirements, and suddenly the single go.mod was pulling in every dependency of every service for every build. Tests for the email service were slow because the go test run was loading the ML inference library needed only by the recommendation service. That was when I started thinking seriously about module boundaries, not just package boundaries.

Lesson 3: Service Discovery — Finding services without hardcoding URLs

Wed, 06 Nov 2024 00:00:00 +0000

When I first started building Go microservices, every service had a config file with a list of URLs. order-service-url: http://10.0.1.42:8080. That worked fine until the service moved, scaled out, or the IP changed during a deployment. Then the deployment would fail, someone would update the config, redeploy, and we’d write a Jira ticket to “fix the discovery mechanism eventually.” Service discovery is that fix — it’s how services find each other without hardcoding network locations.

Lesson 6: Mocking Alternatives — Interfaces over mocks, always

Tue, 05 Nov 2024 00:00:00 +0000

Mocking has a bad reputation in the Go community, and some of it is deserved. Not because mocks are inherently wrong, but because the way most people use them — generating verbose stubs from interfaces, asserting on call counts, verifying argument order — produces tests that are coupled to implementation details rather than behaviour. Refactor the internals of a function without changing its public contract, and suddenly half your mocks break. That’s not a test problem. That’s a mock-as-test-double problem.

Lesson 4: Config Injection — Environment variables, flags, files — in that order

Sat, 02 Nov 2024 00:00:00 +0000

Configuration management is one of those topics that seems solved until you maintain a service that runs in four different environments, has twenty configurable parameters, and needs its secrets rotated without a redeployment. I’ve gone through several evolutionary stages on this: hardcoded values (the naive phase), a single config.yaml file, then twelve config-{env}.yaml files, and finally landing on what the 12-factor app methodology describes — environment variables as the source of truth for deployment-specific configuration.

Lesson 4: Signal Handling — Catch SIGTERM or lose your work

Wed, 30 Oct 2024 00:00:00 +0000

Most CLI tools work perfectly on the happy path and fail silently on the unhappy one. The user presses Ctrl-C, the OS sends SIGINT, and the process dies immediately — leaving a temp file half-written, a database connection open, or a progress bar frozen mid-operation. The problem is invisible because most of the time nobody looks at what gets left behind. Until a deployment script depends on that temp file being complete, or a database hits its connection limit, or a batch job loses six hours of progress because the container was terminated between checkpoints.

Lesson 5: Pagination Done Right — Offset pagination breaks at scale

Mon, 28 Oct 2024 00:00:00 +0000

I have shipped offset-based pagination more times than I would like to admit. It looks clean, it is trivially easy to implement, and it works perfectly — until the table reaches about 100,000 rows. Then it starts to slow down, and by a million rows it is actively harmful. I had a support dashboard that froze every time someone clicked to page 47. That was the moment I stopped using OFFSET.

Lesson 7: Refactoring Concrete to Generic — Start concrete, extract when proven

Fri, 25 Oct 2024 00:00:00 +0000

The advice “start concrete, extract when proven” is easy to say and surprisingly hard to follow when you’re in the middle of writing the third version of the same function. The temptation to generalize early is real. I’ve felt it. Most engineers who care about clean code have felt it.

But the cost of premature abstraction is higher than the cost of temporary duplication. A duplicated function can be removed with a search-and-replace. A bad abstraction gets built around, extended in wrong directions, and defended by sunk-cost thinking. This lesson is about how to do the refactoring correctly — waiting until the pattern is proven, then extracting it cleanly.

Lesson 2: CGo Performance and Pitfalls — The hidden cost of crossing the boundary

Thu, 24 Oct 2024 00:00:00 +0000

When I profiled a service that was spending 40% of its time in cgo calls, I thought I was measuring the C library. I was not. I was measuring the overhead of getting to the C library. The actual C work was fast. What was slow was the goroutine-to-OS-thread transition, the stack switching, and the runtime bookkeeping that happens every single time Go code crosses the C boundary. Understanding this overhead is what separates cgo code that runs fine from cgo code that becomes a bottleneck.

Lesson 5: Auth Middleware — Authentication is not authorization

Tue, 22 Oct 2024 00:00:00 +0000

A few years ago I audited a Go API where every endpoint was protected by an authentication middleware. The middleware checked for a valid JWT, extracted the user ID, and set it in the request context. The developer was proud of it — every route was secured. The problem was that the product had a concept of “organizations” — users belonged to organizations — and the API let you fetch any organization’s data as long as you were authenticated. The authentication was solid. The authorization was completely absent.

Lesson 4: Code Review Heuristics — What to look for in a Go PR

Sun, 20 Oct 2024 00:00:00 +0000

A good code review is not a diff-reading exercise. It’s a transfer of understanding — the reviewer asks “do I understand what this code does, why it does it, and what it doesn’t do?” If the answer to any of those is no, that’s a comment, not a nitpick. I’ve done hundreds of Go reviews and the feedback I give clusters into the same ten or fifteen patterns so reliably that I eventually wrote them down as a checklist. This lesson is that checklist, with examples.

Lesson 4: Correlation IDs — Connect the logs to the trace to the user

Fri, 18 Oct 2024 00:00:00 +0000

A support ticket lands: “User 8842 says their order failed at 2:47 PM yesterday.” You open your log aggregator. You search for user_id = 8842. You get 4,000 log lines — the user made 80 requests that afternoon. You filter to the 2:43–2:51 PM window. You get 300 lines. They interleave with log lines from 12 concurrent requests from other users because your log output is not partitioned by request. The error message, when you find it, says internal server error. No stack trace, no underlying cause, no request that produced it.

Lesson 4: Channel Misuse — You used a channel where a mutex would do

Tue, 15 Oct 2024 00:00:00 +0000

Go’s channels are genuinely great. They make certain concurrent programming patterns — pipelines, fan-out, fan-in, worker pools — natural and readable. Because they are idiomatic and distinctly Go-like, there is a tendency among Go developers to reach for them first whenever concurrency is involved. The result is code that uses channels to protect shared state, which is what mutexes are for, or code that passes one value through a channel with ceremony that could be replaced by a function call.

Lesson 3: Loop Variable Fix — The Go 1.22 change that fixed a decade of bugs

Sun, 13 Oct 2024 00:00:00 +0000

If you have written Go for more than a few weeks, you have hit this bug. Or you have reviewed code that had it and caught it. Or — if you were unlucky — you shipped it to production and spent an hour staring at a data race report wondering what on earth was happening. The loop variable capture bug was so common that it was essentially a Go rite of passage. Every Go tutorial mentioned it. Every linter had a rule for it. And for a decade, the answer was always “just copy the variable inside the loop.”

Lesson 4: Connection Pooling — One connection per request is a performance bug

Sat, 12 Oct 2024 00:00:00 +0000

The first time I benchmarked a Go service against a database, the numbers were embarrassing. Five hundred requests per second, each one taking 30 milliseconds to execute a trivially simple query. The query itself took 2 milliseconds on the database server. The other 28 milliseconds were TCP handshake plus TLS plus PostgreSQL authentication — repeated for every single request because I had no connection pool.

Connection pooling is one of those topics that feels like an advanced optimization until you discover that nearly every database driver in Go already pools connections by default — you just have to configure the pool instead of leaving it at its default settings, which are almost always wrong for your workload.

Lesson 5: Database Testing with Testcontainers — Mock the DB and you mock the truth

Thu, 10 Oct 2024 00:00:00 +0000

I used to mock databases. I had a clean Store interface, a MockStore implementation for tests, and 100% coverage on my service layer. I felt good about it. Then we migrated from MySQL to PostgreSQL and discovered that a dozen subtle behaviours we’d been mocking around were wrong — UPSERT semantics, NULL handling in GROUP BY, timestamp precision, transaction isolation differences. The mock had been lying to us for months. Testcontainers fixed that.

Lesson 3: Struct Tags — Metadata your compiler ignores but your framework reads

Tue, 08 Oct 2024 00:00:00 +0000

Struct tags are one of Go’s most practically useful metaprogramming tools and one of its least formally documented features. The syntax is simple — a raw string literal after the field type in a struct — but the convention built on top of it powers nearly every serialization library, ORM, validator, and configuration loader in the ecosystem. Understanding how tags work at the reflection level demystifies why encoding/json knows to use omitempty, why database/sql scanners can map column names to struct fields, and how you can build your own tag-driven behavior.

Lesson 2: LLM API Clients — Calling Claude, GPT, and Groq from Go

Sun, 06 Oct 2024 00:00:00 +0000

Most Go developers approach LLM APIs the same way they approach any REST API — write an HTTP client, handle errors, parse JSON. That instinct is correct, but LLM APIs have a few characteristics that require specific handling: they’re slow (seconds, not milliseconds), they have complex nested response structures, they support streaming, and the model selection and token management have real cost implications. This lesson is about building Go clients that handle all of this properly.

Lesson 4: Escape Analysis Deep Dive — The compiler decides where your data lives

Sat, 05 Oct 2024 00:00:00 +0000

I used to assume that every time I wrote &someStruct{} or returned a pointer from a function, I was creating a heap allocation. I was wrong — and the wrongness mattered for how I was designing APIs. After learning about escape analysis, I stopped guessing and started asking the compiler directly. This changed how I write Go.

The Problem

Go has two places to put data: the stack and the heap. Stack allocations are cheap — they’re just a pointer bump, and the stack frame is reclaimed automatically when the function returns. Heap allocations go through the memory allocator, require garbage collection, and have non-trivial overhead.

Lesson 6: Real-World Examples — Generics that survived code review

Wed, 02 Oct 2024 00:00:00 +0000

Lessons 1 through 5 were mostly about principles. This one is about code. Specifically, the five generic implementations I’ve used in real production systems that my teammates didn’t complain about. Each one passed code review, made it into production, and held up over time.

The pattern across all of them is consistent: the algorithm is identical regardless of the type, the duplication without generics would have been mechanical and ongoing, and the generic version is genuinely easier to read than the alternative.

Lesson 4: Returning Concrete Types — Give callers the real thing

Tue, 01 Oct 2024 00:00:00 +0000

There is a piece of Go advice that sounds almost too obvious to state, and yet I see it violated in production codebases every week: return concrete types from your functions. Not interfaces. Not interface{}. The actual, named, exported struct that your function produces.

The reason this feels controversial is that it conflicts with object-oriented instincts. In Java and C#, returning an interface from a factory is considered good practice — it hides the implementation detail and “programs to an interface.” In Go, that instinct leads to information loss, surprise type assertions, and constructors that promise less than they deliver.

Lesson 3: encoding/json Beyond Basics — Custom marshalers, streaming, and the traps

Mon, 30 Sep 2024 00:00:00 +0000

encoding/json is one of the first packages every Go developer uses and one of the last they fully understand. The basic json.Marshal / json.Unmarshal API is approachable. But the package contains a whole layer of capabilities — custom marshaling, streaming decoders, json.RawMessage for deferred parsing, interface-type fields, and a surprising number of edge cases — that separate the code that works in demos from the code that works in production with adversarial inputs.

Lesson 4: Interface Placement — Define interfaces where they're used, not where they're implemented

Sat, 28 Sep 2024 00:00:00 +0000

This is the Go idiom that surprises people coming from Java or C# the most. In those languages, you define an interface in the same place as (or even before) the implementation, and consumers import the interface. Go’s approach is the exact opposite, and it takes a while to internalize why. Once it clicks, it changes how you think about dependencies fundamentally.

The rule is: define an interface in the package that needs it, not in the package that satisfies it. It sounds backwards. It is not. It is one of the most powerful design decisions the language enables.

Lesson 4: String and Byte Conversions — The copy nobody sees

Wed, 25 Sep 2024 00:00:00 +0000

Go strings are immutable. Byte slices are mutable. Converting between them requires copying the data — every time, without exception, unless you use unsafe tricks you almost certainly shouldn’t. That sounds like a minor footnote, but it becomes a significant issue the moment you start handling large volumes of text: parsing HTTP requests, processing log lines, building JSON responses. I’ve watched a single string(b) call inside a tight loop add measurable latency to a production API, and the fix was two lines of code once I knew what to look for.

Lesson 3: Health Checks — Readiness vs liveness, and why both matter

Sun, 22 Sep 2024 00:00:00 +0000

I’ve seen two types of health check implementations in production: the ones that always return 200 OK, and the ones that actually check something. The first kind is theater — Kubernetes thinks the pod is healthy and routes traffic to it, but the pod is actually deadlocked or its database connection pool is exhausted. The second kind is what saves you at 3am.

Health checks are Kubernetes’s mechanism for deciding when a pod is ready to receive traffic and when it needs to be restarted. Get them right and Kubernetes becomes a genuinely reliable self-healing system. Get them wrong and you have an elaborate system that sends traffic to broken pods and restarts healthy ones.

Lesson 4: Error Responses — Your API errors are your documentation

Fri, 20 Sep 2024 00:00:00 +0000

I once integrated with an API that returned HTTP 200 for everything — successes and failures alike. The actual outcome was buried in a status field inside the JSON body. To know whether a request worked, you had to parse the response, check status, then switch on a string value that was inconsistently named across endpoints. Integrating with that API felt like defusing a bomb in the dark.

How you design error responses is not a detail. It is part of your public interface.

Lesson 4: SSRF and Injection — The URL your user gave you might be localhost

Wed, 18 Sep 2024 00:00:00 +0000

I reviewed a Go service that let users provide a “webhook URL” — we would call that URL when their account had a notification. The service fetched a preview of the URL to display in the UI. The developer who built it figured that since it only fetched the URL and never executed what was returned, it was safe. They had not considered that http://169.254.169.254/latest/meta-data/iam/security-credentials/ is also a URL.

SSRF — Server-Side Request Forgery — is the class of vulnerability where an attacker tricks your server into making an HTTP request to a target of their choosing, typically to access internal services that are not exposed to the internet. AWS instance metadata, Redis, internal Kubernetes API servers, admin dashboards, other services in your VPC — all are reachable from a server that blindly follows user-supplied URLs.

Lesson 3: Distributed Tracing with OpenTelemetry — Follow the request across services

Sun, 15 Sep 2024 00:00:00 +0000

We had an incident where checkout was timing out intermittently. The logs showed the API gateway receiving the request and returning a 504 after 30 seconds. The payment service logged nothing. The inventory service logged nothing. Something was hanging somewhere in the middle, and we had no way to see where.

I spent four hours bisecting the call graph by adding temporary log lines, redeploying, and re-triggering the error. We eventually found a database query in the inventory service that was waiting on a lock — a lock held by a background job nobody had thought to instrument. Logs told me what each service did in isolation. They told me nothing about the shape of a single request as it flowed across all of them.

Lesson 3: File I/O Patterns — Read, write, stream without loading everything into memory

Thu, 12 Sep 2024 00:00:00 +0000

CLI tools spend most of their life doing file I/O. Reading config files, processing log dumps, writing output, transforming data from stdin to stdout — it all comes down to bytes moving through your program. The difference between a CLI tool that handles 100MB files gracefully and one that runs out of memory on large inputs is almost always whether you read everything into memory or stream it.

Go’s standard library gives you everything you need to stream data efficiently. The key is knowing which functions to reach for and which ones to avoid when the input is large or unknown in size.

Lesson 2: Inter-Service Communication — HTTP, gRPC, or events? It depends on the coupling.

Tue, 10 Sep 2024 00:00:00 +0000

Every time I’ve seen a team choose their inter-service communication protocol by default — “we’ll use REST for everything” or “we’re going gRPC-native” — they’ve ended up with a transport mechanism that fights against some of their use cases. The choice between HTTP, gRPC, and event-driven messaging is a question about coupling: how tightly do these services need to be synchronized? The answer to that question selects your transport, not the other way around.

Lesson 5: Anti-Patterns — Just because you can doesn't mean you should

Sun, 08 Sep 2024 00:00:00 +0000

Every powerful tool has a failure mode that looks like success. With generics, the failure mode is this: you write something that compiles, works correctly, and is impressively abstract — but your teammates can’t read it, can’t debug it, and quietly work around it. I’ve written code like that. It felt clever in the moment. It was a problem in practice.

This lesson is about the patterns that sound good and turn out badly. I’m calling them out explicitly because they’re seductive — especially if you’ve spent time in Haskell or Scala and you know what generic abstractions can look like.

Lesson 3: Global Mutable State — The variable that breaks every test

Thu, 05 Sep 2024 00:00:00 +0000

There was a test suite I worked on where tests passed individually but failed when run together. The failure pattern was non-deterministic — sometimes test A broke test B, sometimes test C broke test A, and it changed with the -count flag. After two hours of bisecting, we found it: a package-level var config Config that every test modified by calling loadConfig("testdata/some-fixture.json"). The tests were sharing state without knowing it, and the one that ran last set the config for all the others.

Lesson 3: Idiomatic Naming — Names are your documentation

Wed, 04 Sep 2024 00:00:00 +0000

When I review Go code, naming problems tell me more about the author’s understanding of the codebase than almost anything else. A function called HandleRequest that parses JSON, queries a database, formats a response, and writes to a log tells me its author didn’t know what it does either. A variable called data in a function that handles three different kinds of data tells me the author stopped thinking halfway through. Names are the first layer of documentation — they’re read far more often than comments, and unlike comments, they can’t drift out of sync with the code.

Lesson 4: HTTP Handler Testing — httptest is your best friend

Sun, 01 Sep 2024 00:00:00 +0000

Every Go HTTP handler is just a function that takes a ResponseWriter and a *Request. That’s the entire contract. The fact that the standard library ships with a testing package that lets you call that function with a fake writer and a real request — without starting a server, without binding a port — is a gift that too many people overlook. I spent months spinning up actual servers in tests before I discovered net/http/httptest. I will not let you make the same mistake.

Lesson 3: Circuit Breaking — Stop calling the service that's already down

Wed, 28 Aug 2024 00:00:00 +0000

There’s a particular kind of production incident that goes like this: Service A calls Service B. Service B starts responding slowly because its database is under pressure. Service A’s goroutines pile up waiting for responses. After a few minutes, Service A is out of memory, and now two services are down instead of one. The postmortem note says “cascading failure.” The fix, which nobody implemented, is a circuit breaker.

The circuit breaker pattern comes from electrical engineering. When too much current flows through a circuit, the breaker trips — it opens the circuit and prevents more current from flowing until someone resets it. In software, the “current” is requests, and “tripping” means refusing to make calls to a failing downstream instead of piling up timeouts and consuming resources.

Lesson 1: Go Plugins and hashicorp/go-plugin — Extending Go apps without recompiling

Mon, 26 Aug 2024 00:00:00 +0000

The first time I needed a plugin system in Go, I went straight to plugin.Open in the standard library. Ten minutes later I was reading about RTLD flags and shared library loading on Linux, discovering that plugins had to be compiled with the same Go toolchain version as the host, and learning that once a plugin was loaded it could not be unloaded. My enthusiasm dropped sharply. Then I found hashicorp/go-plugin and understood that the Go community had largely agreed: real plugin systems in Go should run plugins as separate processes communicating over RPC, not as shared libraries in the same process.

Lesson 3: Method Sets and Addressability — Why your value can't satisfy that interface

Sun, 25 Aug 2024 00:00:00 +0000

I spent a solid twenty minutes staring at a compilation error that read “does not implement interface (Write method has pointer receiver)” and thinking: I can see the Write method right there. What is Go complaining about? Once I understood method sets and why addressability matters, the rule became obvious — and I have never needed to look it up since.

The Problem

Go lets you define methods with either a value receiver or a pointer receiver:

Lesson 3: Interface Pollution — More interfaces means more indirection

Thu, 22 Aug 2024 00:00:00 +0000

Interface pollution is not a hypothetical risk. I have walked into codebases where more than half the types in the package are interfaces, where every function parameter is an interface even when the concrete type is never substituted, and where adding a new feature means navigating six files just to trace what a single method call actually does. The code is technically “flexible” in the sense that every seam is abstract. In practice it is a maze with no map.

Lesson 3: Slice and Map Performance — The data structure tax

Tue, 20 Aug 2024 00:00:00 +0000

Slices and maps are so convenient in Go that it’s easy to forget they’re not free. They have hidden costs — in allocations, in CPU cache misses, in GC scanning time — that only become visible when you push them into a hot path and watch your benchmarks light up. I’ve been burned by both, sometimes in embarrassing ways, and building intuition for when those costs matter has saved me more than one production incident.

Lesson 3: internal/ Usage Patterns — Compiler-enforced encapsulation

Sun, 18 Aug 2024 00:00:00 +0000

Go does not have access modifiers in the Java or Kotlin sense. There is no protected, no package-private, no friend classes. You get exactly two visibility levels: exported (capital letter) and unexported (lowercase letter). That simplicity is a feature. But it creates a gap: how do you share something across packages within your own module without accidentally exposing it to the outside world?

The answer is internal/. It is one of the most underused and underappreciated tools in Go’s package system, and it is enforced by the compiler itself.

Lesson 2: io Patterns — Reader, Writer, and the composability that makes Go great

Fri, 16 Aug 2024 00:00:00 +0000

The io package is three hundred lines of interface definitions and a handful of utility functions. It is also the spine of the entire Go standard library. Every package that reads or writes data — os, net, compress/gzip, crypto/tls, encoding/json, bufio — does it through io.Reader and io.Writer. Once you understand these two interfaces, the standard library clicks into place as one coherent system.

I spent my first few months with Go treating io.Reader as the thing that HTTP response bodies happen to be. It wasn’t until I built a streaming CSV processor — piping data from S3 through gzip decompression into a CSV parser, all without loading the file into memory — that I understood what the interfaces were actually designed for.

Lesson 2: Performance Costs — reflect.ValueOf is not free

Thu, 15 Aug 2024 00:00:00 +0000

Every time I see reflection in a hot path, I know there is a performance conversation waiting to happen. Reflection in Go is not arbitrarily slow — it is predictably and measurably slow in specific ways. Understanding those costs, benchmarking them in your context, and knowing the standard mitigation patterns (primarily caching) lets you use reflection where it belongs without making your application noticeably slower.

The performance story of reflection has two parts: the cost of type inspection (getting a reflect.Type, reading fields, checking kinds) and the cost of value operations (getting a reflect.Value, reading or setting field values, calling methods). Type inspection is expensive the first time and cheap if cached. Value operations are expensive every time and there is no way to avoid that cost except to reduce how often you do them.

Lesson 4: Interfaces vs Generics — Behavior or data shape? That's your answer

Wed, 14 Aug 2024 00:00:00 +0000

One of the most common mistakes I see in Go codebases post-1.18 is people reaching for generics when interfaces were already the right tool — and vice versa. The two features look superficially similar. Both let you write code that works with multiple types. But they’re solving different problems, and using the wrong one makes code harder to read, test, and extend.

Here’s the question I ask myself every time: Is what varies the behavior, or the data shape? That single question gets me to the right answer ninety percent of the time.

Lesson 3: TLS Configuration — Your default HTTP server is unencrypted

Mon, 12 Aug 2024 00:00:00 +0000

When I started writing Go HTTP servers, I thought TLS was someone else’s problem. A load balancer in front of my service handled HTTPS termination, so my service only ever spoke plain HTTP on the internal network. That is a common and often defensible architecture. But it means that if anyone gains access to your internal network — a compromised service, a misconfigured cloud security group, a rogue container — all traffic between your services is plaintext. I learned this lesson not from a breach but from a penetration test report that listed it as a finding with a crisp paragraph explaining exactly why it mattered.

Lesson 2: Enhanced HTTP Routing — Method patterns in net/http, no more gorilla/mux

Sun, 11 Aug 2024 00:00:00 +0000

For most of my Go career, the standard library’s net/http.ServeMux was something I used for toy services and immediately replaced with gorilla/mux for anything real. The standard mux could not match HTTP methods. It could not extract path parameters. It matched prefixes in ways that surprised people. The moment a production service needed GET /users/{id} and POST /users, you reached for a dependency.

Go 1.22 changed that. The enhanced ServeMux now supports method matching, wildcard path parameters, and precedence rules that actually make sense. I rewrote three internal services to drop gorilla/mux after reading the release notes, and every one of them got shorter and simpler. This lesson covers exactly what changed and when you still might want a third-party router.

Lesson 2: Docker for Go — Multi-stage builds that produce tiny images

Sat, 10 Aug 2024 00:00:00 +0000

The first Dockerfile I wrote for a Go service produced a 1.2 GB image. It was based on golang:1.22, which includes the full Go toolchain, build cache, test infrastructure, and a complete Debian system. The compiled binary was 18 MB. I was shipping 1.2 GB to run 18 MB.

The second version, after learning about multi-stage builds, produced a 22 MB image. Same binary. No compiler. No package manager. No shell. Just the binary and the absolute minimum needed to run it. The difference matters not just for storage: smaller images pull faster, have smaller attack surfaces, and fail more obviously when a required file is missing.

Lesson 3: Request Validation — Never trust the caller

Thu, 08 Aug 2024 00:00:00 +0000

I once shipped an endpoint that accepted a limit query parameter for pagination. The valid range was 1–100. I did not validate it. Someone called it with limit=-1 and my database query returned every row in the table. The query took 45 seconds and brought the service to its knees. The fix was a two-line bounds check that I should have written from the start.

Validation is not optional. It is the contract between your API and the outside world.

Lesson 2: Config and Env Handling — Viper, envconfig, or just os.Getenv?

Mon, 05 Aug 2024 00:00:00 +0000

Configuration is one of those problems that looks trivial until it is not. A single environment variable is three lines of code. A configuration file with overridable environment variables, sensible defaults, validation, and reload-on-signal is a project in itself. Knowing when to use each approach — raw os.Getenv, struct-based env decoding, or a full configuration library like Viper — is more about understanding the tradeoffs than about which library is “best.”

Lesson 3: Integration Tests — Unit tests lie, integration tests prove

Thu, 01 Aug 2024 00:00:00 +0000

Unit tests feel productive. You write a function, you write a test, everything goes green, and you merge. But unit tests exist in a bubble — a bubble where every dependency returns exactly what you told it to return. The real world doesn’t do that. Your database serializes a time.Time differently than you expect. Your HTTP client follows a redirect your mock never mentioned. Your message queue drops a message under backpressure that your fake queue cheerfully delivered. I’ve had unit test suites where every test passed and the feature didn’t work in staging. Integration tests are what close that gap.

Lesson 1: Building MCP Servers in Go — Give AI agents tools with the Model Context Protocol

Tue, 30 Jul 2024 00:00:00 +0000

When Claude or another AI assistant needs to look up a database record, call an internal API, or read a file from your filesystem, it can’t do that on its own — it needs tools. The Model Context Protocol (MCP) is Anthropic’s open standard for giving AI agents exactly those tools. An MCP server is a small program you write that exposes tools via a JSON-RPC protocol; the AI client calls your server to invoke them. I find this genuinely exciting as a Go developer: Go’s concurrency model and fast startup time make it a natural fit for MCP servers.

Lesson 2: Metrics That Matter — Count, measure, alert

Sun, 28 Jul 2024 00:00:00 +0000

The first metrics dashboard I built for a Go service had forty-two graphs. CPU, memory, goroutine count, heap allocations, GC pause duration, request rate, error rate, and about thirty-five other things that felt important when I added them. Six months later I was on call at 3 AM and the service was degraded. I opened that dashboard, looked at forty-two graphs, and had no idea where to start.

Metrics are only useful when you know what to alert on, and you can only alert on things you understand. More metrics is not the same as better observability. The question is not “what can I measure?” but “what breaks, how do I know it’s broken, and how quickly can I narrow down why?”

Lesson 2: Giant God Structs — If your struct has 30 fields, it has 30 problems

Thu, 25 Jul 2024 00:00:00 +0000

I inherited a Go service where the primary domain object was a struct with 47 fields. Some were database columns, some were computed from other fields, some were HTTP response projections, some were used only during a specific workflow stage, and a handful were there because someone once needed a flag and adding a field to the God struct was the path of least resistance. The struct was everywhere — passed between functions, serialized to JSON, written to the database, and used as a GraphQL response type. Every change to it rippled through the entire codebase.

Lesson 2: Spotting Over-Abstraction — When your abstraction is the problem

Wed, 24 Jul 2024 00:00:00 +0000

There’s a version of Go code I see in almost every codebase that’s been touched by developers who came from Java or C# — it’s covered in interfaces, repositories, factories, and service layers that all wrap exactly one concrete implementation. No tests mock these interfaces. No second implementation exists. The abstraction is doing nothing except adding indirection. I’ve written code like this myself, and the tell is always the same: when something breaks, I have to jump through five files to understand what happens when I call CreateUser.

Lesson 1: CGo Basics — When you need C and how to call it safely

Mon, 22 Jul 2024 00:00:00 +0000

There is a saying in the Go community: “cgo is not Go.” It is not an insult. It is a warning. The moment you add import "C" to a file, you are no longer writing a pure Go program — you are writing a Go program that manages a C boundary, and all the things that make Go comfortable (fast builds, easy cross-compilation, the race detector, straightforward stack traces) become harder. You are doing it on purpose, because the alternative is worse.

Lesson 3: Good Patterns — Generic code should be boring

Mon, 22 Jul 2024 00:00:00 +0000

The best generic code I’ve ever written looks like the worst. No clever type wizardry, no five-level constraint hierarchies — just a function that clearly does one thing, works for any type that makes sense, and disappears into the background of a codebase. When someone reads it two years later and immediately understands it, that’s a win.

This lesson is about the patterns where generics genuinely shine. These are the ones that survived code review, that made the team’s lives measurably better, and that I’d reach for again without hesitation.

Lesson 2: Retries with Exponential Backoff — Retry right or retry forever

Sat, 20 Jul 2024 00:00:00 +0000

I once worked on a service that retried failed HTTP requests in a tight loop with no backoff and no jitter. When our upstream had a brief outage, every instance of our service fired retries simultaneously, on the same cadence, forever. The upstream came back online, got immediately hammered by a synchronized retry storm from fifty instances, went down again, and the cycle repeated for forty minutes. The “retry” logic had turned a five-minute outage into a cascading failure.

Lesson 2: Nil Interface Gotchas — nil is not nil when it has a type

Thu, 18 Jul 2024 00:00:00 +0000

A few months into my first production Go service, I had a bug that cost me two hours. A function returned an error, I checked if err != nil and it passed — but then further down the stack the program panicked trying to call .Error() on a nil pointer. The function had returned a nil *MyError, not a nil error. These are not the same thing, and until you internalize why, you will hit this bug.

Lesson 2: Stack vs Heap Intuition — The allocation you didn't know you made

Tue, 16 Jul 2024 00:00:00 +0000

There’s a class of performance bugs in Go that doesn’t show up in code review, doesn’t trigger the race detector, and doesn’t cause test failures. It just makes your service slowly worse under load. The source is almost always the same: heap allocations happening in places you didn’t intend, turning what should be fast stack operations into GC-visible objects that pile up until the collector has to stop and clean them up. Building an intuition for when Go allocates on the heap versus the stack was one of the single highest-leverage things I did to improve the services I work on.

Lesson 2: Consumer-Side Interfaces — Define where you use, not where you build

Mon, 15 Jul 2024 00:00:00 +0000

There is a convention I spent a long time following without questioning it: put the interface in the same package as the type that implements it. If I had a payment package with a Stripe struct, I would also define PaymentProcessor right there. Callers would import payment.PaymentProcessor. It felt natural — the interface lives next to the thing it describes.

Go’s designers had a different idea in mind, and it took me several refactoring sessions on a real codebase before I understood why it matters: interfaces should be defined by the package that uses them, not the package that implements them. The Go standard library does this consistently and for good reason.

Lesson 2: Avoiding Cyclic Dependencies — If packages import each other, your design is wrong

Fri, 12 Jul 2024 00:00:00 +0000

The Go compiler refuses to build a program with a cyclic import. It is not a warning. It is not a lint violation. It is a hard failure. I used to find this annoying when I was newer to the language. Now I consider it one of Go’s greatest gifts. The compiler is telling you something important: if package A needs package B and package B needs package A, you have not yet understood what the relationship between these two concepts really is.

Lesson 2: Fuzzing in Go — Let the machine find your edge cases

Wed, 10 Jul 2024 00:00:00 +0000

There’s a class of bugs that you will never find by thinking about edge cases. You’ll think about empty strings, about zero values, about negative numbers. But will you think about the string that’s exactly 65,536 bytes? Or the UTF-8 sequence that’s technically valid but trips up a specific parser codepath? Or the floating point value that serializes and then fails to deserialize because of a precision edge in your JSON handling? You won’t. But a fuzzer will find it in under a minute.

Lesson 2: Secret Handling — Env vars are not a vault

Mon, 08 Jul 2024 00:00:00 +0000

I once found database credentials committed directly in a Go source file — not in a toy project, in a staging environment of a real product. The developer who wrote it knew it was wrong, but they were “just testing” and forgot to revert it. That file lived in the repository for eight months before anyone noticed. By then, the credentials had been rotated, but the history was permanent.

Secret handling in Go is not primarily a coding problem. It is a discipline problem. The code patterns are simple. The failures happen when you treat secrets as a detail to clean up later, or when you assume that environment variables are inherently safe because they are not in source code.

Lesson 1: Service Boundaries — Split by business capability, not by technical layer

Sat, 06 Jul 2024 00:00:00 +0000

The most expensive architectural mistake I’ve seen teams make with microservices is splitting by technical layer instead of by business capability. I’ve seen systems with a “UserDataService,” a “UserLogicService,” and a “UserNotificationService” — three services that all have to be deployed together for any user-related feature to work, that share a database, and that call each other synchronously for every request. They’re not microservices; they’re a distributed monolith with extra network latency.

Lesson 2: Middleware Patterns — Wrap the handler, not the logic

Fri, 05 Jul 2024 00:00:00 +0000

The first time I wrote authentication logic, I put it directly inside each handler. Copy-paste, then copy-paste again. By handler number five I had four slightly different versions of the same JWT check scattered across the codebase. When the security team asked me to add a new validation step, I had to find and update every single one. That was the day I understood middleware.

The Problem

Business logic in a handler should answer one question: “What does this endpoint do?” But handlers inevitably accumulate cross-cutting concerns — logging, authentication, rate limiting, request ID injection, panic recovery. When these live inside the handler body, every handler becomes a tangle of concerns that are hard to test, hard to change, and impossible to apply consistently.

Lesson 1: net/http Deep Dive — The most important package you use wrong

Tue, 02 Jul 2024 00:00:00 +0000

Every Go web service I’ve reviewed starts with net/http. Most of them use it correctly for the obvious parts and incorrectly for the subtle ones. The package API is deceptively simple — http.HandleFunc, http.ListenAndServe, and you’re serving HTTP. But the design decisions underneath — how request routing works, what a Handler actually is, how the server manages connections, what the default timeouts are — contain enough traps to keep a senior engineer busy for a week.

Lesson 2: Type Parameters and Constraints — Teaching the compiler what you mean

Mon, 01 Jul 2024 00:00:00 +0000

The hardest part of learning Go generics isn’t the concept — it’s the syntax. The first time I read a function signature like func Keys[K comparable, V any](m map[K]V) []K, I did a double-take. It looks like someone snuck type annotations from another language into Go. But once it clicks, it’s actually pretty elegant — every piece is there for a reason.

This lesson is about understanding type parameters and constraints deeply enough that you can write them yourself without copying from examples. That’s the threshold that separates “I’ve used generics” from “I understand generics.”

Lesson 1: Static Binaries — One file, zero dependencies, deploy anywhere

Sun, 30 Jun 2024 00:00:00 +0000

The first time I deployed a Go binary to a production server, I was braced for the usual ceremony: SSH in, install the right runtime version, copy over config files, fiddle with symlinks. Instead, I ran scp and then the binary, and it just worked. No installation. No dependency hell. No “but it works on my machine.” The binary contained everything it needed.

This is Go’s single greatest operational advantage: the compiler produces a self-contained executable. Understanding exactly how this works — and how it can break — makes the difference between a deploy that takes five minutes and one that takes an afternoon.

Lesson 1: When Reflection Is Justified — The last resort that sometimes is the only resort

Fri, 28 Jun 2024 00:00:00 +0000

Go’s reflect package carries a reputation: “don’t use it unless you have to.” That advice is correct but incomplete. Understanding when you actually have to use it — and when you are just reaching for it out of habit from dynamic languages — is the difference between reflection that pulls its weight and reflection that creates unmaintainable, slow, panic-prone code that confuses every future reader of the codebase.

Reflection lets Go inspect and manipulate values, types, and struct fields at runtime without static type information. It is the mechanism behind encoding/json, database/sql’s row scanning, struct validators, ORM frameworks, and dependency injection containers. It is also the mechanism behind a lot of code that should have just used a map or an interface.

Lesson 1: Structured Logging with slog — Printf is not observability

Tue, 25 Jun 2024 00:00:00 +0000

I spent two years writing Go services that logged like this:

log.Printf("processing order %s for user %d, amount %.2f", orderID, userID, amount)

It worked fine — until the day I needed to find every failed payment over $500 from a specific user across three weeks of logs in a production incident at 2 AM. I was grepping through gigabytes of text, trying to parse freeform strings with jq, getting nowhere. The logs existed. The information was technically there. But I couldn’t query it in any meaningful way.

Lesson 1: Building CLIs with Cobra — From main.go to production CLI

Sat, 22 Jun 2024 00:00:00 +0000

Every Go project that grows into something useful eventually needs a command-line interface. Maybe it starts as a quick main.go with os.Args[1] checks and a switch statement. That works until you need subcommands, flags, help text, shell completion, and version information — and suddenly you are maintaining a hand-rolled argument parser that nobody wants to touch. Cobra is the standard library-grade solution to this problem, and learning to structure a Cobra application properly saves you from rewriting it twice.

Lesson 1: Escape Analysis — Where your data lives matters more than how you write it

Thu, 20 Jun 2024 00:00:00 +0000

I spent the first two years of writing Go completely unaware that the compiler was making decisions about my code that I never asked for — and that those decisions were quietly shaping the performance profile of everything I shipped. Escape analysis is the mechanism behind all of it. Once I understood it, I started reading code differently. Not just “does this work?” but “where does this data live, and did I give the compiler a chance to put it somewhere fast?”

Lesson 1: Interface Everywhere Syndrome — Not every dependency needs an interface

Tue, 18 Jun 2024 00:00:00 +0000

When I came to Go from a Java background, I brought some habits with me that made my code worse, not better. The most persistent one was defining an interface for every dependency, regardless of whether there was any realistic chance of substituting an alternative implementation. I wrote UserRepositoryInterface, EmailSenderInterface, LoggerInterface — an entire shadow type system that mirrored every concrete type in the codebase. Every file had a corresponding interface file. The codebase was twice as large as it needed to be and no easier to test.

Lesson 1: Refactoring Go Code Safely — Change structure without changing behavior

Sun, 16 Jun 2024 00:00:00 +0000

Refactoring is the one activity that makes codebases better without adding features — and it’s also the activity most likely to introduce bugs if done carelessly. I learned this the hard way on a payments service where I renamed a function, ran the tests, saw green, deployed, and watched a webhook handler silently stop processing because it had been calling the old function name through a string-based registry I hadn’t touched. The tests were green because the old function still existed — I just hadn’t deleted it yet. The refactor was correct; the process was not.

Lesson 1: Subtests and t.Run — Name your test cases or debug blind

Sat, 15 Jun 2024 00:00:00 +0000

I used to write tests the way I wrote the first functions I ever wrote in Go — flat, repetitive, and with names so generic that when they failed, I had no idea which case broke. “TestParseDate failed” is not information. It’s a dare. Go figure out which of the twelve implicit cases in the body is responsible. I wasted hours doing exactly that before I committed to subtests.

t.Run is one of those language features that looks like a small convenience and turns out to be load-bearing for any serious test suite. Once you start using it, you wonder how you ever shipped anything without it.

Lesson 1: HTTP Client Internals — Transport, connection reuse, and the pool you forgot to configure

Fri, 14 Jun 2024 00:00:00 +0000

The first production Go service I wrote hammered our database proxy with thousands of new TCP connections every minute. The proxy started refusing connections. The on-call engineer thought it was the database. It wasn’t. It was me — specifically, my decision to create a new http.Client on every request and then never read the response body to completion. I spent three hours debugging what turned out to be two lines of misunderstood standard library behavior.

Lesson 1: Designing HTTP APIs in Go — net/http is enough

Wed, 12 Jun 2024 00:00:00 +0000

I spent the first few months of writing Go services reaching straight for a framework. Chi, Gorilla, Echo — I cycled through them trying to find the “right” one. Then a colleague reviewed my code and asked a simple question: “What does this framework give you that net/http doesn’t?” I couldn’t answer. That conversation changed how I think about HTTP in Go.

The Problem

Most developers coming from Node.js or Python assume they need a framework to build a real HTTP API. Express, FastAPI, Django — these tools abstract away so much of the protocol that going back to the raw standard library feels like stepping down. But Go’s net/http package is not an afterthought. It was designed with production use in mind, and the gap between it and popular frameworks is much smaller than you’d expect.

Lesson 1: Interface Representation — Two words that carry your abstractions

Mon, 10 Jun 2024 00:00:00 +0000

I remember the first time I hit a bug where err != nil returned true even though the function clearly returned nil. I spent forty minutes staring at perfectly reasonable-looking code before I realized I had no idea what an interface actually is at the memory level. Once I understood the two-word representation, that class of bug never confused me again.

The Problem

Go interfaces are the backbone of polymorphism in the language. You use them constantly — io.Reader, error, fmt.Stringer. But most developers treat them as magic. You assign a concrete value, you call methods, and somehow Go figures out which implementation to dispatch to at runtime.

Lesson 1: When NOT to Use Interfaces — Abstractions cost clarity

Sat, 08 Jun 2024 00:00:00 +0000

The first time I saw Go interfaces click in a codebase, I made the same mistake every developer makes: I started reaching for them everywhere. If I had a struct, I made an interface for it. If I had two types that shared even one method name, I defined an interface over both. It felt disciplined. It felt like proper software engineering. It was making my code worse.

The uncomfortable truth about Go interfaces is that they are most powerful when you use them least. Unlike Java, where every class implementing an interface is an explicit declaration, Go interfaces are satisfied implicitly. That means there is almost zero syntax cost to adding one. And that near-zero cost hides the real cost: cognitive overhead, indirection, and the loss of explicit signal about what a piece of code actually does.

Lesson 1: What Generics Solve in Go — Remove duplication without hiding intent

Fri, 07 Jun 2024 00:00:00 +0000

I spent two years writing Go before generics shipped in 1.18, and I’ll be honest — I didn’t miss them at first. Go’s simplicity felt like a feature. Then I found myself maintaining a codebase with six nearly-identical sort functions, a MinInt, MinFloat64, MinInt64, and a comment that said “do not touch, generated.” That’s when I started caring.

Generics in Go aren’t a revolution. They’re a targeted fix for a specific, real pain point: you had to either use interface{} and lose type safety, or repeat yourself across every concrete type you cared about. Neither option aged well.

Lesson 1: Input Validation — Trust nothing from the wire

Wed, 05 Jun 2024 00:00:00 +0000

The first production security incident I dealt with involved a simple integer field in a JSON body. The client sent a negative number where we expected a positive quantity. We hadn’t validated it. The result was a negative charge on a purchase — we were effectively paying customers money. That taught me more about input validation than any security course.

Every byte that arrives over the wire is adversarial by default. Not because every user is malicious, but because your assumptions about the data are not enforced by anything except your own code. HTTP gives you a byte stream. JSON decoding gives you Go values. Neither of those steps checks whether the values make sense for your business logic. That job is yours.

Lesson 1: Range Over Integers and Iterators — for i := range 10 and the iterator protocol

Tue, 04 Jun 2024 00:00:00 +0000

I have written for i := 0; i < n; i++ so many times that my fingers type it on autopilot. The three-clause for loop is fine — it works, everyone understands it, and Go has always had it. But when Go 1.22 shipped for i := range 10, I stopped and stared at it for a moment. Not because it was complicated. Because it was so obviously the right thing that I wondered why it had taken this long.

Lesson 1: Package Boundaries — One package, one responsibility, zero excuses

Mon, 03 Jun 2024 00:00:00 +0000

I have refactored a lot of Go codebases — my own included. And the single most common structural mistake I see is the utils package. Or helpers. Or common. Or sometimes the worst offender of all: a package named after the entire application domain with fifty unrelated files sitting inside it. When I first started writing Go seriously, I made all of these mistakes. This lesson is about why package boundaries matter and how to get them right.

Lesson 25: What's Next — Your roadmap from beginner to production Go

Sat, 11 May 2024 00:00:00 +0000

You made it. Twenty-five lessons ago you didn’t know what package main meant. Now you understand variables, types, functions, error handling, interfaces, goroutines, testing, JSON, file I/O, the type system, and the entire toolchain. That is not beginner knowledge anymore.

But there’s a gap between knowing the language and writing Go the way experienced Go developers write it. This lesson is about that gap — what it is, how to close it, and what to build while you do.

Lesson 24: The Go Toolchain — build, test, vet, fmt — your daily tools

Tue, 07 May 2024 00:00:00 +0000

One of the things that drew me to Go was that the toolchain ships with the language. You don’t need to choose a build tool, a formatter, or a test framework — they’re all there from day one, and they’re all invoked the same way: go <command>. This lesson is a tour of the tools you’ll use every single day.

The Basics

go run and go build

You’ve used go run throughout this course. It compiles your code and immediately executes it — perfect for development. Under the hood it creates a temporary binary and runs it, then throws the binary away.

Lesson 23: The Type System — Types, aliases, conversions, and embedding

Thu, 02 May 2024 00:00:00 +0000

When I first came to Go from Python, the type system felt like a lot of ceremony. Why can’t I just use an int where a float64 is expected? Why do I need to define a whole new type just to give an integer more meaning? The answers to those questions turned out to be one of the things I now appreciate most about Go. Types aren’t bureaucracy — they’re a way of making your code explain itself.

Lesson 22: File I/O — Reading and writing files the Go way

Fri, 26 Apr 2024 00:00:00 +0000

At some point every program needs to persist something — a config file, a log, a data export. File I/O is one of those topics that sounds tedious but is genuinely satisfying once it clicks. Go gives you a few different layers to work with, from the low-level os package to convenient one-liners. I’ll show you all of them so you can pick the right tool for the job.

The Basics

Reading a file the simple way

For most cases where the file is small enough to fit in memory, os.ReadFile is all you need:

Lesson 21: JSON and HTTP — Reading and writing the web's language

Sun, 21 Apr 2024 00:00:00 +0000

Almost every program I write these days talks to something over HTTP — a third-party API, a database service, a webhook. And almost everything speaks JSON. So learning how Go handles JSON and HTTP isn’t an advanced topic; it’s one of the most practical skills you can pick up early.

In this lesson I’ll walk you through converting Go structs to JSON and back, decoding JSON from an API response, and making real HTTP requests — all using only Go’s standard library. No third-party packages needed.

Lesson 20: Testing in Go — Every Go file gets a test file

Wed, 17 Apr 2024 00:00:00 +0000

I used to think testing was something you did after you finished writing code — a checkbox you ticked before committing. Go changed that attitude for me, not by lecturing me about best practices, but by making testing so straightforward that there was no excuse not to do it. The tooling is built in, the conventions are clear, and writing a test in Go takes about as long as writing the function itself. After a few weeks with Go, I started writing tests alongside my code, then slightly before it. The feedback loop became addictive.

Lesson 19: Context — Passing deadlines and cancellation through your code

Fri, 12 Apr 2024 00:00:00 +0000

There’s a moment in every Go developer’s journey when they realize that starting an operation isn’t the hard part — stopping it cleanly is. What happens when a user cancels a request? What happens when a database query takes 30 seconds instead of 300 milliseconds? Without a way to communicate “stop what you’re doing,” those goroutines keep running, consuming resources for something that no longer matters.

That’s the problem context solves. It gives you a standard way to carry a cancellation signal, a deadline, and a small amount of request-scoped data through your entire call stack. Once you understand it, you’ll see why the Go standard library passes it as the first parameter to almost every function that does I/O.

Lesson 18: The sync Package — Coordination tools for concurrent code

Sat, 06 Apr 2024 00:00:00 +0000

Goroutines make concurrency easy to start, but easy to start isn’t the same as easy to get right. The first time I ran multiple goroutines that touched shared data, I got a data race — a situation where two goroutines read and write the same variable at the same time, producing unpredictable results. The Go race detector caught it immediately, but I still had to understand how to fix it.

Lesson 17: Go Modules — Managing dependencies without pain

Tue, 02 Apr 2024 00:00:00 +0000

Before Go modules existed, managing dependencies was genuinely painful. People used all sorts of third-party tools with their own conventions, and getting a new contributor up and running on a project could eat half a day. I started learning Go after modules became the standard, and I took for granted how smooth the experience was — until I read the old blog posts describing what came before. It made me appreciate go mod init in a way that’s hard to describe.

Lesson 16: Packages and Imports — Organizing code like a professional

Wed, 27 Mar 2024 00:00:00 +0000

Every Go program I’ve written has taught me the same lesson over and over: good code isn’t just about what you write inside functions — it’s about how you organize those functions in the first place. When I started with Go, I crammed everything into one file. It worked, until it didn’t. By the time I had a few hundred lines, I couldn’t find anything. That’s when packages stopped being an abstract concept and became something I genuinely needed.

Lesson 15: Select — Waiting on multiple channels at once

Fri, 22 Mar 2024 00:00:00 +0000

By now you know how to create goroutines and how to communicate between them using channels. But what happens when a goroutine needs to listen to two channels at the same time? Maybe it’s waiting for work to arrive, but it also needs to stop if a timeout fires. With a single channel you’d be stuck — receiving from one blocks the other.

select solves this. It’s like a switch statement for channels. It waits until one of several channel operations is ready, then executes that case. If multiple are ready at the same time, it picks one at random.

Lesson 14: Channels — How goroutines talk to each other

Mon, 18 Mar 2024 00:00:00 +0000

In the last lesson, I showed you how to run code concurrently with goroutines. But goroutines that can’t talk to each other aren’t very useful. What if one goroutine produces a result that another needs? What if you want to signal that work is done without using a WaitGroup? That’s where channels come in.

Go’s guiding philosophy on concurrency is: “don’t communicate by sharing memory; share memory by communicating.” Channels are the mechanism for that. Instead of multiple goroutines reading and writing the same variable, they pass values through a channel — and the channel ensures only one goroutine handles the value at a time.

Lesson 13: Goroutines — Lightweight threads that cost almost nothing

Tue, 12 Mar 2024 00:00:00 +0000

One of the first things people told me about Go was “it makes concurrency easy.” I was sceptical — concurrency is never easy. But the more I used goroutines, the more I understood what they meant. It’s not that concurrency becomes simple. It’s that the cost of starting a concurrent task drops so low that you stop avoiding it.

In most languages, spawning a thread involves megabytes of stack memory and significant overhead. A Go goroutine starts with about 2KB of stack. You can run tens of thousands of them on a normal laptop without breaking a sweat.

Lesson 12: Error Handling — Errors are values, not exceptions

Wed, 06 Mar 2024 00:00:00 +0000

The first time I wrote Go after years of Python and JavaScript, I kept waiting for the try/catch block. It never came. Instead, almost every function returned two values: the result, and an error. I had to check the error every single time. It felt tedious at first. After a few weeks, I realised it was one of the best design decisions in the language.

In Go, errors are just values. They’re not special. They don’t teleport up the call stack. They sit right there, in your return value, waiting for you to deal with them.

Lesson 11: Interfaces — Contracts without the paperwork

Sat, 24 Feb 2024 00:00:00 +0000

When I first learned about interfaces in Go, I expected something complicated — annotations, implements keywords, class hierarchies. Instead, Go just asked: “does your type have the right methods?” That’s it. No paperwork. No explicit declaration. If your type does what the interface requires, it satisfies the interface automatically.

This sounds small, but it changes how you design programs entirely.

The Basics

An interface in Go is a named set of method signatures. Any type that implements those methods automatically satisfies the interface. You don’t declare that you’re satisfying it. Go figures it out at compile time.

Lesson 10: Pointers — Addresses, not magic

Sat, 17 Feb 2024 00:00:00 +0000

Pointers have a reputation for being scary. In C, they’re the source of buffer overflows, dangling references, and cryptic crashes. In Go, pointers are much tamer. There’s no pointer arithmetic, the garbage collector handles memory for you, and the rules are simpler. But pointers are still important — without them, you can’t write Go programs that mutate data through function calls, and you can’t use pointer receivers (which we covered in the last lesson).

Lesson 9: Methods — Functions that belong to a type

Sun, 11 Feb 2024 00:00:00 +0000

In the last lesson we defined a User struct. We could pass it to functions — birthday(u), sendEmail(u), formatName(u). That works, but there’s a better way: we can attach functions directly to the User type. Then instead of birthday(u) we write u.Birthday(). Those are called methods.

Methods make code more readable, more organized, and closer to how we naturally think about objects — “a user does birthday-related things” rather than “a birthday function takes a user.”

Lesson 8: Structs — Your first custom type

Wed, 07 Feb 2024 00:00:00 +0000

So far we’ve been working with Go’s built-in types: strings, ints, booleans, slices, maps. Those are great, but real programs deal with real-world things — users, orders, products, messages. You need a way to group related data together and give it a meaningful name. In Go, that’s a struct.

If you come from Python, think of a struct as a lightweight class that holds data (but with no inheritance, and methods are defined separately). If you come from JavaScript, think of it as a typed object. If you come from C, structs work almost exactly the same way.

Lesson 7: Strings, Runes, and Bytes — Strings aren't what you think

Fri, 02 Feb 2024 00:00:00 +0000

Strings look simple. You write "hello", you print it, done. But when I first started working with non-ASCII text in Go — names with accents, emoji, Chinese characters — things started behaving oddly. len("café") returned 5, not 4. Iterating with a regular index loop gave me garbled output. It took me a while to understand why, and once I did, a lot of things clicked.

The short version: Go strings are sequences of bytes, not characters. Once you internalize that, the rest makes sense.

Lesson 6: Maps — Key-value pairs that power everything

Sat, 27 Jan 2024 00:00:00 +0000

Every language has some version of the dictionary or hash map. Python calls it a dict, JavaScript calls it an Object or Map, Ruby calls it a Hash. In Go, it’s just called a map. Once you understand how Go maps work, you’ll reach for them constantly — they’re one of the most useful data structures in the language.

The Basics

Creating a map

The zero value of a map is nil. A nil map is readable (it returns zero values) but not writable. If you try to write to a nil map, your program panics. The safe way to create a map is with make:

Lesson 5: Arrays and Slices — Slices are what you actually use

Mon, 22 Jan 2024 00:00:00 +0000

Go has two sequence types: arrays and slices. I’ll tell you upfront — arrays are rarely used directly. They exist, they matter for understanding how things work under the hood, but in day-to-day Go programming you’ll almost always reach for a slice instead.

Slices are Go’s workhorse collection type. They’re flexible, they grow when you need them to, and they’re used everywhere: in standard library APIs, in function parameters, in HTTP handlers. Understanding slices well will make you a much more effective Go programmer than memorizing syntax ever will.

Lesson 4: Functions — Small functions are Go's building blocks

Wed, 17 Jan 2024 00:00:00 +0000

If there’s one thing experienced Go programmers agree on, it’s this: write small functions. Not tiny, cryptic one-liners, but focused functions that do one thing and are easy to test. Go’s function syntax encourages this style — it’s clean, explicit, and has one feature that’s genuinely different from most languages you’ve used before: multiple return values.

In Python you can return a tuple. In JavaScript you can return an array. But in Go, returning two or three values is a first-class language feature with its own syntax, and it fundamentally changes how error handling works. By the end of this lesson you’ll understand Go functions well enough to start writing real, useful programs.

Lesson 3: Control Flow — if, for, and switch are all you need

Fri, 12 Jan 2024 00:00:00 +0000

Every program you’ll ever write needs to make decisions and repeat actions. “If this condition is true, do that. Otherwise, do something else.” “Keep doing this until we run out of items.” These are the fundamental building blocks of logic, and Go handles them with just three constructs: if, for, and switch.

That’s it. No while. No do-while. No foreach as a separate keyword. Go’s designers made a deliberate choice to keep the language small — fewer constructs means fewer ways to do the same thing, which means code is more consistent and easier to read across different projects and teams.

Lesson 2: Variables and Types — Go is typed, and that's a good thing

Mon, 08 Jan 2024 00:00:00 +0000

If you’re coming from Python or JavaScript, Go’s type system might feel like extra work at first. Why should you have to tell the compiler that a variable holds a number? Can’t it just figure it out?

Here’s the thing — it usually can. Go has type inference, so you rarely have to write out types explicitly. But when types are written out, every person reading your code knows exactly what kind of data they’re dealing with. There’s no guessing, no surprises at runtime because a string snuck in where you expected a number. Go catches those mistakes at compile time, before your code ever runs.

Lesson 1: Your First Go Program — Hello World is just the beginning

Wed, 03 Jan 2024 00:00:00 +0000

I remember the first time I ran a Go program. The compiler yelled at me for an unused import, and I thought, “Okay, this language has opinions.” That’s not a bad thing. Go’s strictness is part of what makes it so readable and maintainable. Once you understand why Go works the way it does, it starts to feel less like friction and more like clarity.

In this lesson you’re going to write your first Go program, understand every single line of it, and learn the basic tools you’ll use every day. By the end, “Hello, World!” won’t feel like a throwaway demo — it’ll feel like a foundation.