From 9688910acfbef1322f4c8def8f556d5f9119e4db Mon Sep 17 00:00:00 2001
From: DavidHLP <lysf15520112973@163.com>
Date: Sun, 20 Sep 2026 00:22:13 +0800
Subject: [PATCH 1/3] refactor(cache): collapse loader orchestrator onto bound
 constructor entry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 3-arg unbound constructor and the 7-arg per-call callback entry only
existed to serve the old test wiring protocol; production RedisProCache
already binds the three callbacks at construction. Delete both shallow
entries, validate the required callbacks with Objects.requireNonNull at
construction (assembly errors now fail at construction, not per call),
and have executeSyncLoad/executeLoad read the bound final fields so all
loader behavior flows through the single 4-arg orchestrate seam.

Migrate every LoaderOrchestratorTest case onto the same constructor-bound
path the production adapter uses, preserving the bloom / sync / hit /
null / loader-failure / write-back-tolerance assertions, and add the
constructor-validation, cross-call no-state, and null-value-wrapper-hit
cases required by the accepted design (L01-L10, §2.5).
---
 .../cache/redis/cache/LoaderOrchestrator.java | 103 ++----
 .../redis/cache/LoaderOrchestratorTest.java   | 332 ++++++++++--------
 2 files changed, 205 insertions(+), 230 deletions(-)

diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/cache/LoaderOrchestrator.java b/src/main/java/io/github/davidhlp/spring/cache/redis/cache/LoaderOrchestrator.java
index 65f63a2e..132d744d 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/cache/LoaderOrchestrator.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/cache/LoaderOrchestrator.java
@@ -6,6 +6,7 @@
 
 
 import io.github.davidhlp.spring.cache.redis.chain.model.CachePolicyView;
+import java.util.Objects;
 import java.util.concurrent.Callable;
 import java.util.function.BiConsumer;
 import java.util.function.Consumer;
@@ -39,15 +40,16 @@
  *   <li><b>locality</b>:bloom + sync + load 协议 + 异常翻译规则全部内聚在一处文件,
  *       无需在 {@code RedisProCache} 与若干 seam 间跳转</li>
  *   <li><b>testability</b>:orchestrator 仅依赖 {@link BloomGate} / {@link SyncSupport} /
- *       {@link SyncLockTimeout} + 3 个 callback(redisKey / doubleCheck / putAfterLoad);
+ *       {@link SyncLockTimeout} + 3 个构造期绑定的 callback(redisKey / doubleCheck / putAfterLoad);
  *       单测可零 RedisProCache fixture 验证决策分支({@code BloomShortCircuited} /
  *       {@code Loaded} / {@code LoadedWithWriteBackFailure} / {@code LoadFailed})</li>
  *   <li><b>leverage</b>:{@code RedisProCache.get(key, loader)} 主体仅 1 行委派 + switch 翻译</li>
  * </ul>
  *
  * <p><b>callback 协议</b>:orchestrator 不继承 {@code RedisCache},因此需要 cache-specific 操作
- * (key 派生 / 双检 / 写回)以 callback 形式由 {@code RedisProCache} 注入;writer 入口则直接
- * 使用静态 {@link #readThrough} 并传入字节适配:
+ * (key 派生 / 双检 / 写回)以 callback 形式在构造期由 {@code RedisProCache} 绑定;三个 callback
+ * 均为必需,缺失属于装配错误,构造时用 {@link Objects#requireNonNull} 带参数名拒绝。
+ * writer 入口不构造本类,直接使用静态 {@link #readThrough} 并传入字节适配:
  * <ul>
  *   <li>{@code Function<Object, String> redisKeyFn} — 派生 Redis key 用于 BloomGate 与 SyncSupport</li>
  *   <li>{@code Function<Object, Cache.ValueWrapper> doubleCheckFn} — 缓存读原语(走
@@ -125,98 +127,56 @@ public record LoadFailed<T>(Throwable cause) implements LoadOutcome<T> {
     private final Function<Object, Cache.ValueWrapper> boundDoubleCheckFn;
     private final BiConsumer<Object, Object> boundPutAfterLoad;
 
-    public LoaderOrchestrator(@Nullable BloomGate bloomGate,
-                              @Nullable SyncSupport syncSupport,
-                              @Nullable SyncLockTimeout syncLockTimeout) {
-        this(bloomGate, syncSupport, syncLockTimeout, null, null, null);
-    }
-
     /**
-     * 生产构造:一次性绑定 cache-specific 回调,隐藏 loader 编排的 callback 组装细节。
+     * 生产构造:一次性绑定保护依赖与 cache-specific 回调,隐藏 loader 编排的 callback 组装细节。
+     *
+     * <p>3 个回调是 loader 路径的必需操作,构造期分别以 {@link Objects#requireNonNull} 校验,
+     * 缺失即抛带参数名的 {@link NullPointerException};可选保护依赖保持既有可空语义。
      */
     LoaderOrchestrator(
             @Nullable BloomGate bloomGate,
             @Nullable SyncSupport syncSupport,
             @Nullable SyncLockTimeout syncLockTimeout,
-            @Nullable Function<Object, String> redisKeyFn,
-            @Nullable Function<Object, Cache.ValueWrapper> doubleCheckFn,
-            @Nullable BiConsumer<Object, Object> putAfterLoad) {
+            Function<Object, String> redisKeyFn,
+            Function<Object, Cache.ValueWrapper> doubleCheckFn,
+            BiConsumer<Object, Object> putAfterLoad) {
         this.bloomGate = bloomGate;
         this.syncSupport = syncSupport;
         this.syncLockTimeout = syncLockTimeout;
-        this.boundRedisKeyFn = redisKeyFn;
-        this.boundDoubleCheckFn = doubleCheckFn;
-        this.boundPutAfterLoad = putAfterLoad;
+        this.boundRedisKeyFn = Objects.requireNonNull(redisKeyFn, "redisKeyFn");
+        this.boundDoubleCheckFn = Objects.requireNonNull(doubleCheckFn, "doubleCheckFn");
+        this.boundPutAfterLoad = Objects.requireNonNull(putAfterLoad, "putAfterLoad");
     }
 
     /**
-     * 生产调用入口:使用构造期绑定的 callbacks 执行 loader 路径。
+     * 唯一实例入口:编排 loader 路径 — bloom 短路 → sync 路径(sync=true) → default
+     * 路径(同一协议,无锁);cache-specific 操作使用构造期绑定的回调。
      *
-     * @param cacheName 缓存名
-     * @param loader    Spring Cache loader
-     * @param key       用户缓存 key
-     * @param operation 方法级缓存 operation,可为 null
+     * @param cacheName 缓存名(供 BloomGate 区分 cache;非 key 派生)
+     * @param loader    Spring Cache {@link Callable} loader
+     * @param key       缓存 key(用户传入的原始 key;由绑定的 redisKeyFn 派生 Redis key)
+     * @param operation 方法级策略视图(可为 null,视作「无增强属性」→ 不走 bloom / sync)
      * @param <T>       加载结果类型
-     * @return 编排结果
-     */
-    <T> LoadOutcome<T> orchestrate(
-            String cacheName,
-            Callable<T> loader,
-            Object key,
-            @Nullable CachePolicyView.Source operation) {
-        if (boundRedisKeyFn == null
-                || boundDoubleCheckFn == null
-                || boundPutAfterLoad == null) {
-            throw new IllegalStateException("LoaderOrchestrator callbacks are not bound");
-        }
-        return orchestrate(
-                cacheName,
-                boundRedisKeyFn,
-                boundDoubleCheckFn,
-                boundPutAfterLoad,
-                loader,
-                key,
-                operation);
-    }
-
-    /**
-     * 编排 loader 路径:bloom 短路 → sync 路径(sync=true) → default 路径(同一协议,无锁)。
-     *
-     * @param cacheName        缓存名(供 BloomGate 区分 cache;非 key 派生)
-     * @param redisKeyFn       派生 Redis key(callback;caller 传 {@code key -> super.createCacheKey(key)})
-     * @param doubleCheckFn    缓存读原语(callback;caller 传 {@code key -> super.get(key)};
-     *                         含链 GET + null round-trip,无 metrics — metrics 在外层记)
-     * @param putAfterLoad     load 成功后写回缓存的 callback(caller 传 {@code (k, v) -> put(k, v)}
-     *                         闭包 → 走 override 保留 putTimer + putCounter 指标)
-     * @param loader           Spring Cache {@link Callable} loader
-     * @param key              缓存 key(用户传入的原始 key;由 redisKeyFn 派生 Redis key)
-     * @param operation        方法级策略视图(可为 null,视作「无增强属性」→ 不走 bloom / sync)
-     * @param <T>              加载结果类型
      * @return {@link LoadOutcome} 四态之一
      */
-    @SuppressWarnings("unchecked")
-    public <T> LoadOutcome<T> orchestrate(
+    <T> LoadOutcome<T> orchestrate(
             String cacheName,
-            Function<Object, String> redisKeyFn,
-            Function<Object, Cache.ValueWrapper> doubleCheckFn,
-            BiConsumer<Object, Object> putAfterLoad,
             Callable<T> loader,
             Object key,
             @Nullable CachePolicyView.Source operation) {
 
         // 1) Bloom 短路检查 — caller 据 BloomShortCircuited 自增 miss counter
-        if (isBloomShortCircuited(cacheName, redisKeyFn.apply(key), operation)) {
+        if (isBloomShortCircuited(cacheName, boundRedisKeyFn.apply(key), operation)) {
             return new BloomShortCircuited<>();
         }
 
         // 2) Sync 路径 — sync=true 且 SyncSupport 在场才走;否则降级 default 路径
         if (operation != null && operation.isSync() && syncSupport != null) {
-            return executeSyncLoad(cacheName, redisKeyFn, doubleCheckFn, putAfterLoad,
-                    loader, key, operation);
+            return executeSyncLoad(cacheName, loader, key, operation);
         }
 
         // 3) Default 路径 — 与 sync 路径同一 load 协议,只是不跑在分布式锁内
-        return executeLoad(cacheName, doubleCheckFn, putAfterLoad, loader, key);
+        return executeLoad(cacheName, loader, key);
     }
 
     /**
@@ -227,9 +187,6 @@ public <T> LoadOutcome<T> orchestrate(
      */
     private <T> LoadOutcome<T> executeSyncLoad(
             String cacheName,
-            Function<Object, String> redisKeyFn,
-            Function<Object, Cache.ValueWrapper> doubleCheckFn,
-            BiConsumer<Object, Object> putAfterLoad,
             Callable<T> loader,
             Object key,
             CachePolicyView.Source operation) {
@@ -238,10 +195,10 @@ private <T> LoadOutcome<T> executeSyncLoad(
                 : SyncLockTimeout.Resolved.fromSeconds(
                         SyncLockTimeout.DEFAULT_LOCK_TIMEOUT_SECONDS);
         try {
-            String lockKey = redisKeyFn.apply(key);
+            String lockKey = boundRedisKeyFn.apply(key);
             return syncSupport.executeSync(
                     lockKey,
-                    () -> executeLoad(cacheName, doubleCheckFn, putAfterLoad, loader, key),
+                    () -> executeLoad(cacheName, loader, key),
                     timeout);
         } catch (Throwable cause) {
             return new LoadFailed<>(cause);
@@ -258,17 +215,15 @@ private <T> LoadOutcome<T> executeSyncLoad(
     @SuppressWarnings("unchecked")
     private <T> LoadOutcome<T> executeLoad(
             String cacheName,
-            Function<Object, Cache.ValueWrapper> doubleCheckFn,
-            BiConsumer<Object, Object> putAfterLoad,
             Callable<T> loader,
             Object key) {
         return readThrough(
                 cacheName,
-                () -> doubleCheckFn.apply(key),
+                () -> boundDoubleCheckFn.apply(key),
                 cached -> cached != null,
                 cached -> (T) cached.get(),
                 loader::call,
-                value -> putAfterLoad.accept(key, value),
+                value -> boundPutAfterLoad.accept(key, value),
                 cause -> translateCacheLoaderFailure(key, loader, cause));
     }
 
diff --git a/src/test/java/io/github/davidhlp/spring/cache/redis/cache/LoaderOrchestratorTest.java b/src/test/java/io/github/davidhlp/spring/cache/redis/cache/LoaderOrchestratorTest.java
index 44fb50c4..e790495c 100644
--- a/src/test/java/io/github/davidhlp/spring/cache/redis/cache/LoaderOrchestratorTest.java
+++ b/src/test/java/io/github/davidhlp/spring/cache/redis/cache/LoaderOrchestratorTest.java
@@ -8,8 +8,13 @@
 import io.github.davidhlp.spring.cache.redis.cache.SyncLockTimeout.Resolved;
 import io.github.davidhlp.spring.cache.redis.chain.model.CachePolicyView;
 import io.github.davidhlp.spring.cache.redis.config.RedisProCacheProperties;
+import java.util.ArrayList;
+import java.util.List;
 import java.util.concurrent.Callable;
+import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiConsumer;
+import java.util.function.Function;
 import java.util.function.Supplier;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.DisplayName;
@@ -23,6 +28,7 @@
 import org.springframework.cache.Cache;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.anyString;
 import static org.mockito.ArgumentMatchers.eq;
@@ -32,11 +38,12 @@
  * {@link LoaderOrchestrator} 单测 — 3 个 seam 测试集。
  *
  * <p>{@code isBloomShortCircuited} / {@code readThrough} 等 package-private seam 下沉到
- * LoaderOrchestrator,通过 {@link LoaderOrchestrator#orchestrate} 公开方法间接覆盖 —
+ * LoaderOrchestrator,通过唯一实例入口 {@link LoaderOrchestrator#orchestrate} 四参方法间接覆盖 —
  * 每条 case 路径(bloom 短路 / sync 路由 / default 路由 / load 协议决策)
  * 用 {@link LoadOutcome} 各态断言。
  *
- * <p>测试 seam 形态:orchestrator 接受 3 个 callback(redisKey / doubleCheck / putAfterLoad),
+ * <p>测试装配与生产同形:每个用例经六参构造器绑定自身 callback
+ * (redisKey / doubleCheck / putAfterLoad)后走四参 {@code orchestrate},
  * 本测试直接控制 cache-specific 行为,无 RedisProCache fixture 依赖。
  */
 @ExtendWith(MockitoExtension.class)
@@ -50,17 +57,17 @@ class LoaderOrchestratorTest {
     @Mock
     private SyncSupport syncSupport;
 
-
+    private BloomGate bloomGate;
+    private SyncLockTimeout syncLockTimeout;
     private LoaderOrchestrator orchestrator;
     private String testRedisKey;
 
     @BeforeEach
     void setUp() {
-        orchestrator = new LoaderOrchestrator(
-                new BloomGate(bloomSupport),
-                syncSupport,
-                new SyncLockTimeout(new io.github.davidhlp.spring.cache.redis.config.RedisProCacheProperties()));
+        bloomGate = new BloomGate(bloomSupport);
+        syncLockTimeout = new SyncLockTimeout(new RedisProCacheProperties());
         testRedisKey = "testCache::key1";
+        orchestrator = bound(key -> null, (key, value) -> { });
     }
 
     private RedisCacheableOperation operation(boolean useBloom, boolean sync) {
@@ -72,6 +79,13 @@ private RedisCacheableOperation operation(boolean useBloom, boolean sync) {
                 .build();
     }
 
+    /** 构造绑定实例:redis key 派生自 {@link #testRedisKey} fixture。 */
+    private LoaderOrchestrator bound(Function<Object, Cache.ValueWrapper> doubleCheckFn,
+                                     BiConsumer<Object, Object> putAfterLoad) {
+        return new LoaderOrchestrator(bloomGate, syncSupport, syncLockTimeout,
+                key -> testRedisKey, doubleCheckFn, putAfterLoad);
+    }
+
     // ==================== Bloom 短路路径 ====================
 
     @Nested
@@ -85,13 +99,7 @@ void nullOperation_proceedsToDefaultPath() {
             Callable<String> loader = () -> "value";
 
             LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> null,                 // double-check miss
-                    (k, v) -> {},              // putAfterLoad
-                    loader,
-                    "key1",
-                    null);
+                    "testCache", loader, "key1", null);
 
             assertThat(((Loaded<String>) outcome).value()).isEqualTo("value");
         }
@@ -103,35 +111,27 @@ void bloomDisabled_proceedsToDefaultPath() {
             Callable<String> loader = () -> "value";
 
             LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> null,
-                    (k, v) -> {},
-                    loader,
-                    "key1",
-                    op);
+                    "testCache", loader, "key1", op);
             assertThat(outcome).isInstanceOf(Loaded.class);
         }
 
         @Test
-        @DisplayName("bloom rejects (mightContain=false) → return BloomShortCircuited, loader never invoked")
+        @DisplayName("bloom rejects (mightContain=false) → return BloomShortCircuited, loader/write-back never invoked")
         void bloomRejects_returnsBloomShortCircuited() {
             RedisCacheableOperation op = operation(true, false);
             when(bloomSupport.mightContain(eq("testCache"), anyString())).thenReturn(false);
 
+            AtomicInteger putCalls = new AtomicInteger();
             Callable<String> loader = () -> {
                 throw new AssertionError("loader should not be invoked on bloom short-circuit");
             };
 
-            LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> null,
-                    (k, v) -> {},
-                    loader,
-                    "key1",
-                    op);
+            LoadOutcome<String> outcome = bound(key -> null, (key, value) -> putCalls.incrementAndGet())
+                    .orchestrate("testCache", loader, "key1", op);
             assertThat(outcome).isInstanceOf(BloomShortCircuited.class);
+            assertThat(putCalls.get())
+                    .as("bloom 短路必须发生在 loader 与写回之前")
+                    .isZero();
         }
 
         @Test
@@ -143,13 +143,7 @@ void bloomAccepts_proceedsToDefaultPath() {
             Callable<String> loader = () -> "value";
 
             LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> null,
-                    (k, v) -> {},
-                    loader,
-                    "key1",
-                    op);
+                    "testCache", loader, "key1", op);
 
             assertThat(outcome).isInstanceOf(Loaded.class);
             assertThat(((Loaded<String>) outcome).value()).isEqualTo("value");
@@ -179,13 +173,7 @@ void syncEnabled_routesToSyncSupport() {
             Callable<String> loader = () -> "synced-value";
 
             LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> null,
-                    (k, v) -> {},
-                    loader,
-                    "key1",
-                    op);
+                    "testCache", loader, "key1", op);
 
             assertThat(((Loaded<String>) outcome).value()).isEqualTo("synced-value");
         }
@@ -198,16 +186,11 @@ void syncRead_resolvesTimeoutOnceAndReusesResolvedTimeout() {
             RecordingSyncLockTimeout timeout = new RecordingSyncLockTimeout(properties);
             RecordingSyncSupport support = new RecordingSyncSupport(properties);
             LoaderOrchestrator underTest = new LoaderOrchestrator(
-                    new BloomGate(bloomSupport), support, timeout);
+                    new BloomGate(bloomSupport), support, timeout,
+                    key -> testRedisKey, key -> null, (key, value) -> { });
 
             LoadOutcome<String> outcome = underTest.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    key -> null,
-                    (key, value) -> { },
-                    () -> "synced-value",
-                    "key1",
-                    operation(false, true));
+                    "testCache", () -> "synced-value", "key1", operation(false, true));
 
             assertThat(outcome).isInstanceOf(Loaded.class);
             assertThat(((Loaded<String>) outcome).value()).isEqualTo("synced-value");
@@ -240,16 +223,9 @@ void doubleCheckHit_skipsLoader() {
                 throw new AssertionError("loader should not be invoked on cache hit");
             };
 
-            LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> cached,                    // double-check 命中
-                    (k, v) -> {
-                        throw new AssertionError("put should not be invoked on cache hit");
-                    },
-                    loader,
-                    "key1",
-                    op);
+            LoadOutcome<String> outcome = bound(key -> cached, (key, value) -> {
+                throw new AssertionError("put should not be invoked on cache hit");
+            }).orchestrate("testCache", loader, "key1", op);
 
             assertThat(outcome).isInstanceOf(Loaded.class);
             assertThat(((Loaded<String>) outcome).value()).isEqualTo("cached-value");
@@ -266,23 +242,24 @@ void doubleCheckMiss_loaderReturnsValue_putsAfterLoad() {
                         return supplier.get();
                     });
 
-            java.util.concurrent.atomic.AtomicReference<Object> putKey = new java.util.concurrent.atomic.AtomicReference<>();
-            java.util.concurrent.atomic.AtomicReference<Object> putValue = new java.util.concurrent.atomic.AtomicReference<>();
+            AtomicReference<Object> readKey = new AtomicReference<>();
+            AtomicReference<Object> putKey = new AtomicReference<>();
+            AtomicReference<Object> putValue = new AtomicReference<>();
 
-            LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> null,                       // double-check miss
-                    (k, v) -> {                      // putAfterLoad 记录
-                        putKey.set(k);
-                        putValue.set(v);
+            LoadOutcome<String> outcome = bound(
+                    key -> {
+                        readKey.set(key);
+                        return null;                     // double-check miss
                     },
-                    () -> "loaded-value",
-                    "key1",
-                    op);
+                    (key, value) -> {                    // putAfterLoad 记录
+                        putKey.set(key);
+                        putValue.set(value);
+                    })
+                    .orchestrate("testCache", () -> "loaded-value", "key1", op);
 
             assertThat(outcome).isInstanceOf(Loaded.class);
             assertThat(((Loaded<String>) outcome).value()).isEqualTo("loaded-value");
+            assertThat(readKey.get()).isEqualTo("key1");
             assertThat(putKey.get()).isEqualTo("key1");
             assertThat(putValue.get()).isEqualTo("loaded-value");
         }
@@ -298,16 +275,10 @@ void doubleCheckMiss_loaderReturnsNull_putsNull() {
                         return supplier.get();
                     });
 
-            java.util.concurrent.atomic.AtomicInteger putCalls = new java.util.concurrent.atomic.AtomicInteger();
+            AtomicInteger putCalls = new AtomicInteger();
 
-            LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> null,
-                    (k, v) -> putCalls.incrementAndGet(),
-                    () -> null,
-                    "key1",
-                    op);
+            LoadOutcome<String> outcome = bound(key -> null, (key, value) -> putCalls.incrementAndGet())
+                    .orchestrate("testCache", () -> null, "key1", op);
 
             assertThat(outcome).isInstanceOf(Loaded.class);
             assertThat(((Loaded<String>) outcome).value()).isNull();
@@ -330,13 +301,7 @@ void loaderThrows_wrapsInValueRetrievalException() {
             };
 
             LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> null,
-                    (k, v) -> {},
-                    loader,
-                    "key1",
-                    op);
+                    "testCache", loader, "key1", op);
 
             assertThat(outcome).isInstanceOf(LoadFailed.class);
             Throwable cause = ((LoadFailed<String>) outcome).cause();
@@ -357,14 +322,9 @@ void writeBackFails_returnsLoadedWithWriteBackFailure() {
 
             RuntimeException putBoom = new RuntimeException("redis put failed");
 
-            LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> null,
-                    (k, v) -> { throw putBoom; },      // putAfterLoad 写回失败
-                    () -> "loaded-value",
-                    "key1",
-                    op);
+            LoadOutcome<String> outcome = bound(key -> null, (key, value) -> {
+                throw putBoom;                       // putAfterLoad 写回失败
+            }).orchestrate("testCache", () -> "loaded-value", "key1", op);
 
             assertThat(outcome).isInstanceOf(LoadedWithWriteBackFailure.class);
             LoadedWithWriteBackFailure<String> wbf = (LoadedWithWriteBackFailure<String>) outcome;
@@ -387,14 +347,9 @@ void writeBackFails_nullLoadedValue_preserved() {
 
             RuntimeException putBoom = new RuntimeException("redis put failed");
 
-            LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> null,
-                    (k, v) -> { throw putBoom; },
-                    () -> null,
-                    "key1",
-                    op);
+            LoadOutcome<String> outcome = bound(key -> null, (key, value) -> {
+                throw putBoom;
+            }).orchestrate("testCache", () -> null, "key1", op);
 
             assertThat(outcome).isInstanceOf(LoadedWithWriteBackFailure.class);
             LoadedWithWriteBackFailure<String> wbf = (LoadedWithWriteBackFailure<String>) outcome;
@@ -413,7 +368,7 @@ class DefaultLoadPathTests {
         @Test
         @DisplayName("bound callback constructor exposes a small production call surface")
         void boundCallbacks_productionEntryUsesOnlyLoaderAndKey() {
-            LoaderOrchestrator bound = new LoaderOrchestrator(
+            LoaderOrchestrator boundOrchestrator = new LoaderOrchestrator(
                     null,
                     null,
                     null,
@@ -421,31 +376,43 @@ void boundCallbacks_productionEntryUsesOnlyLoaderAndKey() {
                     key -> null,
                     (key, value) -> { });
 
-            LoadOutcome<String> outcome = bound.orchestrate(
+            LoadOutcome<String> outcome = boundOrchestrator.orchestrate(
                     "testCache", () -> "loaded-value", "key1", operation(false, false));
 
             assertThat(outcome).isInstanceOf(Loaded.class);
             assertThat(((Loaded<String>) outcome).value()).isEqualTo("loaded-value");
         }
 
+        @Test
+        @DisplayName("ValueWrapper 非 null 且值为 null → 命中:不调用 loader、不写回")
+        void cachedNullValueWrapperHit_skipsLoaderAndWriteBack() {
+            RedisCacheableOperation op = operation(false, false);
+            Cache.ValueWrapper nullWrapper = () -> null;
+            Callable<String> loader = () -> {
+                throw new AssertionError("loader must not run on null-value cache hit");
+            };
+
+            LoadOutcome<String> outcome = bound(key -> nullWrapper, (key, value) -> {
+                throw new AssertionError("put must not run on null-value cache hit");
+            }).orchestrate("testCache", loader, "key1", op);
+
+            assertThat(outcome).isInstanceOf(Loaded.class);
+            assertThat(((Loaded<String>) outcome).value())
+                    .as("wrapper 命中判定不能用业务值是否为 null 代替")
+                    .isNull();
+        }
+
         @Test
         @DisplayName("double-check hits → default path returns cached value, loader never invoked")
         void doubleCheckHit_defaultPathSkipsLoader() {
             RedisCacheableOperation op = operation(false, false);
             Cache.ValueWrapper cached = () -> "cached-value";
 
-            LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> cached,
-                    (k, v) -> {
-                        throw new AssertionError("put must not run on cache hit");
-                    },
-                    () -> {
-                        throw new AssertionError("loader must not run on cache hit");
-                    },
-                    "key1",
-                    op);
+            LoadOutcome<String> outcome = bound(key -> cached, (key, value) -> {
+                throw new AssertionError("put must not run on cache hit");
+            }).orchestrate("testCache", () -> {
+                throw new AssertionError("loader must not run on cache hit");
+            }, "key1", op);
 
             assertThat(outcome).isInstanceOf(Loaded.class);
             assertThat(((Loaded<String>) outcome).value()).isEqualTo("cached-value");
@@ -455,19 +422,17 @@ void doubleCheckHit_defaultPathSkipsLoader() {
         @DisplayName("double-check miss → loader runs, value written back through putAfterLoad")
         void doubleCheckMiss_defaultPathLoadsAndWritesBack() {
             RedisCacheableOperation op = operation(false, false);
+            AtomicReference<Object> writtenKey = new AtomicReference<>();
             AtomicReference<Object> written = new AtomicReference<>();
 
-            LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> null,
-                    (k, v) -> written.set(v),
-                    () -> "loaded-value",
-                    "key1",
-                    op);
+            LoadOutcome<String> outcome = bound(key -> null, (key, value) -> {
+                writtenKey.set(key);
+                written.set(value);
+            }).orchestrate("testCache", () -> "loaded-value", "key1", op);
 
             assertThat(outcome).isInstanceOf(Loaded.class);
             assertThat(((Loaded<String>) outcome).value()).isEqualTo("loaded-value");
+            assertThat(writtenKey.get()).isEqualTo("key1");
             assertThat(written.get())
                     .as("默认载荷路径的写回必须走 putAfterLoad(带 put metrics 的 override)")
                     .isEqualTo("loaded-value");
@@ -482,13 +447,7 @@ void loaderThrows_defaultPathReturnsLoadFailed() {
             };
 
             LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> null,
-                    (k, v) -> {},
-                    loader,
-                    "key1",
-                    op);
+                    "testCache", loader, "key1", op);
 
             assertThat(outcome).isInstanceOf(LoadFailed.class);
             Throwable cause = ((LoadFailed<String>) outcome).cause();
@@ -497,22 +456,15 @@ void loaderThrows_defaultPathReturnsLoadFailed() {
         }
 
         @Test
-        @DisplayName("写回抛 IllegalArgumentException(配置错误) → 原样上抛,不降级为写回失败")
+        @DisplayName("写回抛 IllegalArgumentException(配置错误) → LoadFailed 原样携带,不降级为写回容错")
         void writeBackConfigurationError_propagates() {
             RedisCacheableOperation op = operation(false, false);
             IllegalArgumentException misconfiguration = new IllegalArgumentException(
                     "Cache 'testCache' does not allow 'null' values");
 
-            LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> null,
-                    (k, v) -> {
-                        throw misconfiguration;
-                    },
-                    () -> null,
-                    "key1",
-                    op);
+            LoadOutcome<String> outcome = bound(key -> null, (key, value) -> {
+                throw misconfiguration;
+            }).orchestrate("testCache", () -> null, "key1", op);
 
             assertThat(outcome)
                     .as("null 缓存未启用是配置错误,必须走 LoadFailed(调用方上抛),不是写回容错")
@@ -526,16 +478,9 @@ void writeBackFails_defaultPathReturnsLoadedWithWriteBackFailure() {
             RedisCacheableOperation op = operation(false, false);
             RuntimeException putBoom = new RuntimeException("redis put failed");
 
-            LoadOutcome<String> outcome = orchestrator.orchestrate(
-                    "testCache",
-                    key -> testRedisKey,
-                    k -> null,
-                    (k, v) -> {
-                        throw putBoom;
-                    },
-                    () -> "loaded-value",
-                    "key1",
-                    op);
+            LoadOutcome<String> outcome = bound(key -> null, (key, value) -> {
+                throw putBoom;
+            }).orchestrate("testCache", () -> "loaded-value", "key1", op);
 
             assertThat(outcome).isInstanceOf(LoadedWithWriteBackFailure.class);
             LoadedWithWriteBackFailure<String> wbf = (LoadedWithWriteBackFailure<String>) outcome;
@@ -546,6 +491,81 @@ void writeBackFails_defaultPathReturnsLoadedWithWriteBackFailure() {
         }
 
     }
+
+    // ==================== 构造绑定(六参构造器)校验与跨调用状态 ====================
+
+    @Nested
+    @DisplayName("Constructor Binding Tests — 必需回调校验 / 无请求级缓存状态")
+    class ConstructorBindingTests {
+
+        private final Function<Object, String> keyFn = key -> testRedisKey;
+        private final Function<Object, Cache.ValueWrapper> checkFn = key -> null;
+        private final BiConsumer<Object, Object> putFn = (key, value) -> { };
+
+        @Test
+        @DisplayName("redisKeyFn 为 null → 构造期抛 NPE,消息指明参数名")
+        void nullRedisKeyFn_rejectedAtConstruction() {
+            assertThatThrownBy(() -> new LoaderOrchestrator(
+                    null, null, null, null, checkFn, putFn))
+                    .isInstanceOf(NullPointerException.class)
+                    .hasMessage("redisKeyFn");
+        }
+
+        @Test
+        @DisplayName("doubleCheckFn 为 null → 构造期抛 NPE,消息指明参数名")
+        void nullDoubleCheckFn_rejectedAtConstruction() {
+            assertThatThrownBy(() -> new LoaderOrchestrator(
+                    null, null, null, keyFn, null, putFn))
+                    .isInstanceOf(NullPointerException.class)
+                    .hasMessage("doubleCheckFn");
+        }
+
+        @Test
+        @DisplayName("putAfterLoad 为 null → 构造期抛 NPE,消息指明参数名")
+        void nullPutAfterLoad_rejectedAtConstruction() {
+            assertThatThrownBy(() -> new LoaderOrchestrator(
+                    null, null, null, keyFn, checkFn, null))
+                    .isInstanceOf(NullPointerException.class)
+                    .hasMessage("putAfterLoad");
+        }
+
+        @Test
+        @DisplayName("可选保护依赖为 null → 合法装配,构造不抛")
+        void nullProtectionDeps_stillAccepted() {
+            assertThat(new LoaderOrchestrator(null, null, null, keyFn, checkFn, putFn))
+                    .isNotNull();
+        }
+
+        @Test
+        @DisplayName("同一实例连续 orchestrate 两个 key → 读与写回各自收到正确 key,不缓存请求状态")
+        void sameInstanceServesConsecutiveCallsWithDistinctKeys() {
+            List<Object> readKeys = new ArrayList<>();
+            List<Object> putKeys = new ArrayList<>();
+            List<Object> putValues = new ArrayList<>();
+            AtomicInteger loads = new AtomicInteger();
+            LoaderOrchestrator boundOrchestrator = bound(
+                    key -> {
+                        readKeys.add(key);
+                        return null;
+                    },
+                    (key, value) -> {
+                        putKeys.add(key);
+                        putValues.add(value);
+                    });
+            Callable<String> loader = () -> "v" + loads.incrementAndGet();
+            RedisCacheableOperation op = operation(false, false);
+
+            LoadOutcome<String> first = boundOrchestrator.orchestrate("testCache", loader, "keyA", op);
+            LoadOutcome<String> second = boundOrchestrator.orchestrate("testCache", loader, "keyB", op);
+
+            assertThat(((Loaded<String>) first).value()).isEqualTo("v1");
+            assertThat(((Loaded<String>) second).value()).isEqualTo("v2");
+            assertThat(readKeys).containsExactly("keyA", "keyB");
+            assertThat(putKeys).containsExactly("keyA", "keyB");
+            assertThat(putValues).containsExactly("v1", "v2");
+        }
+    }
+
     private static final class RecordingSyncLockTimeout extends SyncLockTimeout {
         private final Resolved resolvedTimeout = Resolved.fromSeconds(37);
         private int resolutionCount;

From c32097dd3dfa6052e6999707198829d5fc4b040c Mon Sep 17 00:00:00 2001
From: DavidHLP <lysf15520112973@163.com>
Date: Sun, 20 Sep 2026 00:21:51 +0800
Subject: [PATCH 2/3] refactor(cache): drop test-only strategy entry and dead
 key parameter

The 5-arg handleException(strategy) overload existed only for tests and
exercised operation/strategy combinations production never selects; every
failure now routes through the operation-driven handleError seam. The
key/pattern parameter was threaded through both handleError forms and the
private helper but never used by the failure implementation, so it is gone.

Migrated CacheErrorHandlerTest to real operations, proving the per-operation
strategy through metric tags with independently written expectations, added a
typed PARTIAL_CLEAN + finalizeFailure behavior test for the partial-clean
kind, and moved the key-privacy sentinel into the exception message.
---
 .../cache/redis/cache/ActualCacheHandler.java |  10 +-
 .../cache/redis/cache/CacheErrorHandler.java  |  22 +-
 .../ActualCacheHandlerIntegrationTest.java    |   8 +-
 .../redis/cache/CacheErrorHandlerTest.java    | 233 +++++++++---------
 .../cache/RedisProCacheLoadPathTest.java      |   1 -
 5 files changed, 136 insertions(+), 138 deletions(-)

diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/cache/ActualCacheHandler.java b/src/main/java/io/github/davidhlp/spring/cache/redis/cache/ActualCacheHandler.java
index b5231c2e..2a8e0b2c 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/cache/ActualCacheHandler.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/cache/ActualCacheHandler.java
@@ -130,7 +130,7 @@ private CacheResult handleGet(CacheContext context) {
             return CacheResult.miss();
 
         } catch (Exception e) {
-            return errorHandler.handleError(context.getOperation(), context.getCacheName(), context.getRedisKey(), e);
+            return errorHandler.handleError(context.getOperation(), context.getCacheName(), e);
         }
     }
 
@@ -190,7 +190,7 @@ private CacheResult handlePut(CacheContext context) {
             return CacheResult.success();
 
         } catch (Exception e) {
-            return errorHandler.handleError(context.getOperation(), context.getCacheName(), context.getRedisKey(), e);
+            return errorHandler.handleError(context.getOperation(), context.getCacheName(), e);
         }
     }
 
@@ -230,7 +230,7 @@ private CacheResult handlePutIfAbsent(CacheContext context) {
             return CacheResult.existing(null);
 
         } catch (Exception e) {
-            return errorHandler.handleError(context.getOperation(), context.getCacheName(), context.getRedisKey(), e);
+            return errorHandler.handleError(context.getOperation(), context.getCacheName(), e);
         }
     }
 
@@ -254,7 +254,7 @@ private CacheResult handleRemove(CacheContext context) {
             return CacheResult.success();
 
         } catch (Exception e) {
-            return errorHandler.handleError(context.getOperation(), context.getCacheName(), context.getRedisKey(), e);
+            return errorHandler.handleError(context.getOperation(), context.getCacheName(), e);
         }
     }
 
@@ -317,7 +317,7 @@ private CacheResult handleClean(CacheContext context) {
                     ? CacheResult.FailureKind.PARTIAL_CLEAN
                     : CacheResult.FailureKind.REDIS;
             return errorHandler.handleError(
-                    context.getOperation(), context.getCacheName(), keyPattern, failureKind, e);
+                    context.getOperation(), context.getCacheName(), failureKind, e);
         }
     }
 
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/cache/CacheErrorHandler.java b/src/main/java/io/github/davidhlp/spring/cache/redis/cache/CacheErrorHandler.java
index e0c1113a..d820b60f 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/cache/CacheErrorHandler.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/cache/CacheErrorHandler.java
@@ -24,7 +24,7 @@
  *   <li>按 operation 调度策略 + 应用策略（日志级别 + CacheResult 形态）</li>
  * </ol>
  *
- * <p>单一入口 {@link #handleError(CacheOperation, String, String, Exception)} +
+ * <p>单一入口 {@link #handleError(CacheOperation, String, Exception)} +
  * per-operation 策略集中到 {@link #STRATEGIES} 不可变 Map。调用方只需传
  * {@link CacheContext#getOperation() context.getOperation()}，无需记忆具体方法名；
  * 新增 operation 只需在 {@link CacheOperation} 追加枚举值 + 在 {@link #STRATEGIES} 追加一行。
@@ -123,8 +123,8 @@ public CacheErrorHandler(
     /**
      * 按 operation 调度错误策略并保留诊断信息(typed kind)。
      */
-    public CacheResult handleError(CacheOperation operation, String cacheName, String key, Exception e) {
-        return handleException(operation, cacheName, key, e, strategyFor(operation), classify(e));
+    public CacheResult handleError(CacheOperation operation, String cacheName, Exception e) {
+        return handleException(operation, cacheName, e, strategyFor(operation), classify(e));
     }
 
     /**
@@ -133,28 +133,18 @@ public CacheResult handleError(CacheOperation operation, String cacheName, Strin
     CacheResult handleError(
             CacheOperation operation,
             String cacheName,
-            String key,
             FailureKind failureKind,
             Exception e) {
-        return handleException(operation, cacheName, key, e, strategyFor(operation), failureKind);
+        return handleException(operation, cacheName, e, strategyFor(operation), failureKind);
     }
 
     /**
-     * 直接应用指定策略,供测试和显式内部调用使用。
+     * 应用策略并完成分类、日志与单次计数 —— 链内唯一失败出口。策略与 typed kind 由上面的
+     * {@code handleError} 重载按 operation 选定,不再对外暴露显式策略入口。
      */
-    public CacheResult handleException(
-            CacheOperation operation,
-            String cacheName,
-            String key,
-            Exception e,
-            ErrorStrategy strategy) {
-        return handleException(operation, cacheName, key, e, strategy, classify(e));
-    }
-
     private CacheResult handleException(
             CacheOperation operation,
             String cacheName,
-            String key,
             Exception e,
             ErrorStrategy strategy,
             FailureKind failureKind) {
diff --git a/src/test/java/io/github/davidhlp/spring/cache/redis/cache/ActualCacheHandlerIntegrationTest.java b/src/test/java/io/github/davidhlp/spring/cache/redis/cache/ActualCacheHandlerIntegrationTest.java
index 0deaf17c..74d30e42 100644
--- a/src/test/java/io/github/davidhlp/spring/cache/redis/cache/ActualCacheHandlerIntegrationTest.java
+++ b/src/test/java/io/github/davidhlp/spring/cache/redis/cache/ActualCacheHandlerIntegrationTest.java
@@ -178,7 +178,7 @@ void handleGet_exception_delegatesToErrorHandler() {
             CacheResult errorResult = CacheResult.miss();
             ActualCacheHandler faultHandler = faultHandler(exception, null, null);
             when(errorHandler.handleError(eq(CacheOperation.GET), eq("test-cache"),
-                    eq("test:key"), eq(exception))).thenReturn(errorResult);
+                    eq(exception))).thenReturn(errorResult);
 
             HandlerResult result = faultHandler.handle(createContext(CacheOperation.GET));
 
@@ -247,7 +247,7 @@ void handlePut_exception_delegatesToErrorHandler() {
             CacheResult errorResult = CacheResult.failure(CacheOperation.PUT, CacheResult.FailureKind.REDIS, new IllegalStateException("down"));
             ActualCacheHandler faultHandler = faultHandler(null, exception, null);
             when(errorHandler.handleError(eq(CacheOperation.PUT), eq("test-cache"),
-                    eq("test:key"), eq(exception))).thenReturn(errorResult);
+                    eq(exception))).thenReturn(errorResult);
 
             CacheContext context = createContext(CacheOperation.PUT);
             context.setTtlDecision(TtlDecision.skipped());
@@ -306,7 +306,7 @@ void handlePutIfAbsent_exception_delegatesToErrorHandler() {
             CacheResult errorResult = CacheResult.failure(CacheOperation.PUT_IF_ABSENT, CacheResult.FailureKind.REDIS, new IllegalStateException("down"));
             ActualCacheHandler faultHandler = faultHandler(exception, null, null);
             when(errorHandler.handleError(eq(CacheOperation.PUT_IF_ABSENT), eq("test-cache"),
-                    eq("test:key"), eq(exception))).thenReturn(errorResult);
+                    eq(exception))).thenReturn(errorResult);
 
             HandlerResult result = faultHandler.handle(createContext(CacheOperation.PUT_IF_ABSENT));
 
@@ -339,7 +339,7 @@ void handleRemove_exception_delegatesToErrorHandler() {
             CacheResult errorResult = CacheResult.failure(CacheOperation.REMOVE, CacheResult.FailureKind.REDIS, new IllegalStateException("down"));
             ActualCacheHandler faultHandler = faultHandler(null, null, exception);
             when(errorHandler.handleError(eq(CacheOperation.REMOVE), eq("test-cache"),
-                    eq("test:key"), eq(exception))).thenReturn(errorResult);
+                    eq(exception))).thenReturn(errorResult);
 
             HandlerResult result = faultHandler.handle(createContext(CacheOperation.REMOVE));
 
diff --git a/src/test/java/io/github/davidhlp/spring/cache/redis/cache/CacheErrorHandlerTest.java b/src/test/java/io/github/davidhlp/spring/cache/redis/cache/CacheErrorHandlerTest.java
index 10cee3bb..bd575820 100644
--- a/src/test/java/io/github/davidhlp/spring/cache/redis/cache/CacheErrorHandlerTest.java
+++ b/src/test/java/io/github/davidhlp/spring/cache/redis/cache/CacheErrorHandlerTest.java
@@ -3,7 +3,6 @@
 
 
 
-
 import io.github.davidhlp.spring.cache.redis.chain.CacheOperation;
 import io.github.davidhlp.spring.cache.redis.chain.CacheResult;
 import java.util.stream.Stream;
@@ -19,12 +18,13 @@
 /**
  * CacheErrorHandler 单元测试。
  *
- * <p>单 {@link CacheErrorHandler#handleError(CacheOperation, String, String, Exception)}
+ * <p>单 {@link CacheErrorHandler#handleError(CacheOperation, String, Exception)}
  * 入口,per-operation 策略集中到 {@code STRATEGIES} 不可变 Map。本测试：
  *
  * <ul>
- *   <li>{@code handleException} 直策略调用测试（{@link StrategyDispatchTests}）</li>
- *   <li>1 个 parametric 测试（{@link PerOperationStrategyTests}）— 单一事实源 + pin 全部 op→策略映射</li>
+ *   <li>真实 operation 的失败结果与分类断言（{@link StrategyDispatchTests}）</li>
+ *   <li>1 个 parametric 测试（{@link PerOperationStrategyTests}）— 经 handleError + 指标 tags
+ *       pin 全部 op→策略映射，期望策略以字面量写在参数表中</li>
  *   <li>{@link StrategySelectionTests} 作为策略语义总览</li>
  * </ul>
  *
@@ -45,17 +45,19 @@ private Exception createException(String message) {
         return new RuntimeException(message);
     }
 
+    /**
+     * 失败结果与分类断言 —— 全部经真实 operation 的 handleError 出口，不再使用显式策略入口。
+     */
     @Nested
-    @DisplayName("handleException with explicit strategy")
+    @DisplayName("handleError failure semantics via real operations")
     class StrategyDispatchTests {
 
         @Test
-        @DisplayName("FAIL_FAST returns failure result with original cause")
-        void handleException_failFast_returnsFailure() {
+        @DisplayName("FAIL_FAST operation returns failure result with original cause")
+        void failFast_returnsFailurePreservingCause() {
             Exception e = createException("Connection refused");
 
-            CacheResult result = handler.handleException(CacheOperation.GET, "test-cache", "key", e,
-                    CacheErrorHandler.ErrorStrategy.FAIL_FAST);
+            CacheResult result = handler.handleError(CacheOperation.PUT, "test-cache", e);
 
             assertThat(result.isSuccess()).isFalse();
             assertThat(result.cause()).isSameAs(e);
@@ -63,35 +65,32 @@ void handleException_failFast_returnsFailure() {
         }
 
         @Test
-        @DisplayName("FAIL_FAST preserves operation metadata")
-        void handleException_failFast_preservesOperation() {
+        @DisplayName("FAIL_FAST operation preserves operation metadata")
+        void failFast_preservesOperation() {
             Exception e = createException("Error");
 
-            CacheResult result = handler.handleException(CacheOperation.PUT, "cache", "key", e,
-                    CacheErrorHandler.ErrorStrategy.FAIL_FAST);
+            CacheResult result = handler.handleError(CacheOperation.PUT, "cache", e);
 
             assertThat(result.operation()).isEqualTo(CacheOperation.PUT);
             assertThat(result.outcome()).isEqualTo(CacheResult.Outcome.FAILURE);
         }
 
         @Test
-        @DisplayName("FAIL_FAST sets success false on failure")
-        void handleException_failFast_setsSuccessFalse() {
+        @DisplayName("FAIL_FAST operation sets success false")
+        void failFast_setsSuccessFalse() {
             Exception e = createException("Error");
 
-            CacheResult result = handler.handleException(CacheOperation.PUT, "cache", "key", e,
-                    CacheErrorHandler.ErrorStrategy.FAIL_FAST);
+            CacheResult result = handler.handleError(CacheOperation.PUT, "cache", e);
 
             assertThat(result.isSuccess()).isFalse();
         }
 
         @Test
-        @DisplayName("GRACEFUL_DEGRADATION returns a miss with failure status")
-        void handleException_gracefulDegradation_returnsFailureMiss() {
+        @DisplayName("GET degrades to a miss with failure status")
+        void gracefulDegradation_returnsFailureMiss() {
             Exception e = createException("Timeout");
 
-            CacheResult result = handler.handleException(CacheOperation.GET, "test-cache", "key", e,
-                    CacheErrorHandler.ErrorStrategy.GRACEFUL_DEGRADATION);
+            CacheResult result = handler.handleError(CacheOperation.GET, "test-cache", e);
 
             assertThat(result.isSuccess()).isFalse();
             assertThat(result.resultBytes()).isNull();
@@ -100,59 +99,62 @@ void handleException_gracefulDegradation_returnsFailureMiss() {
         }
 
         @Test
-        @DisplayName("SILENT returns an observable best-effort failure")
-        void handleException_silent_returnsFailure() {
+        @DisplayName("REMOVE returns an observable best-effort failure")
+        void silent_returnsFailure() {
             Exception e = createException("Silent error");
 
-            CacheResult result = handler.handleException(CacheOperation.REMOVE, "test-cache", "key", e,
-                    CacheErrorHandler.ErrorStrategy.SILENT);
+            CacheResult result = handler.handleError(CacheOperation.REMOVE, "test-cache", e);
 
             assertThat(result.isSuccess()).isFalse();
             assertThat(result.cause()).isSameAs(e);
         }
 
         @Test
-        @DisplayName("SILENT does not throw exception")
-        void handleException_silent_doesNotThrow() {
+        @DisplayName("REMOVE best-effort does not throw")
+        void silent_doesNotThrow() {
             Exception e = createException("Silent");
 
-            CacheResult result = handler.handleException(CacheOperation.CLEAN, "cache", "pattern", e,
-                    CacheErrorHandler.ErrorStrategy.SILENT);
+            org.assertj.core.api.Assertions.assertThatCode(
+                            () -> handler.handleError(CacheOperation.REMOVE, "cache", e))
+                    .doesNotThrowAnyException();
 
+            CacheResult result = handler.handleError(CacheOperation.REMOVE, "cache", e);
             assertThat(result).isNotNull();
             assertThat(result.isSuccess()).isFalse();
         }
 
         @Test
-        @DisplayName("classifies timeout, cancellation, and serialization failures")
-        void handleException_classifiesFailureKinds() {
-            CacheResult timeout = handler.handleException(CacheOperation.GET, "cache", "key", new java.util.concurrent.TimeoutException("timeout"),
-                    CacheErrorHandler.ErrorStrategy.GRACEFUL_DEGRADATION);
-            CacheResult cancellation = handler.handleException(CacheOperation.GET, "cache", "key", new java.util.concurrent.CancellationException("cancelled"),
-                    CacheErrorHandler.ErrorStrategy.GRACEFUL_DEGRADATION);
-            CacheResult serialization = handler.handleException(CacheOperation.GET, "cache", "key",
-                    new io.github.davidhlp.spring.cache.redis.serialization.SerializationException("bad"),
-                    CacheErrorHandler.ErrorStrategy.GRACEFUL_DEGRADATION);
+        @DisplayName("classifies timeout, cancellation, serialization and generic failures")
+        void classifiesFailureKinds() {
+            CacheResult timeout = handler.handleError(CacheOperation.GET, "cache",
+                    new java.util.concurrent.TimeoutException("timeout"));
+            CacheResult cancellation = handler.handleError(CacheOperation.GET, "cache",
+                    new java.util.concurrent.CancellationException("cancelled"));
+            CacheResult serialization = handler.handleError(CacheOperation.GET, "cache",
+                    new io.github.davidhlp.spring.cache.redis.serialization.SerializationException("bad"));
+            CacheResult generic = handler.handleError(CacheOperation.GET, "cache",
+                    createException("boom"));
 
             assertThat(timeout.failureKind()).isEqualTo(CacheResult.FailureKind.TIMEOUT);
             assertThat(cancellation.failureKind()).isEqualTo(CacheResult.FailureKind.CANCELLATION);
             assertThat(serialization.failureKind()).isEqualTo(CacheResult.FailureKind.SERIALIZATION);
+            assertThat(generic.failureKind()).isEqualTo(CacheResult.FailureKind.REDIS);
         }
 
     }
 
     /**
-     * 单一事实源 pin — 每个 operation 的策略 + 期望 success 状态。
+     * 单一事实源 pin — 每个 operation 的期望策略（以字面量写死，不调用生产 strategyFor）。
      * 新增 operation 时，{@link CacheOperation} 加枚举值 + {@code STRATEGIES} 加一行 + 本测试
      * 加一行参数,3 处同步驱动。
      */
     static Stream<Arguments> perOperationStrategies() {
         return Stream.of(
-                Arguments.of(CacheOperation.GET, false),
-                Arguments.of(CacheOperation.PUT, false),
-                Arguments.of(CacheOperation.PUT_IF_ABSENT, false),
-                Arguments.of(CacheOperation.REMOVE, false),
-                Arguments.of(CacheOperation.CLEAN, false));
+                Arguments.of(CacheOperation.GET, CacheErrorHandler.ErrorStrategy.GRACEFUL_DEGRADATION),
+                Arguments.of(CacheOperation.PUT, CacheErrorHandler.ErrorStrategy.FAIL_FAST),
+                Arguments.of(CacheOperation.PUT_IF_ABSENT, CacheErrorHandler.ErrorStrategy.FAIL_FAST),
+                Arguments.of(CacheOperation.REMOVE, CacheErrorHandler.ErrorStrategy.SILENT),
+                Arguments.of(CacheOperation.CLEAN, CacheErrorHandler.ErrorStrategy.FAIL_FAST));
     }
 
 
@@ -175,79 +177,61 @@ void strategyFor_exposesTheTableWithoutSideEffects() {
                     .isEqualTo(CacheErrorHandler.ErrorStrategy.FAIL_FAST);
         }
 
-        @ParameterizedTest(name = "{0} → success={1}")
+        @ParameterizedTest(name = "{0} → {1}")
         @MethodSource("io.github.davidhlp.spring.cache.redis.cache.CacheErrorHandlerTest#perOperationStrategies")
-        @DisplayName("dispatches STRATEGIES map to handleException correctly")
-        void handleError_dispatchesPerOperationStrategy(CacheOperation operation, boolean expectedSuccess) {
+        @DisplayName("handleError selects the operation's strategy; proven via metric tags")
+        void handleError_dispatchesPerOperationStrategy(
+                CacheOperation operation, CacheErrorHandler.ErrorStrategy expectedStrategy) {
+            io.micrometer.core.instrument.simple.SimpleMeterRegistry registry =
+                    new io.micrometer.core.instrument.simple.SimpleMeterRegistry();
+            CacheErrorHandler reportingHandler = new CacheErrorHandler(new CacheFailureReporter(registry));
             Exception e = createException("Redis error for " + operation);
 
-            CacheResult result = handler.handleError(operation, "test-cache", "key", e);
-
-            assertThat(result.isSuccess()).isEqualTo(expectedSuccess);
-        }
-        @Test
-        @DisplayName("GET uses GRACEFUL_DEGRADATION with failure status")
-        void handleError_get_returnsObservableMiss() {
-            Exception e = createException("Redis error");
-
-            CacheResult result = handler.handleError(CacheOperation.GET, "test-cache", "key", e);
-
-            assertThat(result.isSuccess()).isFalse();
-            assertThat(result.resultBytes()).isNull();
-            assertThat(result.failureKind()).isEqualTo(CacheResult.FailureKind.REDIS);
-        }
-
-        @Test
-        @DisplayName("PUT uses FAIL_FAST (returns failure, success=false)")
-        void handleError_put_returnsFailure() {
-            Exception e = createException("Redis error");
-
-            CacheResult result = handler.handleError(CacheOperation.PUT, "test-cache", "key", e);
-
-            assertThat(result.isSuccess()).isFalse();
-        }
-
-        @Test
-        @DisplayName("PUT_IF_ABSENT uses FAIL_FAST")
-        void handleError_putIfAbsent_returnsFailure() {
-            Exception e = createException("Redis error");
-
-            CacheResult result = handler.handleError(CacheOperation.PUT_IF_ABSENT, "test-cache", "key", e);
-
-            assertThat(result.isSuccess()).isFalse();
-        }
-
-        @Test
-        @DisplayName("REMOVE uses observable best-effort failure")
-        void handleError_remove_returnsFailureWithoutThrowing() {
-            Exception e = createException("Redis error");
-
-            CacheResult result = handler.handleError(CacheOperation.REMOVE, "test-cache", "key", e);
+            CacheResult result = reportingHandler.handleError(operation, "test-cache", e);
 
             assertThat(result.isSuccess()).isFalse();
             assertThat(result.failureKind()).isEqualTo(CacheResult.FailureKind.REDIS);
-            assertThat(result.cause()).isSameAs(e);
+            var counters = registry.find(CacheFailureReporter.METRIC_NAME).counters();
+            assertThat(counters).hasSize(1);
+            io.micrometer.core.instrument.Counter counter = counters.iterator().next();
+            assertThat(counter.count()).isEqualTo(1.0);
+            assertThat(counter.getId().getTag("operation")).isEqualTo(operation.name());
+            assertThat(counter.getId().getTag("kind")).isEqualTo("REDIS");
+            assertThat(counter.getId().getTag("strategy")).isEqualTo(expectedStrategy.name());
         }
 
         @Test
-        @DisplayName("CLEAN uses FAIL_FAST")
-        void handleError_clean_returnsFailure() {
-            Exception e = createException("Redis error");
+        @DisplayName("CLEAN partial failure keeps the explicit PARTIAL_CLEAN kind")
+        void handleError_clean_preservesExplicitPartialCleanKind() {
+            io.micrometer.core.instrument.simple.SimpleMeterRegistry registry =
+                    new io.micrometer.core.instrument.simple.SimpleMeterRegistry();
+            CacheErrorHandler reportingHandler = new CacheErrorHandler(new CacheFailureReporter(registry));
+            // 普通 RuntimeException 若被自动分类会得到 REDIS；typed-kind 入口必须保留 PARTIAL_CLEAN
+            RuntimeException cause = new RuntimeException("deleted some keys then failed");
 
-            CacheResult result = handler.handleError(CacheOperation.CLEAN, "test-cache", "pattern:*", e);
+            CacheResult result = reportingHandler.handleError(
+                    CacheOperation.CLEAN, "test-cache", CacheResult.FailureKind.PARTIAL_CLEAN, cause);
 
             assertThat(result.isSuccess()).isFalse();
-        }
-
-        @Test
-        @DisplayName("CLEAN accepts pattern as key parameter")
-        void handleError_clean_acceptsPattern() {
-            Exception e = createException("Redis error");
-            String pattern = "cache:keys:*";
+            assertThat(result.failureKind()).isEqualTo(CacheResult.FailureKind.PARTIAL_CLEAN);
+            assertThat(result.cause()).isSameAs(cause);
 
-            CacheResult result = handler.handleError(CacheOperation.CLEAN, "cache", pattern, e);
+            CacheOperationException thrown = org.assertj.core.api.Assertions.catchThrowableOfType(
+                    () -> CacheErrorHandler.finalizeFailure(CacheOperation.CLEAN, "test-cache", result),
+                    CacheOperationException.class);
+            assertThat(thrown.getOperation()).isEqualTo(CacheOperation.CLEAN);
+            assertThat(thrown.getFailureKind()).isEqualTo(CacheResult.FailureKind.PARTIAL_CLEAN);
+            assertThat(thrown.getCause()).isSameAs(cause);
 
-            assertThat(result.isSuccess()).isFalse();
+            var counters = registry.find(CacheFailureReporter.METRIC_NAME).counters();
+            assertThat(counters).hasSize(1);
+            io.micrometer.core.instrument.Counter counter = counters.iterator().next();
+            assertThat(counter.count())
+                    .as("finalizeFailure 不得重复计数")
+                    .isEqualTo(1.0);
+            assertThat(counter.getId().getTag("operation")).isEqualTo("CLEAN");
+            assertThat(counter.getId().getTag("kind")).isEqualTo("PARTIAL_CLEAN");
+            assertThat(counter.getId().getTag("strategy")).isEqualTo("FAIL_FAST");
         }
     }
 
@@ -260,9 +244,9 @@ class StrategySelectionTests {
         void failFast_appropriateForWrites() {
             Exception e = createException("Error");
 
-            CacheResult putResult = handler.handleError(CacheOperation.PUT, "cache", "key", e);
-            CacheResult putIfAbsentResult = handler.handleError(CacheOperation.PUT_IF_ABSENT, "cache", "key", e);
-            CacheResult cleanResult = handler.handleError(CacheOperation.CLEAN, "cache", "pattern", e);
+            CacheResult putResult = handler.handleError(CacheOperation.PUT, "cache", e);
+            CacheResult putIfAbsentResult = handler.handleError(CacheOperation.PUT_IF_ABSENT, "cache", e);
+            CacheResult cleanResult = handler.handleError(CacheOperation.CLEAN, "cache", e);
 
             assertThat(putResult.isSuccess()).isFalse();
             assertThat(putIfAbsentResult.isSuccess()).isFalse();
@@ -274,7 +258,7 @@ void failFast_appropriateForWrites() {
         void silent_appropriateForRemoves() {
             Exception e = createException("Error");
 
-            CacheResult result = handler.handleError(CacheOperation.REMOVE, "cache", "key", e);
+            CacheResult result = handler.handleError(CacheOperation.REMOVE, "cache", e);
 
             assertThat(result.isSuccess()).isFalse();
         }
@@ -284,7 +268,7 @@ void silent_appropriateForRemoves() {
         void gracefulDegradation_appropriateForReads() {
             Exception e = createException("Error");
 
-            CacheResult result = handler.handleError(CacheOperation.GET, "cache", "key", e);
+            CacheResult result = handler.handleError(CacheOperation.GET, "cache", e);
 
             assertThat(result.isSuccess()).isFalse();
             assertThat(result.resultBytes()).isNull();
@@ -335,15 +319,16 @@ void cachePathLogs_omitRawKeyAndCauseMessage() {
             captured.start();
             logger.addAppender(captured);
             try {
+                // 敏感 sentinel 现在只存在于异常 message（key 参数已删除）
                 Exception e = new IllegalStateException("redis failed for key " + secretKey);
-                handler.handleError(CacheOperation.PUT, "cache", secretKey, e);
+                handler.handleError(CacheOperation.PUT, "cache", e);
 
                 assertThat(captured.list).isNotEmpty();
                 String logs = captured.list.stream()
                         .map(ch.qos.logback.classic.spi.ILoggingEvent::getFormattedMessage)
                         .reduce("", String::concat);
                 assertThat(logs)
-                        .as("WARN/ERROR 日志不得含 raw key 或 cause message")
+                        .as("WARN/ERROR 日志不得含异常 message（可能嵌入 key）")
                         .doesNotContain(secretKey)
                         .doesNotContain("redis failed for key");
             } finally {
@@ -361,7 +346,7 @@ void singleFailure_reportsExactlyOnce() {
 
             Exception e = createException("boom");
             // 同一事件只经 handleError 一次 → 计数恰好 1
-            reportingHandler.handleError(CacheOperation.PUT, "cache", "key", e);
+            reportingHandler.handleError(CacheOperation.PUT, "cache", e);
 
             var counters = registry.find(
                     "resicache.cache.failure").counters();
@@ -379,9 +364,33 @@ void noRegistry_reportsNothing() {
             CacheErrorHandler plainHandler = new CacheErrorHandler(null);
             Exception e = createException("boom");
 
-            CacheResult result = plainHandler.handleError(CacheOperation.GET, "cache", "key", e);
+            CacheResult result = plainHandler.handleError(CacheOperation.GET, "cache", e);
 
             assertThat(result.isSuccess()).isFalse();
         }
+
+        @Test
+        @DisplayName("null operation / kind / cause 被拒绝，且不产生失败计数")
+        void nullInputs_rejectWithoutCounting() {
+            io.micrometer.core.instrument.simple.SimpleMeterRegistry registry =
+                    new io.micrometer.core.instrument.simple.SimpleMeterRegistry();
+            CacheErrorHandler reportingHandler = new CacheErrorHandler(new CacheFailureReporter(registry));
+
+            org.assertj.core.api.Assertions.assertThatThrownBy(
+                            () -> reportingHandler.handleError(null, "cache", createException("boom")))
+                    .isInstanceOf(NullPointerException.class);
+            org.assertj.core.api.Assertions.assertThatThrownBy(
+                            () -> reportingHandler.handleError(CacheOperation.GET, "cache", (Exception) null))
+                    .isInstanceOf(NullPointerException.class);
+            org.assertj.core.api.Assertions.assertThatThrownBy(
+                            () -> reportingHandler.handleError(
+                                    CacheOperation.GET, "cache", (CacheResult.FailureKind) null,
+                                    createException("boom")))
+                    .isInstanceOf(NullPointerException.class);
+
+            assertThat(registry.find(CacheFailureReporter.METRIC_NAME).counters())
+                    .as("构造失败结果前抛错 → 不进入指标上报")
+                    .isEmpty();
+        }
     }
 }
diff --git a/src/test/java/io/github/davidhlp/spring/cache/redis/cache/RedisProCacheLoadPathTest.java b/src/test/java/io/github/davidhlp/spring/cache/redis/cache/RedisProCacheLoadPathTest.java
index 919f938c..904d521c 100644
--- a/src/test/java/io/github/davidhlp/spring/cache/redis/cache/RedisProCacheLoadPathTest.java
+++ b/src/test/java/io/github/davidhlp/spring/cache/redis/cache/RedisProCacheLoadPathTest.java
@@ -176,7 +176,6 @@ private RedisProCacheWriter writerWithPutFailure(
             return errorHandler.handleError(
                     context.getOperation(),
                     context.getCacheName(),
-                    context.getRedisKey(),
                     new IllegalStateException("redis put failed for key " + SENTINEL_KEY));
         });
         return new RedisProCacheWriter(

From 7bc957280495e575d27d01671184ed96ae69e6f5 Mon Sep 17 00:00:00 2001
From: DavidHLP <lysf15520112973@163.com>
Date: Sun, 20 Sep 2026 00:43:32 +0800
Subject: [PATCH 3/3] style: normalize source whitespace to the editorconfig
 contract

Trailing whitespace on javadoc and builder lines, one tab-indented
BloomFilterConfig block and two files missing their final newline all
violated the committed .editorconfig rules (4-space indent, trim trailing
whitespace, insert final newline) that no automated check enforces.

Whitespace-only: `git diff -w` against the parent is empty, so compiled
bytecodes and behavior are unchanged. testcontainers.properties gained its
missing trailing newline so the file ends like every other tracked text file.
---
 .../cache/redis/cache/ActualCacheHandler.java |  2 +-
 .../cache/redis/cache/BloomFilterConfig.java  | 22 +++++++++----------
 .../spring/cache/redis/cache/CacheInput.java  | 20 ++++++++---------
 .../redis/cache/HierarchicalBloomIFilter.java |  4 ++--
 .../spring/cache/redis/chain/FlowControl.java |  6 ++---
 .../cache/redis/chain/HandlerResult.java      | 14 ++++++------
 .../chain/model/EarlyExpirationDecision.java  | 10 ++++-----
 .../cache/redis/chain/model/TtlDecision.java  |  2 +-
 .../protection/bloom/filter/BloomIFilter.java |  2 +-
 src/test/resources/testcontainers.properties  |  2 +-
 10 files changed, 42 insertions(+), 42 deletions(-)

diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/cache/ActualCacheHandler.java b/src/main/java/io/github/davidhlp/spring/cache/redis/cache/ActualCacheHandler.java
index 2a8e0b2c..da1253a3 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/cache/ActualCacheHandler.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/cache/ActualCacheHandler.java
@@ -103,7 +103,7 @@ private CacheResult dispatchOperation(CacheContext context) {
 
     /**
      * 处理 GET 操作
-     * 
+     *
      * 注意：锁逻辑已由 SyncLockHandler 处理，这里直接执行 Redis 操作
      */
     private CacheResult handleGet(CacheContext context) {
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/cache/BloomFilterConfig.java b/src/main/java/io/github/davidhlp/spring/cache/redis/cache/BloomFilterConfig.java
index 43e10327..4fd7bc83 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/cache/BloomFilterConfig.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/cache/BloomFilterConfig.java
@@ -16,18 +16,18 @@
 @Slf4j
 class BloomFilterConfig {
 
-	private final String keyPrefix;
-	private final int bitSize;
-	private final int hashFunctions;
-	private final int hashCacheSize;
+    private final String keyPrefix;
+    private final int bitSize;
+    private final int hashFunctions;
+    private final int hashCacheSize;
 
-	public BloomFilterConfig(
-			String keyPrefix, int bitSize, int hashFunctions, int hashCacheSize) {
-		this.keyPrefix = keyPrefix;
-		this.bitSize = Math.max(1, bitSize);
-		this.hashFunctions = Math.max(1, hashFunctions);
-		this.hashCacheSize = Math.max(1, hashCacheSize);
-	}
+    public BloomFilterConfig(
+            String keyPrefix, int bitSize, int hashFunctions, int hashCacheSize) {
+        this.keyPrefix = keyPrefix;
+        this.bitSize = Math.max(1, bitSize);
+        this.hashFunctions = Math.max(1, hashFunctions);
+        this.hashCacheSize = Math.max(1, hashCacheSize);
+    }
 
     int[] positionsFor(String key) {
         if (key == null) {
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/cache/CacheInput.java b/src/main/java/io/github/davidhlp/spring/cache/redis/cache/CacheInput.java
index 78b35efd..55e9d21b 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/cache/CacheInput.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/cache/CacheInput.java
@@ -14,32 +14,32 @@
 
 /**
  * 缓存操作输入参数（不可变）
- * 
+ *
  * 包含请求的原始数据，在整个责任链中只读。
  * 设计为 record 确保不可变性。
  */
 record CacheInput(
     /** 缓存操作类型 */
     CacheOperation operation,
-    
+
     /** 缓存名称 */
     String cacheName,
-    
+
     /** Redis 完整 key */
     String redisKey,
-    
+
     /** 实际 key（去除前缀） */
     String actualKey,
-    
+
     /** 缓存值（字节数组） */
     @Nullable byte[] valueBytes,
-    
+
     /** 反序列化后的值 */
     @Nullable Object deserializedValue,
-    
+
     /** TTL */
     @Nullable Duration ttl,
-    
+
     /** 缓存操作配置 */
     @Nullable CachePolicyView.Source cacheOperation
 ) implements CacheContext.InputView {
@@ -69,10 +69,10 @@ public static class Builder {
         public Builder deserializedValue(Object value) { this.deserializedValue = value; return this; }
         public Builder ttl(Duration ttl) { this.ttl = ttl; return this; }
         public Builder cacheOperation(CachePolicyView.Source op) { this.cacheOperation = op; return this; }
-        
+
         public CacheInput build() {
             return new CacheInput(
-                operation, cacheName, redisKey, actualKey, 
+                operation, cacheName, redisKey, actualKey,
                 valueBytes, deserializedValue, ttl, cacheOperation
             );
         }
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/cache/HierarchicalBloomIFilter.java b/src/main/java/io/github/davidhlp/spring/cache/redis/cache/HierarchicalBloomIFilter.java
index b2c35356..26127317 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/cache/HierarchicalBloomIFilter.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/cache/HierarchicalBloomIFilter.java
@@ -9,14 +9,14 @@
 
 /**
  * JVM + Redis 双层布隆过滤器，优先使用 JVM 过滤结果，必要时回退 Redis。
- * 
+ *
  * <p>设计说明：
  * <ul>
  *   <li>本地布隆过滤器用于快速检查，减少 Redis 访问</li>
  *   <li>Redis 布隆过滤器作为权威数据源，在集群间共享</li>
  *   <li>缓存驱逐时需要调用 clear() 同步清除两个过滤器</li>
  * </ul>
- * 
+ *
  * <p>注意事项：
  * <ul>
  *   <li>布隆过滤器本身存在误判率（false positive），这是预期行为</li>
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/FlowControl.java b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/FlowControl.java
index c9538b37..880049c6 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/FlowControl.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/FlowControl.java
@@ -5,16 +5,16 @@
 /**
  * 责任链控制流决策 — 与 {@code chain/model/} 下的数据型 {@code *Decision} record
  * (Ttl/Null/Prefetch/EarlyExpiration 不同概念族)正交,重命名以消解词法碰撞。
- * 
+ *
  * <p>明确控制责任链的执行流程，避免隐式终止条件。
  */
 public enum FlowControl {
     /** 继续执行下一个 Handler */
     CONTINUE,
-    
+
     /** 终止责任链，返回当前结果 */
     TERMINATE,
-    
+
     /** 跳过剩余处理器，返回成功。
      *  <p>不变式：返回 {@code SKIP_ALL} 等价于请求引擎跳过剩余 handler，
      *  并由引擎在遇到该决策时单点置 {@code CacheContext.skipRemaining=true}
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/HandlerResult.java b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/HandlerResult.java
index aa126b06..c95d3b22 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/HandlerResult.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/HandlerResult.java
@@ -4,7 +4,7 @@
 
 /**
  * Handler 处理结果，包含链控制决策
- * 
+ *
  * 设计原则：
  * 1. 每个 Handler 返回明确的决策，控制链的执行
  * 2. 决策与结果分离，便于理解和维护
@@ -19,32 +19,32 @@ public record HandlerResult(FlowControl decision, CacheResult result) {
         Objects.requireNonNull(decision,
                 "HandlerResult decision is required by the SPI protocol");
     }
-    
+
     /** 继续执行下一个 Handler（无中间结果） */
     public static HandlerResult continueChain() {
         return new HandlerResult(FlowControl.CONTINUE, null);
     }
-    
+
     /** 继续执行，携带中间结果 */
     public static HandlerResult continueWith(CacheResult result) {
         return new HandlerResult(FlowControl.CONTINUE, result);
     }
-    
+
     /** 终止责任链，返回结果 */
     public static HandlerResult terminate(CacheResult result) {
         return new HandlerResult(FlowControl.TERMINATE, result);
     }
-    
+
     /** 终止责任链，无结果 */
     public static HandlerResult terminate() {
         return new HandlerResult(FlowControl.TERMINATE, null);
     }
-    
+
     /** 跳过所有剩余处理器 */
     public static HandlerResult skipAll() {
         return new HandlerResult(FlowControl.SKIP_ALL, CacheResult.success());
     }
-    
+
     /** 跳过所有剩余处理器，携带结果 */
     public static HandlerResult skipAll(CacheResult result) {
         return new HandlerResult(FlowControl.SKIP_ALL, result);
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/model/EarlyExpirationDecision.java b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/model/EarlyExpirationDecision.java
index 00c320cd..a9d0627f 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/model/EarlyExpirationDecision.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/model/EarlyExpirationDecision.java
@@ -4,16 +4,16 @@
 
 /**
  * 提前过期决策
- * 
+ *
  * 由 EarlyExpirationHandler 返回，指示如何处理提前过期。
  */
 public record EarlyExpirationDecision(
     /** 是否需要刷新 */
     boolean needsRefresh,
-    
+
     /** 是否为同步刷新（true = 返回 miss 触发刷新；false = 异步后台刷新） */
     boolean isSync,
-    
+
     /** 是否继续使用当前缓存值 */
     boolean continueWithCurrentValue
 ) {
@@ -21,12 +21,12 @@ public record EarlyExpirationDecision(
     public static EarlyExpirationDecision noRefresh() {
         return new EarlyExpirationDecision(false, false, true);
     }
-    
+
     /** 同步提前过期：返回 miss，触发调用方刷新数据 */
     public static EarlyExpirationDecision syncRefresh() {
         return new EarlyExpirationDecision(true, true, false);
     }
-    
+
     /** 异步提前过期：后台刷新，返回当前值 */
     public static EarlyExpirationDecision asyncRefresh() {
         return new EarlyExpirationDecision(true, false, true);
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/model/TtlDecision.java b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/model/TtlDecision.java
index bb1543b3..4c06d3cf 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/model/TtlDecision.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/model/TtlDecision.java
@@ -25,4 +25,4 @@ public static TtlDecision applied(long finalTtl) {
     public static TtlDecision skipped() {
         return new TtlDecision(-1L, false);
     }
-}
\ No newline at end of file
+}
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/protection/bloom/filter/BloomIFilter.java b/src/main/java/io/github/davidhlp/spring/cache/redis/protection/bloom/filter/BloomIFilter.java
index 89d16bd7..ed60a041 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/protection/bloom/filter/BloomIFilter.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/protection/bloom/filter/BloomIFilter.java
@@ -17,4 +17,4 @@ public interface BloomIFilter {
 
     /** 清空指定缓存的布隆过滤器。 */
     void clear(String cacheName);
-}
\ No newline at end of file
+}
diff --git a/src/test/resources/testcontainers.properties b/src/test/resources/testcontainers.properties
index e8d1da46..3088e2b2 100644
--- a/src/test/resources/testcontainers.properties
+++ b/src/test/resources/testcontainers.properties
@@ -13,4 +13,4 @@ testcontainers.reuse.enable=false
 # runner (Docker engine max API = 1.48, "client version 1.54 is too new") and
 # made every Testcontainers test fail with
 # "Previous attempts to find a Docker environment failed." Let auto-negotiation
-# handle the version; it works on both the GitHub runner and local WSL2.
\ No newline at end of file
+# handle the version; it works on both the GitHub runner and local WSL2.