Update caching docs for opt-in queries

Documents opt-in caching with marker interface/attribute, serializer preference selection, and updated defaults across reference, recipes, and package README.

Author: mheidari988

docs/extensions/caching.md

@@ -52,17 +52,30 @@ builder.Services.AddMediatR(cfg =>
 
 `QueryCachingBehavior<TRequest, TResponse>` applies cache-aside semantics:
 
-- The default predicate caches request types whose names end with `Query` (case-insensitive).
+- The default predicate caches requests that opt in via `ICacheableQuery` or `[CacheableQuery]`.
 - The cache key uses the request type name as the resource and a SHA256 hash of the request payload.
 - Cache hits short-circuit the handler; cache misses store the handler result.
 
+Opt-in a query by marker interface or attribute:
+
+```csharp
+using CleanArchitecture.Extensions.Caching;
+using CleanArchitecture.Extensions.Caching.Abstractions;
+
+[CacheableQuery]
+public record GetTodosQuery : IRequest<TodosVm>;
+
+// or
+public record GetUserQuery(int Id) : IRequest<UserDto>, ICacheableQuery;
+```
+
 Configure request selection and TTLs via `QueryCachingBehaviorOptions`:
 
 ```csharp
 builder.Services.AddCleanArchitectureCaching(
     configureQueryCaching: options =>
     {
-        options.CachePredicate = request => request is ICacheableQuery; // your own marker interface
+        options.CachePredicate = request => request is ICacheableQuery;
         options.DefaultTtl = TimeSpan.FromMinutes(2);
         options.TtlByRequestType[typeof(GetUserQuery)] = TimeSpan.FromSeconds(30);
         options.CacheNullValues = false;
@@ -75,7 +88,7 @@ builder.Services.AddCleanArchitectureCaching(
 - `DefaultCacheKeyFactory` hashes the request payload as JSON (deterministic SHA256).
 - `ICacheScope` supplies the namespace and optional tenant segment.
 
-If you customize keys, keep them deterministic and stable across versions.
+If you customize keys, keep them deterministic and stable across versions. For user-scoped data, include user context in the hash or namespace.
 
 ## Choose a cache adapter
 
@@ -110,6 +123,8 @@ builder.Services.AddSingleton<ICacheSerializer>(sp =>
     new SystemTextJsonCacheSerializer(new JsonSerializerOptions(JsonSerializerDefaults.Web)));
 ```
 
+When multiple serializers are registered, set `CachingOptions.PreferredSerializer` to a content type or serializer type name.
+
 ## Stampede protection and entry options
 
 - `CachingOptions.StampedePolicy` controls locking, timeouts, and jitter.

docs/recipes/caching.md

@@ -40,7 +40,20 @@ builder.Services.AddMediatR(cfg =>
 });
 ```
 
-4. Add invalidation for write operations (commands or domain events).
+4. Opt in queries to caching.
+
+```csharp
+using CleanArchitecture.Extensions.Caching;
+using CleanArchitecture.Extensions.Caching.Abstractions;
+
+[CacheableQuery]
+public record GetOrdersQuery : IRequest<OrdersVm>;
+
+// or
+public record GetUserQuery(int Id) : IRequest<UserDto>, ICacheableQuery;
+```
+
+5. Add invalidation for write operations (commands or domain events).
 
 ```csharp
 await cache.RemoveAsync(cacheScope.Create("GetOrdersQuery", hash));

docs/reference/caching-options.md

@@ -9,13 +9,13 @@
 | `DefaultEntryOptions` | `CacheEntryOptions` | `CacheEntryOptions.Default` | Default entry options when no overrides are provided. |
 | `StampedePolicy` | `CacheStampedePolicy` | `CacheStampedePolicy.Default` | Locking and jitter defaults. |
 | `MaxEntrySizeBytes` | `long?` | `null` | Maximum payload size in bytes. |
-| `PreferredSerializer` | `string?` | `null` | Preferred serializer name/content type when multiple serializers are registered. |
+| `PreferredSerializer` | `string?` | `null` | Preferred serializer type name or content type when multiple serializers are registered. |
 
 ## QueryCachingBehaviorOptions
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `CachePredicate` | `Func<object,bool>` | Types ending with `Query` | Determines cacheable requests. |
+| `CachePredicate` | `Func<object,bool>` | `ICacheableQuery` or `[CacheableQuery]` | Determines cacheable requests. |
 | `ResourceNameSelector` | `Func<object,string>?` | `null` | Custom resource name for cache keys. |
 | `HashFactory` | `Func<object,string>?` | `null` | Custom hash for cache keys. |
 | `DefaultTtl` | `TimeSpan?` | `00:05:00` | Default TTL for cached queries. |
@@ -40,4 +40,3 @@
 | `EnableLocking` | `bool` | `true` | Enable per-key locking. |
 | `LockTimeout` | `TimeSpan` | `00:00:05` | Max wait for a lock. |
 | `Jitter` | `TimeSpan?` | `00:00:00.050` | Random jitter applied to expirations. |
-| `RefreshAhead` | `TimeSpan?` | `null` | Refresh-ahead interval (provider-dependent). |

src/CleanArchitecture.Extensions.Caching/README.md

@@ -59,9 +59,24 @@ builder.Services.AddMediatR(cfg =>
 });
 ```
 
-## Step 4 - What to expect
+## Step 4 - Opt-in queries
 
-- Queries (types ending with `Query`) are cached by default; commands are not.
+Only queries that opt in are cached by default. Use the marker interface or attribute:
+
+```csharp
+using CleanArchitecture.Extensions.Caching;
+using CleanArchitecture.Extensions.Caching.Abstractions;
+
+[CacheableQuery]
+public record GetTodosQuery : IRequest<TodosVm>;
+
+// or
+public record GetUserQuery(int Id) : IRequest<UserDto>, ICacheableQuery;
+```
+
+## Step 5 - What to expect
+
+- Only queries marked with `ICacheableQuery` or `[CacheableQuery]` are cached by default.
 - First request is a cache miss; the second identical request is a cache hit.
 - Default TTL is 5 minutes; override with `QueryCachingBehaviorOptions.DefaultTtl` or `TtlByRequestType`.
 - Debug logs show `Cache hit` and `Cache miss` messages when caching is active.