feat: add opt-in MonoBehaviour lifecycle weaving

2026-08-28 04:31:00 +08:00
parent cdd9dbdb73
commit 7838d37f06
6 changed files with 361 additions and 3 deletions
@@ -2,6 +2,13 @@

 本文件记录 `ShrinkEventBus` 在当前工作区中的包内变更。

+## [2.0.1] - 2026-08-28
+
+### Added
+
+- `ShrinkEventSubscriberAttribute` 新增显式 `Lifetime`，选择 `AwakeToDestroy` 的 `MonoBehaviour` 会由 ILPostProcessor 在编译期织入生成绑定的 `Attach` 与 `Dispose`，禁用对象时保持订阅，销毁时自动释放。
+- 自动生命周期支持已有或缺失的 `Awake` / `OnDestroy`，并保留可重写基类生命周期调用；默认仍为 `Manual`，避免既有 2.0 使用方升级后重复订阅。
+
 ## [2.0.0] - 2026-08-23

 ### Added
@@ -43,12 +43,25 @@ namespace ShrinkEventBus.CodeGen
                    return GetResult(assemblyDefinition, diagnostics);

                foreach (var type in GetAllTypes(module.Types)
-                             .Where(type => !type.IsInterface && !type.IsAbstract)
+                             .Where(type => !type.IsInterface)
                             .Where(type => HasAttribute(type, generatedSubscriberType))
                             .Where(type => type.Methods.Any(method =>
                                 !method.IsStatic && HasAttribute(method, generatedSubscribeType))))
                {
+                    var subscriberAttribute = type.CustomAttributes.First(attribute =>
+                        attribute.AttributeType.FullName == generatedSubscriberType.FullName);
                    InjectGeneratedBinding(type, module, generatedSubscribeType);
+                    switch (ReadIntProperty(subscriberAttribute, "Lifetime", 0))
+                    {
+                        case 0:
+                            break;
+                        case 1:
+                            InjectAwakeToDestroyLifetime(type, module);
+                            break;
+                        default:
+                            throw new InvalidOperationException(
+                                $"Unsupported ShrinkSubscriberLifetime on {type.FullName}.");
+                    }
                }

                var staticSubscriberTypes = GetAllTypes(module.Types)
@@ -176,6 +189,244 @@ namespace ShrinkEventBus.CodeGen
            type.Methods.Add(generatedMethod);
        }

+        private static void InjectAwakeToDestroyLifetime(TypeDefinition type, ModuleDefinition module)
+        {
+            if (!InheritsFrom(type, "UnityEngine.MonoBehaviour"))
+            {
+                throw new InvalidOperationException(
+                    $"[ShrinkEventSubscriber(Lifetime = AwakeToDestroy)] requires MonoBehaviour: {type.FullName}.");
+            }
+
+            const string bindingFieldName = "__shrinkEventBusAwakeToDestroyBinding";
+            if (type.Fields.Any(field => field.Name == bindingFieldName))
+            {
+                throw new InvalidOperationException(
+                    $"Reserved generated field already exists on {type.FullName}: {bindingFieldName}.");
+            }
+
+            var disposableType = module.ImportReference(typeof(IDisposable));
+            var bindingField = new FieldDefinition(bindingFieldName,
+                FieldAttributes.Private, disposableType);
+            type.Fields.Add(bindingField);
+
+            var eventBusType = FindType(module, "ShrinkEventBus.EventBus", RuntimeAssemblyName)
+                ?? throw new InvalidOperationException("EventBus was not found.");
+            var eventBusDefinition = eventBusType.Resolve()
+                ?? throw new InvalidOperationException("EventBus could not be resolved.");
+            var attachMethod = module.ImportReference(eventBusDefinition.Methods.Single(method =>
+                method.Name == "Attach" && method.IsStatic && method.Parameters.Count == 2));
+            var disposeMethod = module.ImportReference(typeof(IDisposable).GetMethod(nameof(IDisposable.Dispose))
+                ?? throw new InvalidOperationException("IDisposable.Dispose was not found."));
+
+            InjectAwake(type, module, bindingField, attachMethod);
+            InjectOnDestroy(type, module, bindingField, disposeMethod);
+        }
+
+        private static void InjectAwake(TypeDefinition type, ModuleDefinition module,
+            FieldDefinition bindingField, MethodReference attachMethod)
+        {
+            var awake = type.Methods.FirstOrDefault(method =>
+                method.Name == "Awake" && !method.IsStatic && method.Parameters.Count == 0);
+            if (awake != null)
+            {
+                InsertAttachAtStart(awake, module, bindingField, attachMethod);
+                return;
+            }
+
+            var baseAwake = FindBaseMethodReference(type, "Awake", module);
+            awake = new MethodDefinition("Awake",
+                baseAwake != null
+                    ? MethodAttributes.Family | MethodAttributes.HideBySig | MethodAttributes.Virtual
+                    : MethodAttributes.Family | MethodAttributes.HideBySig | MethodAttributes.Virtual |
+                      MethodAttributes.NewSlot,
+                module.TypeSystem.Void);
+            awake.Body.InitLocals = true;
+            var il = awake.Body.GetILProcessor();
+            if (baseAwake != null)
+            {
+                il.Emit(OpCodes.Ldarg_0);
+                il.Emit(OpCodes.Call, baseAwake);
+            }
+            EmitAttach(il, awake, module, bindingField, attachMethod);
+            il.Emit(OpCodes.Ret);
+            type.Methods.Add(awake);
+        }
+
+        private static void InjectOnDestroy(TypeDefinition type, ModuleDefinition module,
+            FieldDefinition bindingField, MethodReference disposeMethod)
+        {
+            var onDestroy = type.Methods.FirstOrDefault(method =>
+                method.Name == "OnDestroy" && !method.IsStatic && method.Parameters.Count == 0);
+            if (onDestroy != null)
+            {
+                InsertDisposeAtStart(onDestroy, bindingField, disposeMethod);
+                return;
+            }
+
+            var baseOnDestroy = FindBaseMethodReference(type, "OnDestroy", module);
+            onDestroy = new MethodDefinition("OnDestroy",
+                baseOnDestroy != null
+                    ? MethodAttributes.Family | MethodAttributes.HideBySig | MethodAttributes.Virtual
+                    : MethodAttributes.Family | MethodAttributes.HideBySig | MethodAttributes.Virtual |
+                      MethodAttributes.NewSlot,
+                module.TypeSystem.Void);
+            var il = onDestroy.Body.GetILProcessor();
+            EmitDispose(il, bindingField, disposeMethod);
+            if (baseOnDestroy != null)
+            {
+                il.Emit(OpCodes.Ldarg_0);
+                il.Emit(OpCodes.Call, baseOnDestroy);
+            }
+            il.Emit(OpCodes.Ret);
+            type.Methods.Add(onDestroy);
+        }
+
+        private static void InsertAttachAtStart(MethodDefinition method, ModuleDefinition module,
+            FieldDefinition bindingField, MethodReference attachMethod)
+        {
+            if (!method.HasBody || method.Body.Instructions.Count == 0)
+                throw new InvalidOperationException($"Awake has no body: {method.FullName}.");
+
+            method.Body.InitLocals = true;
+            var processor = method.Body.GetILProcessor();
+            var instructions = BuildAttachInstructions(processor, method, module, bindingField, attachMethod);
+            var first = method.Body.Instructions[0];
+            foreach (var instruction in instructions)
+                processor.InsertBefore(first, instruction);
+        }
+
+        private static void EmitAttach(ILProcessor il, MethodDefinition method, ModuleDefinition module,
+            FieldDefinition bindingField, MethodReference attachMethod)
+        {
+            foreach (var instruction in BuildAttachInstructions(il, method, module, bindingField, attachMethod))
+                il.Append(instruction);
+        }
+
+        private static IReadOnlyList<Instruction> BuildAttachInstructions(ILProcessor il,
+            MethodDefinition method, ModuleDefinition module, FieldDefinition bindingField,
+            MethodReference attachMethod)
+        {
+            var defaultBusType = module.ImportReference(attachMethod.Parameters[1].ParameterType);
+            var defaultBus = new VariableDefinition(defaultBusType);
+            method.Body.Variables.Add(defaultBus);
+            var attached = il.Create(OpCodes.Nop);
+            return new[]
+            {
+                il.Create(OpCodes.Ldarg_0),
+                il.Create(OpCodes.Ldfld, bindingField),
+                il.Create(OpCodes.Brtrue_S, attached),
+                il.Create(OpCodes.Ldarg_0),
+                il.Create(OpCodes.Ldarg_0),
+                il.Create(OpCodes.Ldloca_S, defaultBus),
+                il.Create(OpCodes.Initobj, defaultBusType),
+                il.Create(OpCodes.Ldloc, defaultBus),
+                il.Create(OpCodes.Call, attachMethod),
+                il.Create(OpCodes.Stfld, bindingField),
+                attached
+            };
+        }
+
+        private static void InsertDisposeAtStart(MethodDefinition method,
+            FieldDefinition bindingField, MethodReference disposeMethod)
+        {
+            if (!method.HasBody || method.Body.Instructions.Count == 0)
+                throw new InvalidOperationException($"OnDestroy has no body: {method.FullName}.");
+
+            var processor = method.Body.GetILProcessor();
+            var instructions = BuildDisposeInstructions(processor, bindingField, disposeMethod);
+            var first = method.Body.Instructions[0];
+            foreach (var instruction in instructions)
+                processor.InsertBefore(first, instruction);
+        }
+
+        private static void EmitDispose(ILProcessor il, FieldDefinition bindingField,
+            MethodReference disposeMethod)
+        {
+            foreach (var instruction in BuildDisposeInstructions(il, bindingField, disposeMethod))
+                il.Append(instruction);
+        }
+
+        private static IReadOnlyList<Instruction> BuildDisposeInstructions(ILProcessor il,
+            FieldDefinition bindingField, MethodReference disposeMethod)
+        {
+            var disposed = il.Create(OpCodes.Nop);
+            return new[]
+            {
+                il.Create(OpCodes.Ldarg_0),
+                il.Create(OpCodes.Ldfld, bindingField),
+                il.Create(OpCodes.Brfalse_S, disposed),
+                il.Create(OpCodes.Ldarg_0),
+                il.Create(OpCodes.Ldfld, bindingField),
+                il.Create(OpCodes.Callvirt, disposeMethod),
+                il.Create(OpCodes.Ldarg_0),
+                il.Create(OpCodes.Ldnull),
+                il.Create(OpCodes.Stfld, bindingField),
+                disposed
+            };
+        }
+
+        private static MethodReference? FindBaseMethodReference(TypeDefinition type,
+            string methodName, ModuleDefinition module)
+        {
+            try
+            {
+                var baseTypeReference = type.BaseType;
+                while (baseTypeReference != null)
+                {
+                    var baseType = baseTypeReference.Resolve();
+                    if (baseType == null)
+                        break;
+
+                    var method = baseType.Methods.FirstOrDefault(candidate =>
+                        candidate.Name == methodName && !candidate.IsStatic && candidate.IsVirtual &&
+                        candidate.Parameters.Count == 0);
+                    if (method != null)
+                    {
+                        if (baseTypeReference is GenericInstanceType genericBase)
+                        {
+                            var methodReference = new MethodReference(method.Name,
+                                module.ImportReference(method.ReturnType), module.ImportReference(genericBase))
+                            {
+                                HasThis = method.HasThis,
+                                ExplicitThis = method.ExplicitThis,
+                                CallingConvention = method.CallingConvention
+                            };
+                            return methodReference;
+                        }
+
+                        return module.ImportReference(method);
+                    }
+
+                    baseTypeReference = baseType.BaseType;
+                }
+            }
+            catch
+            {
+            }
+
+            return null;
+        }
+
+        private static bool InheritsFrom(TypeDefinition type, string expectedFullName)
+        {
+            var current = type.BaseType;
+            while (current != null)
+            {
+                if (current.FullName == expectedFullName)
+                    return true;
+                try
+                {
+                    current = current.Resolve()?.BaseType;
+                }
+                catch
+                {
+                    return false;
+                }
+            }
+
+            return false;
+        }
+
        private static void EmitGeneratedSubscription(ILProcessor il, ModuleDefinition module,
            TypeDefinition ownerType, MethodDefinition handler, CustomAttribute attribute,
            string classDefaultBus, VariableDefinition bindingLocal, MethodReference bindingAdd,
@@ -80,7 +80,18 @@ Bus 解析顺序：方法 `Bus`、类型 `DefaultBus`、`Attach` 传入默认 Bu
 using var binding = EventBus.Attach(new PlayerHandlers());
 ```

-MonoBehaviour 不需要继承 SDK 基类。可自行在 `OnEnable/OnDisable` 中 Attach/Dispose，也可以在 GameObject 上添加 `ShrinkMonoEventScope`，由它统一绑定同对象或子层级中的生成 subscriber。
+MonoBehaviour 不需要继承 SDK 基类。需要从 `Awake` 持续订阅到 `OnDestroy` 时，可以显式选择编译期生命周期织入：
+
+```csharp
+[ShrinkEventSubscriber(Lifetime = ShrinkSubscriberLifetime.AwakeToDestroy)]
+public sealed class PlayerHandlers : MonoBehaviour
+{
+    [ShrinkSubscribe]
+    private void OnJoined(PlayerJoinedEvent value) { }
+}
+```
+
+默认 `Lifetime` 为 `Manual`，普通对象与由 Context、Scene 或 Mod 宿主管理的实例继续自行持有 `EventBus.Attach(...)` 返回的绑定。需要随启用状态反复订阅的 MonoBehaviour 可以自行在 `OnEnable/OnDisable` 中 Attach/Dispose，也可以在 GameObject 上添加 `ShrinkMonoEventScope`，由它统一绑定同对象或子层级中的生成 subscriber。

 静态类型同样只使用特性：

@@ -2,11 +2,18 @@ using System;

 namespace ShrinkEventBus
 {
+    public enum ShrinkSubscriberLifetime
+    {
+        Manual = 0,
+        AwakeToDestroy = 1
+    }
+
    [AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = false)]
    public sealed class ShrinkEventSubscriberAttribute : Attribute
    {
        public string OwnerId { get; set; } = string.Empty;
        public string DefaultBus { get; set; } = string.Empty;
+        public ShrinkSubscriberLifetime Lifetime { get; set; } = ShrinkSubscriberLifetime.Manual;
    }

    [AttributeUsage(AttributeTargets.Method, Inherited = false, AllowMultiple = false)]
@@ -14,6 +14,41 @@ namespace ShrinkEventBus.PlayMode.Tests
        public int Value { get; }
    }

+    internal readonly struct AwakeToDestroyEvent : IShrinkEvent
+    {
+        public AwakeToDestroyEvent(int value) => Value = value;
+        public int Value { get; }
+    }
+
+    [ShrinkEventSubscriber(
+        DefaultBus = "game",
+        Lifetime = ShrinkSubscriberLifetime.AwakeToDestroy)]
+    internal sealed class AwakeToDestroyTarget : MonoBehaviour
+    {
+        public static int Sum { get; set; }
+        public static int AwakeCalls { get; set; }
+        public static int DestroyCalls { get; set; }
+
+        private void Awake() => AwakeCalls++;
+        private void OnDestroy() => DestroyCalls++;
+
+        [ShrinkSubscribe]
+        private void OnEvent(AwakeToDestroyEvent value) => Sum += value.Value;
+    }
+
+    [ShrinkEventSubscriber(Lifetime = ShrinkSubscriberLifetime.AwakeToDestroy)]
+    internal abstract class AbstractAwakeToDestroyTarget : MonoBehaviour
+    {
+        public static int Sum { get; set; }
+
+        [ShrinkSubscribe]
+        private void OnEvent(AwakeToDestroyEvent value) => Sum += value.Value;
+    }
+
+    internal sealed class ConcreteAwakeToDestroyTarget : AbstractAwakeToDestroyTarget
+    {
+    }
+
    [ShrinkEventSubscriber(DefaultBus = "game")]
    internal sealed class MonoLifecycleTarget : MonoBehaviour
    {
@@ -25,6 +60,53 @@ namespace ShrinkEventBus.PlayMode.Tests

    public sealed class ShrinkMonoEventScopePlayModeTests
    {
+        [UnityTest]
+        public IEnumerator AwakeToDestroyLifetimeIsInjectedWithoutManualBinding()
+        {
+            AwakeToDestroyTarget.Sum = 0;
+            AwakeToDestroyTarget.AwakeCalls = 0;
+            AwakeToDestroyTarget.DestroyCalls = 0;
+            var gameObject = new GameObject("ShrinkEventBus-AwakeToDestroy");
+            var target = gameObject.AddComponent<AwakeToDestroyTarget>();
+
+            yield return null;
+            Assert.IsInstanceOf<IShrinkGeneratedSubscriber>(target);
+            Assert.AreEqual(1, AwakeToDestroyTarget.AwakeCalls);
+            yield return EventBus.PostAsync(new AwakeToDestroyEvent(3)).ToCoroutine();
+            Assert.AreEqual(3, AwakeToDestroyTarget.Sum);
+
+            gameObject.SetActive(false);
+            yield return null;
+            yield return EventBus.PostAsync(new AwakeToDestroyEvent(5)).ToCoroutine();
+            Assert.AreEqual(8, AwakeToDestroyTarget.Sum,
+                "AwakeToDestroy subscriptions must survive OnDisable.");
+
+            Object.Destroy(gameObject);
+            yield return null;
+            Assert.AreEqual(1, AwakeToDestroyTarget.DestroyCalls);
+            yield return EventBus.PostAsync(new AwakeToDestroyEvent(7)).ToCoroutine();
+            Assert.AreEqual(8, AwakeToDestroyTarget.Sum,
+                "The generated OnDestroy release must remove the subscription.");
+        }
+
+        [UnityTest]
+        public IEnumerator AwakeToDestroyLifetimeSupportsAbstractSubscriberBasesWithoutLifecycleMethods()
+        {
+            AbstractAwakeToDestroyTarget.Sum = 0;
+            var gameObject = new GameObject("ShrinkEventBus-AbstractAwakeToDestroy");
+            var target = gameObject.AddComponent<ConcreteAwakeToDestroyTarget>();
+
+            yield return null;
+            Assert.IsInstanceOf<IShrinkGeneratedSubscriber>(target);
+            yield return EventBus.PostAsync(new AwakeToDestroyEvent(11)).ToCoroutine();
+            Assert.AreEqual(11, AbstractAwakeToDestroyTarget.Sum);
+
+            Object.Destroy(gameObject);
+            yield return null;
+            yield return EventBus.PostAsync(new AwakeToDestroyEvent(13)).ToCoroutine();
+            Assert.AreEqual(11, AbstractAwakeToDestroyTarget.Sum);
+        }
+
        [UnityTest]
        public IEnumerator OnEnableAttachesAndOnDisableReleases()
        {
@@ -1,6 +1,6 @@
 {
  "name": "com.cneicy.shrink-eventbus",
-  "version": "2.0.0",
+  "version": "2.0.1",
  "displayName": "ShrinkEventBus",
  "description": "多 Bus、特性强类型注册、UniTask 调度与低分配发布的 Unity 事件总线。",
  "unity": "2022.3",