Design patterns are not a catalogue to memorise. They are names for shapes of code that keep showing up because the same problems keep showing up: behaviour that varies by case, objects that are tricky to build, cross-cutting work like retries and caching, an outside API that does not fit yours, and many things that want to know when something happened. This lesson follows one request, "when will my parcel arrive?", through the code that answers it. Each hop is a pattern solving one specific problem, and each failure scenario is a pattern used in the wrong place or the wrong order. By the end you can spot the problem first, pick the pattern second, and explain to a reviewer what it costs.
Difficulty: Advanced · Know this first: Lesson 166, Lesson 44, Lesson 36
This bar splits one delivery-window request. It is a worked example, not a measurement. The partner call dominates on a good day, which is why the cache, the retry, and the breaker around it matter so much, and why their order decides what a bad day looks like.
Move the sliders. Retries multiply both the latency a request can pay and the load on the partner. A breaker in the right place caps both. The adapter hop above follows your worst case.
expected attempts = 1 + p + p² + … up to the attempt limit, where p is the failure rate · worst case = attempts × timeout · partner load = expected attempts × normal load
With the breaker outside and open, a request costs one fast rejection and the fallback.
Retry storm: every request multiplies load on a failing partner
Three questions. No score is saved anywhere — this is just you against the material.
Patterns grow in four levels: first recognising the problem each one solves, then composing them, then using them at service boundaries where order and failure matter, and finally knowing when a pattern costs more than the problem it solves.
At the basic level you learn each pattern as an answer to a problem you can see in code. Behaviour varies by case: Strategy. Which object to create depends on runtime data: Factory. Business logic should not know where data lives: Repository. You learn to spot the smell, such as the same switch statement in three files, before you reach for the cure.
Types:
Uses: pricing rules per region, ETA per carrier, storage behind a domain service.
Where it breaks: a pattern applied to a problem that is not there, such as a factory that only ever builds one class. It adds a file and a hop and solves nothing.
Try it: Basic
The same switch on carrier appears in four files. What is the first pattern to reach for?
Now do it: Find a switch or if-chain that appears in more than one place in your code and sketch the strategy interface that would replace it.
At the intermediate level you compose patterns and prefer composition over inheritance. A decorator wraps an object with the same interface to add caching, logging, or metrics. An adapter wraps an outside API to present your interface. Observer lets many listeners react to one event. State moves state-dependent behaviour into one class per state.
Types:
Uses: clients for partner APIs, instrumented repositories, status-driven behaviour, internal event hooks.
Scale and failure: deep decorator stacks are hard to debug, because the stack trace passes through five wrappers; keep them few and named. A synchronous observer couples the publisher's latency to the slowest listener. The trade is flexibility against how many hops a reader must follow to find what actually happens.
Try it: Intermediate
You want caching and metrics on RouteRepository without editing it. Which pattern?
Now do it: Pick one external API your code calls and list the partner-specific details that leak past the first class that calls it. That class should become the adapter.
At the advanced level patterns meet the network, and their composition decides how failures behave. Resilience decorators have a conventional order, the one Polly and resilience4j document: timeout innermost so each attempt is bounded, the circuit breaker around it so it counts every attempt, the retry around the breaker, and the fallback outermost. The retry must treat "breaker open" as a final answer. Adapters own error translation as well as data translation. Observers that cross processes become events with at-least-once delivery, so their handlers must be idempotent.
Types:
Uses: every call to a dependency you do not control.
Scale and failure: three attempts against a partner that is failing every call triples its load exactly when it can least take it; the breaker, counting each attempt, is what stops the multiplication within a few failures. The two classic mistakes are retries with no breaker at all, and a retry that retries the breaker's own "open" rejection with backoff, which fills threads with sleeping requests. The cost is tuning: thresholds, timeouts, and retry budgets need real numbers from the dependency's latency distribution, not defaults.
Try it: Advanced
What is the conventional nesting for calls to a partner API?
Now do it: Use the retry simulator above: find the failure rate at which three attempts double the partner's load.
At the master level you remove patterns as readily as you add them. Every pattern costs a reader a hop; it is worth it only when the problem it solves is real and present. You refactor toward a pattern when the second or third case arrives, not in anticipation of it, and you write down a team's pattern language: which patterns this codebase uses, where, and why, so that every reader recognises them.
Types:
Uses: design reviews and long-lived codebases, where the question is whether the next reader will understand it faster or slower.
Trade-off: a well-placed pattern makes change cheap in the direction it anticipates and expensive in every other direction. Master-level judgement is choosing which direction of change is likely, and leaving the code plain where none is.
Try it: Master
A reviewer finds a Factory, an interface, and a Strategy, all with exactly one implementation that has not changed in two years. What is the master-level call?
Now do it: Find one abstraction in your codebase with a single implementation and no test that uses another. Decide whether it is a seam you need or one you can remove.
A pattern is easier to review when the composition is written down as one expression. This is the wiring for the delivery-window service; reading it outside in tells you exactly what happens on a bad day.
routes = Metrics(CachingRouteRepository(PostgresRouteRepository(db), ttl=300))
partner = Fallback(
Retry(
CircuitBreaker(Timeout(PartnerCarrierAdapter(http), ms=800),
open_after=5, half_open_after_s=30),
attempts=2, backoff="jitter", never_retry=[BreakerOpen]),
fallback=HistoricalWindow(routes))
factory = WindowStrategyFactory({
"own_fleet": OwnFleetWindow(routes),
"partner": PartnerCarrierWindow(partner, routes),
"intl": CustomsAverageWindow(routes)})
events = AsyncEventBus(workers=2) # observers never run on the request thread
events.subscribe("WindowShown", AnalyticsRecorder(warehouse))
events.subscribe("WindowShown", AccuracyTracker(metrics))
windows = WindowService(factory, ParcelStates(), events)One composition root. Every pattern is visible in the wiring, and the resilience order can be checked by reading one expression.
Five requests against a partner that always fails, with three attempts each. First with retries and no breaker, then with a breaker inside the retry that opens after two failures, and a retry that does not retry "breaker open". Count the calls that actually reach the partner.
# python3 breaker_saves.py
class BreakerOpen(Exception):
pass
def partner(counter):
counter["calls"] += 1
raise TimeoutError("partner down")
def retry(fn, attempts=3):
def wrapped(c):
for i in range(attempts):
try:
return fn(c)
except BreakerOpen:
raise # final: never retry an open breaker
except TimeoutError:
if i == attempts - 1:
raise
return wrapped
def breaker(fn, open_after=2):
state = {"fails": 0}
def wrapped(c):
if state["fails"] >= open_after:
raise BreakerOpen() # fail fast, partner untouched
try:
return fn(c)
except TimeoutError:
state["fails"] += 1
raise
return wrapped
for name, stack in [("retry, no breaker", retry(partner)),
("retry(breaker(partner))", retry(breaker(partner)))]:
c = {"calls": 0}
for _ in range(5):
try:
stack(c)
except (TimeoutError, BreakerOpen):
pass
print(f"{name}: partner called {c['calls']} times for 5 requests")
Expected: with no breaker, 15 calls, three for every request, all against a partner that is down. With the breaker inside the retry, 2 calls: the first request's first two attempts open the breaker, its third attempt gets "breaker open" and stops, and the next four requests fail fast without touching the partner. Put a fallback outside the retry and all five requests get an answer.
A shipping service I reviewed called four partner carriers through a shared HTTP client wrapped as Retry(CircuitBreaker(client)), with three attempts and a two-second timeout. It had worked for a year, because partners rarely failed hard.
The wiring became Fallback(Retry(Breaker(Timeout(call)))), with "breaker open" on the retry's never-retry list, and a separate thread pool per partner as a bulkhead. The composition root is now reviewed like code that matters, because it is: one line of retry configuration decided whether one partner's bad afternoon stayed one partner's problem.
A pricing service must compute delivery prices for three products (standard, express, same-day), in two currencies, with discounts that change every month, and call a tax service that is sometimes slow. Design it with patterns, and name the problem each one solves.
Do the three products share any pricing logic, or are they fully different? Who changes the discount rules, engineers or a business team? What should happen when the tax service is slow: wait, use a cached rate, or fail? Do other services need to know when a price is computed?
Say 300 price requests a second at peak, with a 150 ms p99 target. The tax service's p99 is 400 ms on a bad day, so it cannot be called synchronously without a timeout and a fallback.
PricingStrategy per product behind a factory; DiscountRule objects loaded from configuration and applied as a chain; Money as a value object with currency; a TaxClient adapter wrapped as Fallback(Breaker(Retry(Timeout()))) with a cached-rate fallback; PriceComputed published asynchronously for analytics. The composition root written out in one place.
Discount rules as code are type-checked and need a deploy; as configuration they change without a deploy and need validation and tests of their own. A cached tax rate keeps prices fast and may be slightly wrong for a few minutes; the business has to agree that is acceptable before the fallback ships.