feat: add pre-write interceptors for external caches

docs/CN/Config.md

@@ -23,6 +23,8 @@ jetcache:
       broadcastChannel: projectA
       valueEncoder: java #其他可选：kryo/kryo5
       valueDecoder: java #其他可选：kryo/kryo5
+      # 同时演示两种解析方式：带 bean: 前缀的 Spring Bean，以及 plain name 对应的 customContainer 条目
+      externalWriteInterceptors: bean:loggingExternalCacheWriteInterceptor,auditExternalCacheWriteInterceptor
       poolConfig:
         minIdle: 5
         maxIdle: 20
@@ -59,6 +61,7 @@ jetcache:
 | jetcache.[local/remote].${area}.expireAfterWriteInMillis | 无穷大                         | 以毫秒为单位指定超时时间的全局配置(以前为defaultExpireInMillis)                                                                                                                                                           |
 | jetcache.remote.${area}.broadcastChannel | 无                           | jetcahe2.7的两级缓存支持更新以后失效其他JVM中的local cache，但多个服务共用redis同一个channel可能会造成广播风暴，需要在这里指定channel，你可以决定多个不同的服务是否共用同一个channel。如果没有指定则不开启。                                                                       |
 | jetcache.local.${area}.expireAfterAccessInMillis | 0                           | 需要jetcache2.2以上，以毫秒为单位，指定多长时间没有访问，就让缓存失效，当前只有本地缓存支持。0表示不使用这个功能。                                                                                                                                       |
+| jetcache.remote.${area}.externalWriteInterceptors | 无                           | 指定外部缓存写入前回调，多个用逗号分隔。`bean:xxx` 表示按 Spring Bean 名称解析；普通名称表示从 `AutoConfigureBeans.customContainer` 中解析。例如：`bean:loggingInterceptor,logging`。回调接收的是只读写入元数据，适合做日志、审计、埋点、大 key 检测等，不用于修改实际编码后的写入请求。返回 `WriteInterceptDecision.reject(...)` 会拒绝当前写操作，并通过缓存结果返回失败；若回调抛出异常，则表示拦截器自身执行异常，同样会通过缓存结果返回，而不会从基础写方法向外传播。像 `@Cached`、`@CreateCache`、`QuickConfig.externalWriteInterceptors(...)` 这样的单 cache 配置会覆盖这个全局配置。 |
 
 上表中${area}对应@Cached和@CreateCache的area属性。注意如果注解上没有指定area，默认值是"default"。
 

docs/CN/CreateCache.md

@@ -42,7 +42,8 @@ private Cache<Long, UserDO> userCache;
 |localLimit|未定义|如果cacheType为CacheType.LOCAL或CacheType.BOTH，这个参数指定本地缓存的最大元素数量，以控制内存占用。注解上没有定义的时候会使用全局配置，如果此时全局配置也没有定义，则取100|
 |serialPolicy|未定义|如果cacheType为CacheType.REMOTE或CacheType.BOTH，指定远程缓存的序列化方式。JetCache内置的可选值为SerialPolicy.JAVA和SerialPolicy.KRYO。注解上没有定义的时候会使用全局配置，如果此时全局配置也没有定义，则取SerialPolicy.JAVA|
 |keyConvertor|未定义|指定KEY的转换方式，用于将复杂的KEY类型转换为缓存实现可以接受的类型，JetCache内置的可选值为KeyConvertor.FASTJSON和KeyConvertor.NONE。NONE表示不转换，FASTJSON通过fastjson将复杂对象KEY转换成String。如果注解上没有定义，则使用全局配置。|
+|externalWriteInterceptors|未定义|指定外部缓存写入前回调列表，仅当 cacheType 为 REMOTE 或 BOTH 时有效；如果配置在 LOCAL 上会抛出配置异常。注解方式必须使用 `bean:` 前缀引用 Spring Bean，例如：`bean:loggingInterceptor,bean:auditInterceptor`。回调接收的是只读写入元数据，适合做日志、审计、埋点、大 key 检测等，不用于修改实际编码后的写入请求。返回 `WriteInterceptDecision.reject(...)` 会拒绝当前写操作，并通过缓存结果返回失败；若回调抛出异常，则表示拦截器自身执行异常，同样会通过缓存结果返回，而不会从基础写方法向外传播。如果在注解上配置了该属性，会覆盖当前 cache 的全局 `jetcache.remote.${area}.externalWriteInterceptors` 配置。|
 
 ## 默认值
 
-对于以上未定义默认值的参数，如果没有指定，将使用yml中指定的全局配置，请参考[配置说明](Config.md)。
+对于以上未定义默认值的参数，如果没有指定，将使用yml中指定的全局配置，请参考[配置说明](Config.md)。

docs/CN/MethodCache.md

@@ -37,6 +37,7 @@ key使用Spring的[SpEL](https://docs.spring.io/spring/docs/4.2.x/spring-framewo
 |cacheNullValue|false|当方法返回值为null的时候是否要缓存|
 |condition|未定义|使用[SpEL](https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/expressions.html)指定条件，如果表达式返回true的时候才去缓存中查询|
 |postCondition|未定义|使用[SpEL](https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/expressions.html)指定条件，如果表达式返回true的时候才更新缓存，该评估在方法执行后进行，因此可以访问到#result|
+|externalWriteInterceptors|未定义|指定外部缓存写入前回调，多个用逗号分隔。仅当 cacheType 为 REMOTE 或 BOTH 时有效；如果配置在 LOCAL 上会抛出配置异常。注解方式必须使用 `bean:` 前缀引用 Spring Bean，例如：`"bean:loggingInterceptor,bean:auditInterceptor"`。该回调接收的是只读写入元数据，适合做日志、审计、埋点、大 key 检测等，不用于修改实际编码后的写入请求。返回 `WriteInterceptDecision.reject(...)` 会拒绝当前写操作，并通过缓存结果返回失败；若回调抛出异常，则表示拦截器自身执行异常，同样会通过缓存结果返回，而不会从基础写方法向外传播。如果在注解上配置了该属性，会覆盖当前 cache 的全局 `jetcache.remote.${area}.externalWriteInterceptors` 配置。全局配置方式参见 [Config](Config.md)。|
 
 @CacheInvalidate注解说明：
 
@@ -76,4 +77,3 @@ key使用Spring的[SpEL](https://docs.spring.io/spring/docs/4.2.x/spring-framewo
 
 
 对于以上未定义默认值的参数，如果没有指定，将使用yml中指定的全局配置，全局配置请参考[配置说明](Config.md)。
-

docs/EN/Config.md

@@ -23,6 +23,8 @@ jetcache:
       broadcastChannel: projectA
       valueEncoder: java #other choose：kryo/kryo5
       valueDecoder: java #other choose：kryo/kryo5
+      # Demonstrates both resolution paths: Spring bean via "bean:" and customContainer entry via plain name.
+      externalWriteInterceptors: bean:loggingExternalCacheWriteInterceptor,auditExternalCacheWriteInterceptor
       poolConfig:
         minIdle: 5
         maxIdle: 20
@@ -59,6 +61,7 @@ The description of configuration listed in the below table:
 | jetcache.[local/remote].${area}.expireAfterWriteInMillis | infinity | Global config of write expire time, in millis.                                                                                                                                                                                                                                                                                                       |
 | jetcache.remote.${area}.broadcastChannel | n/a | jetcahe2.7 support invalidate local cache of other jvm after updatation (cacheType = CacheType.BOTH), this config specify broadcast channel, this feature disabled if not set                                                                                                                                                                        |
 | jetcache.local.${area}.expireAfterAccessInMillis | 0 | Global config of read expire time, in millis. Need jetcache2.2+, only local cache support this feature. 0 indicates disabled read expire feature.                                                                                                                                                                                                    |
+| jetcache.remote.${area}.externalWriteInterceptors | n/a | Specify external cache pre-write hooks, separated by commas. `bean:xxx` resolves a Spring Bean by name; a plain name resolves an entry from `AutoConfigureBeans.customContainer`. Example: `bean:loggingInterceptor,logging`. The hook receives read-only write metadata and is intended for logging, auditing, metrics or big-key detection, not for mutating the outgoing encoded write request. Returning `WriteInterceptDecision.reject(...)` rejects the current write operation through its cache result. Throwing an exception indicates the interceptor itself failed unexpectedly and is also reported through the cache result instead of propagating from the base write methods. Cache-specific configuration such as `@Cached`, `@CreateCache`, or `QuickConfig.externalWriteInterceptors(...)` overrides this global setting for the current cache. |
 
 The ${area} of the above table is the ```area``` attribute of ```@Cached``` and ```@CreateCache```. Note that the default value of ```area``` attribute of the two annotation is ```"default"```.
 

docs/EN/CreateCache.md

@@ -42,7 +42,8 @@ private Cache<Long, UserDO> userCache;
 |localLimit|undefined|Specify max elements in local memory when ```cacheType``` is CacheType.LOCAL or CacheType.BOTH. Use global config if the attribute value is absent, and if the global config is not defined either, use 100.|
 |serialPolicy|undefined|Specify the serialization policy of remote cache when ```cacheType``` is CacheType.REMOTE or CacheType.BOTH. The JetCache build-in ```serialPolicy``` are SerialPolicy.JAVA or SerialPolicy.KRYO. Use global config if the attribute value is absent, and if the global config is not defined either, use ```SerialPolicy.JAVA```.|
 |keyConvertor|undefined|Specify the key convertor. Used to convert the complex key object. The JetCache build-in ```keyConvertor``` are KeyConvertor.FASTJSON or KeyConvertor.NONE. NONE indicate do not convert, FASTJSON will use fastjson to convert key object to a string. Use global config if the attribute value is absent.|
+|externalWriteInterceptors|undefined|Specify the list of external cache pre-write hooks. It is only valid when ```cacheType``` is REMOTE or BOTH; using it with LOCAL causes a configuration error. Annotation-based configuration must reference Spring Beans with the ```bean:``` prefix, for example ```bean:loggingInterceptor,bean:auditInterceptor```. The hook receives read-only write metadata and is intended for logging, auditing, metrics or big-key detection, not for mutating the outgoing encoded write request. Returning ```WriteInterceptDecision.reject(...)``` rejects the current write operation through its cache result. Throwing an exception indicates the interceptor itself failed unexpectedly and is also reported through the cache result instead of propagating from the base write methods. If this attribute is configured on the annotation, it overrides the global ```jetcache.remote.${area}.externalWriteInterceptors``` setting for the current cache.|
 
 # Default values
 There are some attributes in the above table has no default value. JetCache will use global config value when you not specify the value in annotation.
-See [Configuration details](Config.md) for more information about global config.
+See [Configuration details](Config.md) for more information about global config.

docs/EN/MethodCache.md

@@ -34,6 +34,7 @@ The attributes of ```@Cached``` are similar with ```@CreateCache``` except ```@C
 |cacheNullValue|false|Specify whether a null value should be cached.|
 |condition|undefined|Expression script used for conditioning the method caching, the cache is not used when evaluation result is false. Can't refer return value of real method.|
 |postCondition|undefined|Expression script used for conditioning the method cache updating, the cache updating action is vetoed when the evaluation result is false. Evaluation occurs after real method invocation so we can refer *#result* in script.|
+|externalWriteInterceptors|undefined|Specify external cache pre-write hooks, separated by commas. It is only valid when cacheType is REMOTE or BOTH; using it with LOCAL causes a configuration error. Annotation-based configuration must reference Spring Beans with the `bean:` prefix, for example: `"bean:loggingInterceptor,bean:auditInterceptor"`. The hook receives read-only write metadata and is intended for logging, auditing, metrics or big-key detection, not for mutating the outgoing encoded write request. Returning `WriteInterceptDecision.reject(...)` rejects the current write operation through its cache result. Throwing an exception indicates the interceptor itself failed unexpectedly and is also reported through the cache result instead of propagating from the base write methods. If this attribute is configured on the annotation, it overrides the global `jetcache.remote.${area}.externalWriteInterceptors` setting for the current cache. For global configuration style, see [Config](Config.md).|
 
 @CacheInvalidate attribute table:
 
@@ -72,4 +73,4 @@ Currently it only take effect only in each single JVM, that is, in one JVM there
 other threads wait for the result. 
 
 There are some attributes in the above table has no default value. JetCache will use global config when you not specify the value in annotation.
-See [Configuration details](Config.md) for more information about global config.
+See [Configuration details](Config.md) for more information about global config.

jetcache-anno-api/src/main/java/com/alicp/jetcache/anno/Cached.java

@@ -128,4 +128,27 @@
      */
     String postCondition() default CacheConsts.UNDEFINED_STRING;
 
+    /**
+     * Specify external cache write pre-hooks for this cache.
+     * Multiple interceptor bean references can be separated by commas.
+     * In annotation-based configuration, interceptor beans must be Spring beans
+     * referenced with the {@code bean:} prefix, for example
+     * {@code bean:loggingInterceptor,bean:auditInterceptor}.
+     * <p>
+     * The hook runs before REMOTE/BOTH cache write attempts and receives an
+     * read-only write metadata view. It is intended for observation or
+     * validation, not for mutating the outgoing encoded write request.
+     * Throwing an exception from the hook causes the current write operation
+     * to fail through its cache result instead of propagating from the base
+     * write methods.
+     * </p>
+     * <p>
+     * This attribute is only valid for external caches (REMOTE or BOTH cache types).
+     * Using it with LOCAL cache type is a configuration error.
+     * </p>
+     *
+     * @return external cache write interceptor bean references
+     */
+    String externalWriteInterceptors() default CacheConsts.UNDEFINED_STRING;
+
 }

jetcache-anno-api/src/main/java/com/alicp/jetcache/anno/CreateCache.java

@@ -94,4 +94,27 @@
      * @return convertor name of cache key
      */
     String keyConvertor() default CacheConsts.UNDEFINED_STRING;
+
+    /**
+     * Specify external cache write pre-hooks for this cache.
+     * Multiple interceptor bean references can be separated by commas.
+     * In annotation-based configuration, interceptor beans must be Spring beans
+     * referenced with the {@code bean:} prefix, for example
+     * {@code bean:loggingInterceptor,bean:auditInterceptor}.
+     * <p>
+     * The hook runs before REMOTE/BOTH cache write attempts and receives an
+     * read-only write metadata view. It is intended for observation or
+     * validation, not for mutating the outgoing encoded write request.
+     * Throwing an exception from the hook causes the current write operation
+     * to fail through its cache result instead of propagating from the base
+     * write methods.
+     * </p>
+     * <p>
+     * This attribute is only valid for external caches (REMOTE or BOTH cache types).
+     * Using it with LOCAL cache type is a configuration error.
+     * </p>
+     *
+     * @return external cache write interceptor bean references
+     */
+    String externalWriteInterceptors() default CacheConsts.UNDEFINED_STRING;
 }

jetcache-anno/src/main/java/com/alicp/jetcache/anno/field/CreateCacheWrapper.java

@@ -70,10 +70,10 @@ private void init() {
         cac.setLocalLimit(ann.localLimit());
         cac.setSerialPolicy(ann.serialPolicy());
         cac.setKeyConvertor(ann.keyConvertor());
+        cac.setExternalWriteInterceptors(ann.externalWriteInterceptors());
 
         cac.setRefreshPolicy(refreshPolicy);
         cac.setPenetrationProtectConfig(protectConfig);
-
         String cacheName = cac.getName();
         if (CacheConsts.isUndefined(cacheName)) {
             String[] hiddenPackages = globalCacheConfig.getHiddenPackages();

jetcache-anno/src/main/java/com/alicp/jetcache/anno/method/CacheConfigUtil.java

@@ -49,6 +49,7 @@ private static CachedAnnoConfig parseCached(Method m) {
         cc.setSerialPolicy(anno.serialPolicy());
         cc.setKeyConvertor(anno.keyConvertor());
         cc.setKey(anno.key());
+        cc.setExternalWriteInterceptors(anno.externalWriteInterceptors());
         cc.setDefineMethod(m);
 
         CacheRefresh cacheRefresh = m.getAnnotation(CacheRefresh.class);

jetcache-anno/src/main/java/com/alicp/jetcache/anno/support/CacheContext.java

@@ -7,6 +7,7 @@
 import com.alicp.jetcache.CacheConfigException;
 import com.alicp.jetcache.CacheManager;
 import com.alicp.jetcache.anno.CacheConsts;
+import com.alicp.jetcache.anno.CacheType;
 import com.alicp.jetcache.anno.EnableCache;
 import com.alicp.jetcache.anno.method.CacheInvokeContext;
 import com.alicp.jetcache.template.QuickConfig;
@@ -114,6 +115,13 @@ public Cache __createOrGetCache(CachedAnnoConfig cac, String area, String cacheN
             b.penetrationProtectTimeout(ppc.getPenetrationProtectTimeout());
         }
         b.refreshPolicy(cac.getRefreshPolicy());
+        if (!CacheConsts.isUndefined(cac.getExternalWriteInterceptors())) {
+            if (cac.getCacheType() == CacheType.LOCAL) {
+                throw new CacheConfigException("externalWriteInterceptors only works for REMOTE or BOTH cache types");
+            } else {
+                b.externalWriteInterceptors(configProvider.parseWriteInterceptors(cac.getExternalWriteInterceptors()));
+            }
+        }
         return cacheManager.getOrCreateCache(b.build());
     }
 

jetcache-anno/src/main/java/com/alicp/jetcache/anno/support/CachedAnnoConfig.java

@@ -29,6 +29,7 @@ public class CachedAnnoConfig extends CacheAnnoConfig {
     private Function<Object, Boolean> postConditionEvaluator;
     private RefreshPolicy refreshPolicy;
     private PenetrationProtectConfig penetrationProtectConfig;
+    private String externalWriteInterceptors;
 
     public boolean isEnabled() {
         return enabled;
@@ -142,4 +143,12 @@ public boolean isSyncLocal() {
     public void setSyncLocal(boolean syncLocal) {
         this.syncLocal = syncLocal;
     }
+
+    public String getExternalWriteInterceptors() {
+        return externalWriteInterceptors;
+    }
+
+    public void setExternalWriteInterceptors(String externalWriteInterceptors) {
+        this.externalWriteInterceptors = externalWriteInterceptors;
+    }
 }