diff --git a/app/runtime/event/binding.py b/app/runtime/event/binding.py index a5ff91fc7..d80026b68 100644 --- a/app/runtime/event/binding.py +++ b/app/runtime/event/binding.py @@ -57,6 +57,12 @@ class EventBindingResolver: return "", names[0] return names[0], names[1] + @staticmethod + def is_class_method_declaration(handler: Callable) -> bool: + """判断处理器是否声明在类体内(限定名含类前缀且非局部闭包)。""" + parts = handler.__qualname__.split(".") + return len(parts) >= 2 and "" not in parts + @staticmethod def owner_class(handler: Callable) -> Optional[Type[Any]]: """从处理器对象本身解析声明类,不按字符串动态导入模块。""" @@ -75,6 +81,14 @@ class EventBindingResolver: return None return owner if isinstance(owner, type) else None + def _record_unresolved(self, identifier: str, reason: str) -> None: + """首次未命中时记录告警,避免重载窗口内重复刷屏。""" + with self._lock: + first_miss = identifier not in self._unresolved + self._unresolved.add(identifier) + if first_miss: + logger.warning(reason, identifier) + def resolve( self, handler: Callable, @@ -87,6 +101,15 @@ class EventBindingResolver: self.parse_handler_names(handler)[1], ) if owner_class is None: + # 插件重载会先清除模块缓存,窗口期内残留的旧类方法声明无法定位声明类; + # 此时直接调用原始函数会绕过实例绑定(旧签名可能与事件调用约定不一致), + # 因此按未绑定处理跳过,等待重载完成后按新 handler 注册自愈。 + if self.is_class_method_declaration(handler): + self._record_unresolved( + EventRegistry.handler_identifier(handler), + "事件处理器所属模块已卸载或声明类不可解析,跳过执行:%s", + ) + return None binding = EventHandlerBinding( instance=None, owner_name=EventRegistry.handler_identifier(handler), @@ -105,15 +128,10 @@ class EventBindingResolver: resolver_name = name break if binding is None: - identifier = EventRegistry.handler_identifier(handler) - with self._lock: - first_miss = identifier not in self._unresolved - self._unresolved.add(identifier) - if first_miss: - logger.warning( - "事件处理器未绑定显式 resolver,已跳过:%s", - identifier, - ) + self._record_unresolved( + EventRegistry.handler_identifier(handler), + "事件处理器未绑定显式 resolver,已跳过:%s", + ) return None logger.debug( "事件处理器绑定:%s -> %s", diff --git a/tests/test_event_runtime_components.py b/tests/test_event_runtime_components.py index 72c47195a..ea087437a 100644 --- a/tests/test_event_runtime_components.py +++ b/tests/test_event_runtime_components.py @@ -1,6 +1,8 @@ """事件注册、绑定、调度和错误策略组件的独立测试。""" +import sys import threading +import types from unittest.mock import Mock from app.runtime.event.binding import ( @@ -26,6 +28,10 @@ class _UnmanagedHandler: """提供可解析的实例方法声明。""" +def _free_function_handler(_event: Event) -> None: + """模块级自由函数处理器,用于验证直调路径保持不变。""" + + def test_binding_miss_does_not_construct_handler_owner() -> None: """resolver 未命中时只记录诊断,不能调用 owner_class()。""" resolvers = {} @@ -42,6 +48,53 @@ def test_binding_miss_does_not_construct_handler_owner() -> None: ) +def test_unloaded_module_class_handler_is_skipped() -> None: + """模块缓存被清除后,残留的类方法声明必须跳过而非直调原始函数。""" + fake_name = "tests._fake_unloaded_plugin" + fake_module = types.ModuleType(fake_name) + sys.modules[fake_name] = fake_module + try: + # 在伪模块命名空间内构造类,使处理器 __module__ 指向该模块 + exec( + "class _ResidualPlugin:\n" + " def reload(self, event):\n" + " raise AssertionError('residual handler must not run')\n", + fake_module.__dict__, + ) + residual_handler = fake_module._ResidualPlugin.reload + # 模拟插件重载 stop 阶段清除模块缓存后的残留注册 + del sys.modules[fake_name] + + binding = EventBindingResolver( + lock=threading.Lock(), + resolvers=lambda: {}, + ) + assert binding.resolve(residual_handler) is None + # 模块卸载后 identifier 回退为 unknown_module 前缀,与线上日志一致 + assert binding.unresolved_handlers() == ( + "unknown_module._ResidualPlugin.reload", + ) + finally: + sys.modules.pop(fake_name, None) + + +def test_free_function_handler_still_invoked_directly() -> None: + """自由函数处理器不属于类声明,保持直调路径不被新跳过逻辑影响。""" + binding = EventBindingResolver( + lock=threading.Lock(), + resolvers=lambda: {}, + ) + + resolved = binding.resolve(_free_function_handler) + + assert resolved is not None + method, handler_binding, class_name, method_name = resolved + assert method is _free_function_handler + assert handler_binding.run_sync_in_threadpool is True + assert class_name == "" + assert method_name == "_free_function_handler" + + def test_binding_uses_explicit_resolver_instance() -> None: """显式 resolver 应返回当前托管实例上的绑定方法。""" instance = object.__new__(_UnmanagedHandler)