Listener
标记一个函数为监听器/监听函数,并尝试自动检测其监听类型。
当标记在一个函数上的时候,应当提供至多一个事件类型的参数作为你需要监听的事件类型。eg:
@Listener
suspend fun ChannelMessageEvent.myListener() { ... }
默认情况下,此函数的ID为其全限定名,你可以通过 @Listener(id="...") 指定一个ID。 当不指定的时候默认为当前标记对象的全限定二进制名称或随机UUID字符串。
在 Boot相关模块下,@Listener 会检测标记函数的返回值类型。如果返回值类型为 EventListenerBuilder 或者 EventListener, 则会将当前函数会直接被当作为一个需要注册的bean,而不再解析为一个函数式的监听函数。
以Spring环境下为例,上述情况的函数将会被视作一个 Spring Bean 出处理,相当于标记了 @Bean, 并不会再作为监听函数注册。
需要注意的是,如果作为一个 EventListenerBuilder 或 EventListener Bean 注册的话,被标记函数不可为挂起函数。
@Component
class Foo {
@Listener
suspend fun EventProcessingContext.listener(event: FooEvent) {
// 此函数为普通的监听函数
// 可以使用挂起函数
}
@Listener
fun fooListenerBuilder(): EventListenerBuilder {
// 此函数的返回值会作为Bean注册,不会被作为监听函数。
// 不可使用挂起函数
return ...
}
@Listener
fun fooListenerBuilder() = buildSimpleListener(FooEvent) {
// 此函数的返回值会作为Bean注册,不会被作为监听函数。
// 不可使用挂起函数
id = "..."
match { condition1 }
match { condition2 }
handle {
// ...
EventResult.defaults()
}
}
@Bean
fun barListenerBuilder(): EventListenerBuilder {
// 更推荐养成使用明确区分二者注解的标准写法的习惯。
// 不可使用挂起函数
return ...
}
@Bean
fun barListener(): EventListener {
// 更推荐养成使用明确区分二者注解的标准写法的习惯。
// 不可使用挂起函数
return ...
}
}
当通过直接返回 EventListener 或者 EventListenerBuilder 的形式注册监听函数的时候,@Listener 将仅作为标记用, 其中的所有参数( 例如 id 、async)都将无效。
⚠️注意: 与在 spring 环境下不同,在 boot 模块中支持通过 @Listener 注册一个 EventListenerBuilder 或 EventListener, 但是不支持这个被标记的函数存在参数。这也是为什么建议在任何环境下都使用明确的注解: 如果是注册 EventListenerBuilder 或 EventListener,最好使用明确的 @Beans
或者 @Bean
, 而不是统一使用 @Listener。
Parameters
监听函数ID。
此事件的优先级。
此函数是否为异步函数。 如果为 object
类型,则会直接获取实例,否则会尝试通过可用途径获取对应结果。