You have a working service class. Now you need to add logging. Then caching. Then metrics. Then retry logic. If you keep cramming all of that into the original class, you end up with a 500-line method where the actual business logic is buried under infrastructure concerns. The Decorator Pattern solves this by letting you wrap objects with new behavior while keeping the same interface.

The core idea: a decorator implements the same interface as the object it wraps, delegates the core work to that object, and adds its own behavior before or after. Each decorator is a thin, single-responsibility layer.

Real-world example: Suppose you have an OrderService with a placeOrder(order) method. Instead of modifying that class, you build decorators:

• LoggingOrderService — logs the order ID before and after delegation
• MetricsOrderService — records latency and success/failure counts
• RetryOrderService — retries on transient failures up to 3 times

You compose them at the wiring layer:

service = RetryOrderService(LoggingOrderService(MetricsOrderService(RealOrderService())))

Each class is 15–30 lines. Each is independently testable. You can reorder them, remove one, or add a new one without touching any of the others. The RealOrderService never knows it's being decorated.

Where this beats inheritance: If you used subclassing, you'd face a combinatorial explosion. Logging + metrics? New subclass. Logging + retry? Another subclass. Logging + metrics + retry? Yet another. With n behaviors, inheritance gives you up to 2ⁿ - 1 subclasses. Decorators give you exactly n classes that compose freely. For 5 cross-cutting concerns, that's 31 subclasses vs. 5 decorators.

When to use it:

• Cross-cutting concerns like logging, caching, auth checks, or retries
• When you want to toggle behavior at runtime or through configuration
• When the Open/Closed Principle matters — extending behavior without modifying existing, tested code

When to avoid it:

• If you only ever need one fixed combination, a simple wrapper method is clearer
• If decorators need to inspect each other's internal state — that signals the responsibilities aren't actually independent
• Deep decorator stacks (5+ layers) can make debugging stack traces harder. If you hit this, consider whether middleware pipelines or aspect-oriented approaches fit better

Practical tip: In languages with interfaces or protocols, define the contract explicitly. Every decorator and the real implementation should implement the same interface. This makes the compiler enforce correctness instead of relying on convention.