diff --git a/src/main/java/com/mingliqiye/utils/springboot/annotation/ApplicationDestroyedRunner.java b/src/main/java/com/mingliqiye/utils/springboot/annotation/ApplicationDestroyedRunner.java new file mode 100644 index 0000000..6999dc8 --- /dev/null +++ b/src/main/java/com/mingliqiye/utils/springboot/annotation/ApplicationDestroyedRunner.java @@ -0,0 +1,83 @@ +/* + * Copyright 2026 mingliqiye + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * ProjectName mingli-utils + * ModuleName mingli-utils.main + * CurrentFile ApplicationDestroyedRunner.java + * LastUpdate 2026-11-18 08:21:37 + * UpdateUser MingLiPro + */ + +package com.mingliqiye.utils.springboot.annotation; + +import org.springframework.context.event.ContextClosedEvent; +import org.springframework.context.event.EventListener; +import org.springframework.core.Ordered; +import org.springframework.core.annotation.AliasFor; +import org.springframework.core.annotation.Order; + +import java.lang.annotation.*; + +/** + * 应用销毁(上下文关闭)事件监听注解。 + * + *
标注在 Spring Bean 的方法上,当 Spring 应用上下文关闭 + * ({@link ContextClosedEvent} 发布)时自动调用该方法。
+ * + * @deprecated 已弃用,请改用 {@link ContextClosedEventListener}(监听相同事件,命名更规范)。 + * @see ContextClosedEventListener + * @see EventListener + * @see ContextClosedEvent + */ +@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE}) +@Retention(RetentionPolicy.RUNTIME) +@Documented +@EventListener(ContextClosedEvent.class) +@Order +@Deprecated(since = "use ApplicationReadyEventListener") +public @interface ApplicationDestroyedRunner { + /** + * SpEL 条件表达式,仅当表达式求值为 true 时才执行监听方法。 + * + * @return 条件表达式,默认为空字符串(无条件执行) + */ + @AliasFor(annotation = EventListener.class, attribute = "condition") + String condition() default ""; + + /** + * 当事件不是 {@link ContextClosedEvent} 类型时是否仍默认执行监听方法。 + * + * @return 是否默认执行,默认为 true + */ + @AliasFor(annotation = EventListener.class, attribute = "defaultExecution") + boolean defaultExecution() default true; + + /** + * 监听器的唯一标识,用于注册可指定 id 的监听器。 + * + * @return 监听器 id,默认为空字符串(自动生成) + */ + @AliasFor(annotation = EventListener.class, attribute = "id") + String id() default ""; + + /** + * 监听器的执行顺序,值越小优先级越高。 + * + * @return 顺序值,默认为 {@link Ordered#LOWEST_PRECEDENCE} + * @see Ordered#getOrder() + */ + @AliasFor(annotation = Order.class, attribute = "value") + int order() default Ordered.LOWEST_PRECEDENCE; +} diff --git a/src/main/java/com/mingliqiye/utils/springboot/annotation/ApplicationReadyEventListener.java b/src/main/java/com/mingliqiye/utils/springboot/annotation/ApplicationReadyEventListener.java new file mode 100644 index 0000000..43df7c6 --- /dev/null +++ b/src/main/java/com/mingliqiye/utils/springboot/annotation/ApplicationReadyEventListener.java @@ -0,0 +1,95 @@ +/* + * Copyright 2026 mingliqiye + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * ProjectName mingli-utils + * ModuleName mingli-utils.main + * CurrentFile ApplicationReadyEventListener.java + * LastUpdate 2026-11-18 08:21:57 + * UpdateUser MingLiPro + */ + +package com.mingliqiye.utils.springboot.annotation; + + +import org.springframework.boot.context.event.ApplicationReadyEvent; +import org.springframework.context.event.EventListener; +import org.springframework.core.Ordered; +import org.springframework.core.annotation.AliasFor; +import org.springframework.core.annotation.Order; + +import java.lang.annotation.*; + + +/** + * 应用就绪事件监听注解。 + * + *标注在 Spring Bean 的方法上,当 Spring Boot 应用完成启动并就绪 + * ({@link ApplicationReadyEvent} 发布)时自动调用该方法, + * 等价于 {@code @EventListener(ApplicationReadyEvent.class)} 的组合简化写法。
+ * + *使用示例:
+ *{@code
+ * @Component
+ * public class InitTask {
+ * @ApplicationReadyEventListener(order = 0)
+ * public void onReady() {
+ * // 应用就绪后执行的初始化逻辑
+ * }
+ * }
+ * }
+ *
+ * @see EventListener
+ * @see ApplicationReadyEvent
+ */
+@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@EventListener(ApplicationReadyEvent.class)
+@Order
+public @interface ApplicationReadyEventListener {
+ /**
+ * SpEL 条件表达式,仅当表达式求值为 true 时才执行监听方法。
+ *
+ * @return 条件表达式,默认为空字符串(无条件执行)
+ */
+ @AliasFor(annotation = EventListener.class, attribute = "condition")
+ String condition() default "";
+
+ /**
+ * 当事件不是 {@link ApplicationReadyEvent} 类型时是否仍默认执行监听方法。
+ *
+ * @return 是否默认执行,默认为 true
+ */
+ @AliasFor(annotation = EventListener.class, attribute = "defaultExecution")
+ boolean defaultExecution() default true;
+
+ /**
+ * 监听器的唯一标识,用于注册可指定 id 的监听器。
+ *
+ * @return 监听器 id,默认为空字符串(自动生成)
+ */
+ @AliasFor(annotation = EventListener.class, attribute = "id")
+ String id() default "";
+
+
+ /**
+ * 监听器的执行顺序,值越小优先级越高。
+ *
+ * @return 顺序值,默认为 {@link Ordered#LOWEST_PRECEDENCE}
+ * @see Ordered#getOrder()
+ */
+ @AliasFor(annotation = Order.class, attribute = "value")
+ int order() default Ordered.LOWEST_PRECEDENCE;
+}
diff --git a/src/main/java/com/mingliqiye/utils/springboot/annotation/ApplicationStartedRunner.java b/src/main/java/com/mingliqiye/utils/springboot/annotation/ApplicationStartedRunner.java
new file mode 100644
index 0000000..437a6f2
--- /dev/null
+++ b/src/main/java/com/mingliqiye/utils/springboot/annotation/ApplicationStartedRunner.java
@@ -0,0 +1,84 @@
+/*
+ * Copyright 2026 mingliqiye
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * ProjectName mingli-utils
+ * ModuleName mingli-utils.main
+ * CurrentFile ApplicationStartedRunner.java
+ * LastUpdate 2026-11-18 08:21:57
+ * UpdateUser MingLiPro
+ */
+
+package com.mingliqiye.utils.springboot.annotation;
+
+import org.springframework.boot.context.event.ApplicationReadyEvent;
+import org.springframework.context.event.EventListener;
+import org.springframework.core.Ordered;
+import org.springframework.core.annotation.AliasFor;
+import org.springframework.core.annotation.Order;
+
+import java.lang.annotation.*;
+
+/**
+ * 应用启动完成事件监听注解。
+ *
+ * 标注在 Spring Bean 的方法上,当 Spring Boot 应用完成启动并就绪 + * ({@link ApplicationReadyEvent} 发布)时自动调用该方法。
+ * + * @deprecated 已弃用,请改用 {@link ApplicationReadyEventListener}(功能完全一致,命名更规范)。 + * @see ApplicationReadyEventListener + * @see EventListener + * @see ApplicationReadyEvent + */ +@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE}) +@Retention(RetentionPolicy.RUNTIME) +@Documented +@EventListener(ApplicationReadyEvent.class) +@Order +@Deprecated(since = "use ApplicationReadyEventListener") +public @interface ApplicationStartedRunner { + /** + * SpEL 条件表达式,仅当表达式求值为 true 时才执行监听方法。 + * + * @return 条件表达式,默认为空字符串(无条件执行) + */ + @AliasFor(annotation = EventListener.class, attribute = "condition") + String condition() default ""; + + /** + * 当事件不是 {@link ApplicationReadyEvent} 类型时是否仍默认执行监听方法。 + * + * @return 是否默认执行,默认为 true + */ + @AliasFor(annotation = EventListener.class, attribute = "defaultExecution") + boolean defaultExecution() default true; + + /** + * 监听器的唯一标识,用于注册可指定 id 的监听器。 + * + * @return 监听器 id,默认为空字符串(自动生成) + */ + @AliasFor(annotation = EventListener.class, attribute = "id") + String id() default ""; + + + /** + * 监听器的执行顺序,值越小优先级越高。 + * + * @return 顺序值,默认为 {@link Ordered#LOWEST_PRECEDENCE} + * @see Ordered#getOrder() + */ + @AliasFor(annotation = Order.class, attribute = "value") + int order() default Ordered.LOWEST_PRECEDENCE; +} diff --git a/src/main/java/com/mingliqiye/utils/springboot/annotation/ContextClosedEventListener.java b/src/main/java/com/mingliqiye/utils/springboot/annotation/ContextClosedEventListener.java new file mode 100644 index 0000000..08afd9c --- /dev/null +++ b/src/main/java/com/mingliqiye/utils/springboot/annotation/ContextClosedEventListener.java @@ -0,0 +1,93 @@ +/* + * Copyright 2026 mingliqiye + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * ProjectName mingli-utils + * ModuleName mingli-utils.main + * CurrentFile ContextClosedEventListener.java + * LastUpdate 2026-11-18 08:21:23 + * UpdateUser MingLiPro + */ + +package com.mingliqiye.utils.springboot.annotation; + +import org.springframework.context.event.ContextClosedEvent; +import org.springframework.context.event.EventListener; +import org.springframework.core.Ordered; +import org.springframework.core.annotation.AliasFor; +import org.springframework.core.annotation.Order; + +import java.lang.annotation.*; + +/** + * 应用上下文关闭事件监听注解。 + * + *标注在 Spring Bean 的方法上,当 Spring 应用上下文关闭 + * ({@link ContextClosedEvent} 发布)时自动调用该方法, + * 等价于 {@code @EventListener(ContextClosedEvent.class)} 的组合简化写法, + * 适用于应用停机前的资源清理、状态保存等场景。
+ * + *使用示例:
+ *{@code
+ * @Component
+ * public class CleanupTask {
+ * @ContextClosedEventListener
+ * public void onClosed() {
+ * // 上下文关闭前执行的清理逻辑
+ * }
+ * }
+ * }
+ *
+ * @see EventListener
+ * @see ContextClosedEvent
+ */
+@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@EventListener(ContextClosedEvent.class)
+@Order
+public @interface ContextClosedEventListener {
+ /**
+ * SpEL 条件表达式,仅当表达式求值为 true 时才执行监听方法。
+ *
+ * @return 条件表达式,默认为空字符串(无条件执行)
+ */
+ @AliasFor(annotation = EventListener.class, attribute = "condition")
+ String condition() default "";
+
+ /**
+ * 当事件不是 {@link ContextClosedEvent} 类型时是否仍默认执行监听方法。
+ *
+ * @return 是否默认执行,默认为 true
+ */
+ @AliasFor(annotation = EventListener.class, attribute = "defaultExecution")
+ boolean defaultExecution() default true;
+
+ /**
+ * 监听器的唯一标识,用于注册可指定 id 的监听器。
+ *
+ * @return 监听器 id,默认为空字符串(自动生成)
+ */
+ @AliasFor(annotation = EventListener.class, attribute = "id")
+ String id() default "";
+
+ /**
+ * 监听器的执行顺序,值越小优先级越高。
+ *
+ * @return 顺序值,默认为 {@link Ordered#LOWEST_PRECEDENCE}
+ * @see Ordered#getOrder()
+ */
+ @AliasFor(annotation = Order.class, attribute = "value")
+ int order() default Ordered.LOWEST_PRECEDENCE;
+}
diff --git a/src/main/kotlin/com/mingliqiye/utils/springboot/annotation/ApplicationDestroyedRunner.kt b/src/main/kotlin/com/mingliqiye/utils/springboot/annotation/ApplicationDestroyedRunner.kt
deleted file mode 100644
index b6df3c2..0000000
--- a/src/main/kotlin/com/mingliqiye/utils/springboot/annotation/ApplicationDestroyedRunner.kt
+++ /dev/null
@@ -1,36 +0,0 @@
-/*
- * Copyright 2026 mingliqiye
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * ProjectName mingli-utils
- * ModuleName mingli-utils.main
- * CurrentFile ApplicationDestroyedRunner.kt
- * LastUpdate 2026-03-10 09:04:02
- * UpdateUser MingLiPro
- */
-
-package com.mingliqiye.utils.springboot.annotation
-
-/**
- * 标记在 Spring 上下文关闭时执行的方法。
- * 被标注的方法会在 ContextClosedEvent 触发时由
- * [com.mingliqiye.utils.springboot.listener.ApplicationListener] 反射调用,
- * 多个方法按 [order] 升序执行。
- *
- * @property order 执行顺序,值越小越先执行,默认为 [Int.MIN_VALUE]
- */
-@Target(AnnotationTarget.FUNCTION)
-annotation class ApplicationDestroyedRunner(
- val order: Int = Int.MIN_VALUE,
-)
diff --git a/src/main/kotlin/com/mingliqiye/utils/springboot/annotation/ApplicationStartedRunner.kt b/src/main/kotlin/com/mingliqiye/utils/springboot/annotation/ApplicationStartedRunner.kt
deleted file mode 100644
index d3f6c7b..0000000
--- a/src/main/kotlin/com/mingliqiye/utils/springboot/annotation/ApplicationStartedRunner.kt
+++ /dev/null
@@ -1,36 +0,0 @@
-/*
- * Copyright 2026 mingliqiye
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * ProjectName mingli-utils
- * ModuleName mingli-utils.main
- * CurrentFile ApplicationStartedRunner.kt
- * LastUpdate 2026-03-11 08:46:40
- * UpdateUser MingLiPro
- */
-
-package com.mingliqiye.utils.springboot.annotation
-
-/**
- * 标记在 Spring Boot 应用启动完成后执行的方法。
- * 被标注的方法会在 ApplicationStartedEvent 触发时由
- * [com.mingliqiye.utils.springboot.listener.ApplicationListener] 反射调用,
- * 多个方法按 [order] 升序执行。
- *
- * @property order 执行顺序,值越小越先执行,默认为 [Int.MIN_VALUE]
- */
-@Target(AnnotationTarget.FUNCTION)
-annotation class ApplicationStartedRunner(
- val order: Int = Int.MIN_VALUE,
-)
diff --git a/src/main/kotlin/com/mingliqiye/utils/springboot/annotation/Listener.kt b/src/main/kotlin/com/mingliqiye/utils/springboot/annotation/Listener.kt
deleted file mode 100644
index 7e370ae..0000000
--- a/src/main/kotlin/com/mingliqiye/utils/springboot/annotation/Listener.kt
+++ /dev/null
@@ -1,39 +0,0 @@
-/*
- * Copyright 2026 mingliqiye
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * ProjectName mingli-utils
- * ModuleName mingli-utils.main
- * CurrentFile Listener.kt
- * LastUpdate 2026-03-10 09:04:02
- * UpdateUser MingLiPro
- */
-
-package com.mingliqiye.utils.springboot.annotation
-
-import org.springframework.core.annotation.AliasFor
-import org.springframework.stereotype.Component
-
-/**
- * 监听器组件注解,组合了 [Component] 的语义。
- * 被标注的类会被组件扫描注册为 Spring Bean,
- * [value] 通过 [AliasFor] 别名到 [Component.value],用于指定 Bean 名称。
- *
- * @property value Bean 名称,默认为空字符串(由 Spring 按类名生成)
- */
-@Component
-annotation class Listener(
- @get:AliasFor(annotation = Component::class)
- val value: String = "",
-)
diff --git a/src/main/kotlin/com/mingliqiye/utils/springboot/autoconfigure/Okhttp3AutoConfiguration.kt b/src/main/kotlin/com/mingliqiye/utils/springboot/autoconfigure/Okhttp3AutoConfiguration.kt
index 7e58ff1..db03d43 100644
--- a/src/main/kotlin/com/mingliqiye/utils/springboot/autoconfigure/Okhttp3AutoConfiguration.kt
+++ b/src/main/kotlin/com/mingliqiye/utils/springboot/autoconfigure/Okhttp3AutoConfiguration.kt
@@ -16,13 +16,14 @@
* ProjectName mingli-utils
* ModuleName mingli-utils.main
* CurrentFile Okhttp3AutoConfiguration.kt
- * LastUpdate 2026-11-16 11:29:35
+ * LastUpdate 2026-11-18 08:22:35
* UpdateUser MingLiPro
*/
package com.mingliqiye.utils.springboot.autoconfigure
import com.mingliqiye.utils.logger.MingLiLoggerFactory
+import com.mingliqiye.utils.springboot.annotation.ContextClosedEventListener
import com.mingliqiye.utils.springboot.autoconfigure.builder.OkhttpBuilder
import org.slf4j.Logger
import org.springframework.beans.factory.ObjectProvider
@@ -31,7 +32,6 @@ import org.springframework.boot.autoconfigure.condition.ConditionalOnClass
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean
import org.springframework.context.annotation.Bean
import org.springframework.context.event.ContextClosedEvent
-import org.springframework.context.event.EventListener
/**
* OkHttp 3 的 Spring Boot 自动配置。
@@ -118,7 +118,7 @@ open class Okhttp3AutoConfiguration {
* 仅当 [okhttp] 字段非空(即客户端由本配置创建)时执行;
* 调用方自行声明的客户端不会被清理。
*/
- @EventListener(ContextClosedEvent::class)
+ @ContextClosedEventListener
open fun handleContextClosed() {
okhttp?.let {
log.info("Context closed, cleaning up OkHttpClient...")
diff --git a/src/main/kotlin/com/mingliqiye/utils/springboot/listener/ApplicationListener.kt b/src/main/kotlin/com/mingliqiye/utils/springboot/listener/ApplicationListener.kt
deleted file mode 100644
index 42ff784..0000000
--- a/src/main/kotlin/com/mingliqiye/utils/springboot/listener/ApplicationListener.kt
+++ /dev/null
@@ -1,132 +0,0 @@
-/*
- * Copyright 2026 mingliqiye
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * ProjectName mingli-utils
- * ModuleName mingli-utils.main
- * CurrentFile ApplicationListener.kt
- * LastUpdate 2026-03-11 08:20:37
- * UpdateUser MingLiPro
- */
-
-package com.mingliqiye.utils.springboot.listener
-
-
-import com.mingliqiye.utils.logger.MingLiLoggerFactory
-import com.mingliqiye.utils.springboot.annotation.ApplicationDestroyedRunner
-import com.mingliqiye.utils.springboot.annotation.ApplicationStartedRunner
-import com.mingliqiye.utils.springboot.annotation.Listener
-import org.springframework.beans.factory.ListableBeanFactory
-import org.springframework.boot.context.event.ApplicationStartedEvent
-import org.springframework.context.event.ContextClosedEvent
-import org.springframework.context.event.EventListener
-
-
-/**
- * 应用生命周期监听器。
- * 在应用启动完成时扫描容器中所有 Bean 的方法,收集标注了
- * [ApplicationStartedRunner] / [ApplicationDestroyedRunner] 的方法并按 order 排序,
- * 分别在 ApplicationStartedEvent 和 ContextClosedEvent 触发时依次反射执行。
- */
-@Listener
-class ApplicationListener {
-
- /**
- * 已扫描到的待执行方法集合,键为注解类全名,值为按 order 升序排列的执行数据列表。
- */
- val runningMap = HashMap