阅读中文版本

Cache Key Normalisation

Normalising the cache key collapses requests that are semantically identical but differ in ordering, case, or irrelevant parameters, raising the hit rate.

Definition

Cache key normalisation is the process of canonicalising a request’s identity, such as sorting query parameters and trimming insignificant values, so equivalent requests share one entry.

It matters for API caches and CDNs where clients construct the same logical request in many textual forms. Compared to simpler alternatives, this concept fits best when the trade-off it represents is the one the system actually cares about.

When to use it

A common use case is applying it at the boundary where the cost of getting it wrong is highest, and the scenario usually involves a concrete guarantee the system must uphold. Unlike an ad hoc approach, it makes that guarantee explicit, reviewable, and testable.

How it works

Two URLs that differ only in parameter order or default values denote the same resource, so treating them as distinct splits the cache and lowers the hit rate.

Over-normalisation is the opposite risk: dropping or reordering a parameter that does change the response causes one variant to be served for another request.

Trade-offs and alternatives

The key should include exactly the inputs that affect the response, which means auditing vary behaviour and the parameter set whenever the endpoint changes. The main drawback is the extra complexity it introduces, so the benefit should clearly outweigh that cost before a team adopts it.

Common misconceptions

A persistent misconception is that the raw URL is always a correct cache key. Another is that normalising keys cannot cause incorrect responses. For example, an engineer who assumes otherwise may design around a guarantee that does not actually exist, which only becomes obvious under load or failure.

Anti-patterns to avoid

Two recurring anti-patterns are to including volatile parameters such as a request identifier in the key and to normalising away a parameter that actually changes the response. Both tend to surface as hard-to-debug production issues rather than obvious test failures. Related concepts include Read-Through Caching, Negative Versus Positive Caching, Cache Preloading and Warming.