阅读中文版本

Cache-Control Directives

Cache-Control controls freshness, revalidation, and shared versus private storage, so the wrong directive either serves stale data or wastes origin capacity.

Definition

Cache-Control is a response header whose directives tell client and shared caches how long a response is fresh, when it may be reused, and under what conditions it must revalidate.

It governs every HTTP cache in the path, from the browser to the CDN and any reverse proxy in between. 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

no-store forbids writing the response to disk at all, while no-cache permits storage but requires revalidation before reuse, a distinction often confused.

public and private control whether shared caches may retain a response, and s-maxage overrides max-age specifically for shared caches.

Trade-offs and alternatives

Revalidation directives such as must-revalidate and stale-while-revalidate shape behaviour once the response is stale, changing both correctness and perceived latency. 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 no-store and no-cache mean the same thing. Another is that max-age applies equally to browsers and shared caches. 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 setting a long max-age on a URL whose content changes and to omitting private and letting a shared cache store personalised responses. Both tend to surface as hard-to-debug production issues rather than obvious test failures. Related concepts include Cache Key Normalisation, Read-Through Caching, Negative Versus Positive Caching.