Go-Handbook-for-Software-Engineers

module

v1.2.0 Latest Latest Go to latest Published: Oct 3, 2026 License: Apache-2.0

README ¶

Go Handbook for Software Engineers

A practical, engineering-focused Go handbook: from the fundamentals to production-grade, distributed, and financial systems. Every runnable example compiles and is verified by CI on every push.

Start here

git clone https://github.com/TharunKumarReddyPolu/Go-Handbook-for-Software-Engineers.git
cd Go-Handbook-for-Software-Engineers
go test ./08-concurrency/... -race   # see the examples run

Read the Markdown in any editor. Every section is fully written, with chapter status and plans tracked in ROADMAP.md.

The sections

#	Section	Status
01	Go Fundamentals	✅ In depth
02	The Go Language	✅ In depth
03	Data Structures	✅ In depth
04	Functions, Methods & Interfaces	✅ In depth
05	Error Handling	✅ In depth
06	Packages & Modules	✅ In depth
07	Generics	✅ In depth
08	Concurrency	✅ In depth
09	Memory & Runtime	✅ In depth
10	Testing	✅ In depth
11	Tooling	✅ In depth
12	HTTP & Networking	✅ In depth
13	Databases	✅ In depth
14	Backend Development	✅ In depth
15	Microservices	✅ In depth
16	Distributed Systems	✅ In depth
17	Messaging	✅ In depth
18	Kafka with Go	✅ In depth
19	Performance	✅ In depth
20	Observability	✅ In depth
21	Security	✅ In depth
22	Production Go	✅ In depth
23	Go Internals	✅ In depth
24	System Design with Go	✅ In depth
25	FinTech with Go	✅ In depth
26	Go Interview Preparation	✅ In depth
27	Open Source	✅ In depth
28	Projects	✅ In depth

Progress and the writing order live in ROADMAP.md.

How to read it

Pick the row that matches you, read the sections in order:

You are...	Read in this order
New to Go	01 → 02 → 03 → 04 → 05 → 10 → 08
Coming from Java/Python/C++/JS	01 Section 8 → 04 → 05 → 02 → 07 → 08
A backend engineer	12 → 13 → 05 → 14 → 10 → 20 → 22 → 21
Building distributed systems	08 → 15 → 16 → 17 → 18 → 19 → 24
Building fintech systems	25 → 16 → 18 → 21 → 28
Preparing for interviews	26 → 08 → 19 → 09 → 23 → 24
Contributing to open source	27 → CONTRIBUTING.md → 11 → 06

What makes this handbook different

Depth before breadth. A topic is not covered until it answers: what is it, why does it exist, how does it work, when should I not use it, what goes wrong in production, and how would I debug it?
Few, deep chapters. Sections ship 4-7 chapters, not a chapter per topic: related topics fold into one chapter, and a topic another section already owns is a cross-reference, never a duplicate. One worked example per section, with tests that pin its claims.
Everything compiles. Every example package passes go build, go vet, go test -race, and staticcheck in CI on every push. Tests skip cleanly when optional infrastructure (Kafka, Postgres) is absent.
No copying. Original explanations; official documentation is linked under Further Reading at the end of each chapter, never reproduced.

Go changes every six months. Version-dependent claims are stamped ("Introduced in Go X"); the convention is explained in meta/versioning.md.

Contributing

Contributions are welcome: see CONTRIBUTING.md for the chapter template and the verification commands every PR must pass. By participating you agree to the Code of Conduct.

⭐ Support the Project

If this handbook helps you on your path to mastering Go, please consider:

Star History

Learn Go smarter, not harder! 🧠

Inspired by practical production engineering with key insights from official sources like go.dev, Effective Go, the Go Blog, and real-world systems experience. Happy Coding! 🚀

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
01-go-fundamentals
examples/hello command Command hello is the smallest real program in the handbook: a module, a main package, one import, one statement.	Command hello is the smallest real program in the handbook: a module, a main package, one import, one statement.
examples/zero command Command zero prints the zero value of the core types.	Command zero prints the zero value of the core types.
02-go-language
examples/seqops Package seqops is the handbook's worked example for section 02: slice aliasing, map semantics, and pointer-vs-value receiver rules, each with a deterministic test next to it.	Package seqops is the handbook's worked example for section 02: slice aliasing, map semantics, and pointer-vs-value receiver rules, each with a deterministic test next to it.
03-data-structures
examples/heap Package heap is the handbook's worked example for 03-data-structures chapter 4: a generic binary min-heap ordered by a caller-supplied less function, with the Fix and Remove support (index bookkeeping) that container/heap makes awkward.	Package heap is the handbook's worked example for 03-data-structures chapter 4: a generic binary min-heap ordered by a caller-supplied less function, with the Fix and Remove support (index bookkeeping) that container/heap makes awkward.
examples/lru Package lru is the handbook's worked example for 03-data-structures chapter 9: the map-plus-list LRU with O(1) operations, an eviction hook, and hit/miss/eviction counters.	Package lru is the handbook's worked example for 03-data-structures chapter 9: the map-plus-list LRU with O(1) operations, an eviction hook, and hit/miss/eviction counters.
examples/ring Package ring is the handbook's worked example for 03-data-structures chapter 8: a fixed-capacity FIFO with drop-oldest eviction, plus the bounded RecentKeys dedup shape from that chapter's idioms section.	Package ring is the handbook's worked example for 03-data-structures chapter 8: a fixed-capacity FIFO with drop-oldest eviction, plus the bounded RecentKeys dedup shape from that chapter's idioms section.
04-functions-methods-interfaces
examples/di Package di is the handbook's worked example for 04-functions-methods- interfaces: the design clinic's UserService (chapter 4) built with consumer-side interfaces (chapter 3), constructor injection (chapter 5), and an invariant-enforcing domain type (chapter 6).	Package di is the handbook's worked example for 04-functions-methods- interfaces: the design clinic's UserService (chapter 4) built with consumer-side interfaces (chapter 3), constructor injection (chapter 5), and an invariant-enforcing domain type (chapter 6).
05-errors
examples/errorslib Package errorslib is the handbook's worked example of production error design: a sentinel, a typed domain error with a classification code, and a retryability predicate.	Package errorslib is the handbook's worked example of production error design: a sentinel, a typed domain error with a classification code, and a retryability predicate.
examples/service command Package main is a small but complete demonstration of error mapping at an HTTP boundary: a payment service that returns classified domain errors, and a handler that translates them to responses exactly once.	Package main is a small but complete demonstration of error mapping at an HTTP boundary: a payment service that returns classified domain errors, and a handler that translates them to responses exactly once.
07-generics
examples/genlib Package genlib is the handbook's worked example for 07-generics: the constraint styles from chapter 2, the API style from chapter 4, and the instantiation-table tests that chapter 5's rules imply.	Package genlib is the handbook's worked example for 07-generics: the constraint styles from chapter 2, the API style from chapter 4, and the instantiation-table tests that chapter 5's rules imply.
08-concurrency
examples/01-toy command Command toy is stage 1 of the concurrency progression: a producer and a consumer sharing one channel with single ownership (producer closes).	Command toy is stage 1 of the concurrency progression: a producer and a consumer sharing one channel with single ownership (producer closes).
examples/02-workerpool command Command workerpool is stage 2 of the concurrency progression: a bounded worker pool with a results channel.	Command workerpool is stage 2 of the concurrency progression: a bounded worker pool with a results channel.
examples/03-workerpool-cancel command Command cancelable-pool is stage 3 of the concurrency progression: the worker pool from stage 2, made leak-free under cancellation.	Command cancelable-pool is stage 3 of the concurrency progression: the worker pool from stage 2, made leak-free under cancellation.
examples/04-backpressure command Command backpressure is stage 4 of the concurrency progression: the pool with a bounded intake queue and explicit load shedding.	Command backpressure is stage 4 of the concurrency progression: the pool with a bounded intake queue and explicit load shedding.
examples/05-jobprocessor command Command jobprocessor is stage 5 of the concurrency progression: a production-shaped job processor.	Command jobprocessor is stage 5 of the concurrency progression: a production-shaped job processor.
09-memory-runtime
examples/memwatch Package memwatch is the handbook's worked example for 09-memory-runtime: the leak taxonomy from chapter 5 as runnable code.	Package memwatch is the handbook's worked example for 09-memory-runtime: the leak taxonomy from chapter 5 as runnable code.
10-testing
examples/calculator Package calc is the handbook's testing subject: a tiny expression evaluator small enough to read, real enough to exercise table tests, doubles, fuzzing, and benchmarks.	Package calc is the handbook's testing subject: a tiny expression evaluator small enough to read, real enough to exercise table tests, doubles, fuzzing, and benchmarks.
12-http-networking
examples/api command Package main is the handbook's runnable example for section 12: a payments API built entirely from the standard library, composing the five chapters: routing (01), middleware (02), the JSON boundary (03), error mapping from 05-errors, and graceful shutdown (05).	Package main is the handbook's runnable example for section 12: a payments API built entirely from the standard library, composing the five chapters: routing (01), middleware (02), the JSON boundary (03), error mapping from 05-errors, and graceful shutdown (05).
13-databases
examples/bank Package bank is the handbook's worked example for 13-databases: a payments store with the repository boundary from chapter 4.	Package bank is the handbook's worked example for 13-databases: a payments store with the repository boundary from chapter 4.
14-backend-development
examples/service command Command service is the handbook's complete backend example for section 14, now carrying section 20's observability: RED metrics and tracing middleware on every request, business metrics on the payments domain, a /metrics endpoint, and OTel wiring with correct shutdown ordering (flush spans AFTER the server drains).	Command service is the handbook's complete backend example for section 14, now carrying section 20's observability: RED metrics and tracing middleware on every request, business metrics on the payments domain, a /metrics endpoint, and OTel wiring with correct shutdown ordering (flush spans AFTER the server drains).
examples/service/internal/config Package config is chapter 2's loader: typed at the edge, validated once at boot, immutable after.	Package config is chapter 2's loader: typed at the edge, validated once at boot, immutable after.
examples/service/internal/payments Package payments is the domain core from chapter 1: the service owns business decisions and defines the store interface it needs.	Package payments is the domain core from chapter 1: the service owns business decisions and defines the store interface it needs.
examples/service/internal/platform/httpjson Package httpjson is the platform JSON boundary from 12 Section 3: write, decode with limits, and the single error-mapping point.	Package httpjson is the platform JSON boundary from 12 Section 3: write, decode with limits, and the single error-mapping point.
examples/service/internal/platform/httpmw Package httpmw is the platform middleware from 12 Section 2: the chain constructor plus the three every service needs.	Package httpmw is the platform middleware from 12 Section 2: the chain constructor plus the three every service needs.
examples/service/internal/platform/obshttp Package obshttp is the observability middleware from section 20: metrics (RED, Prometheus format), distributed tracing (OTel), and the log-correlation tie between them.	Package obshttp is the observability middleware from section 20: metrics (RED, Prometheus format), distributed tracing (OTel), and the log-correlation tie between them.
examples/service/internal/platform/otelwiring Package otelwiring is chapter 3: process-global tracer setup, collapsed into an Init/shutdown pair.	Package otelwiring is chapter 3: process-global tracer setup, collapsed into an Init/shutdown pair.
15-microservices
examples/resilience Package resilience is the handbook's worked example for 15-microservices chapter 3: the resilience quartet (timeout, retry, circuit breaker, bulkhead) as small composable pieces, each with a deterministic test.	Package resilience is the handbook's worked example for 15-microservices chapter 3: the resilience quartet (timeout, retry, circuit breaker, bulkhead) as small composable pieces, each with a deterministic test.
16-distributed-systems
examples/lease Package lease is the handbook's worked example for 16-distributed-systems chapter 3: a lease with fencing tokens.	Package lease is the handbook's worked example for 16-distributed-systems chapter 3: a lease with fencing tokens.
17-messaging
examples/messaging Package messaging is the handbook's worked example for 17-messaging: a minimal in-memory queue broker implementing the queue model's exact semantics: ack, redeliver with attempt counts and backoff, dead-letter with triage metadata, plus the envelope versioning rule from chapter 4.	Package messaging is the handbook's worked example for 17-messaging: a minimal in-memory queue broker implementing the queue model's exact semantics: ack, redeliver with attempt counts and backoff, dead-letter with triage metadata, plus the envelope versioning rule from chapter 4.
18-kafka-with-go
examples command consumer.go adapts franz-go for the order-events processor: the poll -> process -> commit loop with process-then-commit ordering (at-least-once), bounded batches, and clean drain on cancellation.	consumer.go adapts franz-go for the order-events processor: the poll -> process -> commit loop with process-then-commit ordering (at-least-once), bounded batches, and clean drain on cancellation.
19-performance
examples/profiling command Command profiling is a deliberately slow service for practicing the pprof workflow in 19-performance/01-measure-first.md.	Command profiling is a deliberately slow service for practicing the pprof workflow in 19-performance/01-measure-first.md.
21-security
examples/secure Package secure is the handbook's worked example for 21-security: a pinned-algorithm bearer-token verifier (chapter 2), a two-layer token-bucket limiter with TTL eviction (chapter 4), and an allowlisted outbound fetcher (chapter 5).	Package secure is the handbook's worked example for 21-security: a pinned-algorithm bearer-token verifier (chapter 2), a two-layer token-bucket limiter with TTL eviction (chapter 4), and an allowlisted outbound fetcher (chapter 5).
23-go-internals
examples/internals Package internals is the handbook's worked example for 23-go-internals: each function demonstrates one internal behavior with a test that pins it deterministically: escape analysis (via testing.AllocsPerRun), the typed-nil interface trap and its honest fix, and map iteration order discipline.	Package internals is the handbook's worked example for 23-go-internals: each function demonstrates one internal behavior with a test that pins it deterministically: escape analysis (via testing.AllocsPerRun), the typed-nil interface trap and its honest fix, and map iteration order discipline.
25-fintech-with-go
examples/ledger Package ledger is the handbook's educational double-entry ledger: integer minor units, balanced immutable entries, derived balances.	Package ledger is the handbook's educational double-entry ledger: integer minor units, balanced immutable entries, derived balances.
tools
linkcheck command Command linkcheck validates internal, relative Markdown links in the handbook.	Command linkcheck validates internal, relative Markdown links in the handbook.