五件事，五种责任

自动注册不是黑箱，接口也不是装饰。

新版 Core 的关键不是“多加几个抽象”，而是把 Unity 项目最容易失控的五件事拆成五种机制：自动注册只减少装配代码，构造注入暴露依赖，能力接口限制职责，Scope 管生命周期，诊断图让自动化可见。

自动注册解决少写装配代码

只在模块内部自动化，不做全项目黑箱扫描。

构造注入解决依赖清晰

业务类真实依赖必须出现在构造函数里。

能力接口解决职责权限

像 QFramework 一样，用接口限制“对象能做什么”。

Scope 解决生命周期

Root、Stage、Feature 各自创建和释放自己的对象。

诊断图解决自动注册不黑箱

启动时输出注册表、依赖图、生命周期归属。

核心思想

最新版不应该只是“一堆模块手动装起来”。它的全局概念是消费侧的 GameComposition，框架只把这份配方变成可运行、可诊断、可释放的 FlowScopeRuntime。

概念	是谁拥有	负责什么	不负责什么
GameComposition	消费侧	声明项目用了哪些模块、项目服务、首个 Feature、启动前置条件。	不执行 Feature 生命周期，不释放资源。
CompositionBuilder	框架提供，消费侧调用	收集模块安装、服务注册、自动扫描规则和诊断信息。	不决定项目业务启动顺序。
FlowScopeRuntime	框架创建，消费侧持有	持有 RootScope、FeatureHost、Diagnostics，作为运行时总句柄。	不变成全能 GContext，不允许业务随便从它 Resolve 一切。
FeatureHost	框架	执行 Feature 切换、Scope 创建、生命周期和失败清理。	不写业务逻辑，不决定首个 Feature 是谁。

所以它不是回到 AppKernel 接管一切，也不是散装 Bootstrap。消费侧用一个 CompositionRoot 声明全局结构；框架把这份声明转成 Runtime，并保证依赖、权限、生命周期和诊断。

五条约束

它们不是并列名词，而是一条链。少写注册不等于隐藏依赖；自动化越多，诊断越要硬。

自动注册

目标是少写重复装配代码。它只能在模块边界内工作，必须有 Marker、生命周期声明和诊断输出。

构造注入

目标是让依赖可读、可测、可替换。不要把自动注册变成业务代码到处 Resolve。

能力接口

目标是限制职责权限。对象实现什么能力，才获得什么扩展方法；接口必须能复用。

Scope

目标是明确谁拥有对象、谁释放对象。Feature 临时对象不能留在 Root。

诊断图

目标是让自动注册可审查。启动时能看见每个服务来自哪个模块、依赖谁、生命周期是什么。

install 显式安装模块

消费侧知道装了哪些模块，不让框架猜启动顺序。

scan 模块内自动注册

扫描本模块 Assembly 和 Marker，减少重复注册。

inject 构造函数声明依赖

类依赖在类型定义处暴露，不靠内部 Resolve。

scope 进入 FeatureScope

资源、订阅、临时状态进入本次 Feature 生命周期。

report 输出诊断图

自动化结果可见，启动失败能定位到模块和依赖链。

消费侧用法

消费侧仍然保留 CompositionRoot，但不再把注册散落在 MonoBehaviour 里。项目写一份 GameComposition，Bootstrap 只负责构建 Runtime 和进入首个 Feature。

GameBootstrap 干净入口

public sealed class GameBootstrap : MonoBehaviour
{
    private FlowScopeRuntime _runtime;

    private async void Start()
    {
        var composition = new FishingGameComposition(
            addressablesBackend,
            uiRoot,
            savePath);

        _runtime = FlowScopeRuntime.Build(composition);

        await _runtime.Features.SwitchAsync<MainMenuFeature>(
            FeatureSwitchRequest.Replace(),
            destroyCancellationToken);
    }

    private async void OnDestroy()
    {
        if (_runtime != null)
            await _runtime.DisposeAsync();
    }
}

FishingGameComposition 消费侧全局配方

public sealed class FishingGameComposition : IGameComposition
{
    private readonly IResourceBackend _resourceBackend;
    private readonly Transform _uiRoot;
    private readonly string _savePath;

    public FishingGameComposition(
        IResourceBackend resourceBackend,
        Transform uiRoot,
        string savePath)
    {
        _resourceBackend = resourceBackend;
        _uiRoot = uiRoot;
        _savePath = savePath;
    }

    public void Configure(ICompositionBuilder app)
    {
        app.UseRoot(new ServiceContainer());

        app.Install(new ResourceModule(_resourceBackend));
        app.Install(new UIModule(_uiRoot));
        app.Install(new SaveModule(_savePath));
        app.Install(new FishingModule());

        app.Services.RegisterInstance<IPlayerData>(new PlayerData());
        app.Services.RegisterFactory<IFishingApi>(
            s => new FishingApi());

        app.Features.UseDefaultSwitchPolicy(FeatureSwitchPolicy.ReplaceOnly);
    }
}

代码实现预览

下面不是完整实现，而是接口和关键路径预览。重点是职责分离：自动注册、依赖、权限、生命周期、诊断各管一件事。

组合根契约 全局概念，不接管启动

public interface IGameComposition
{
    void Configure(ICompositionBuilder app);
}

public interface ICompositionBuilder
{
    IServiceRegistry Services { get; }
    IFeatureRegistry Features { get; }
    IDiagnosticOptions Diagnostics { get; }

    void UseRoot(IServiceScope root);
    void Install(IModule module);
}

public sealed class FlowScopeRuntime : IAsyncDisposable
{
    public IServiceScope Root { get; }
    public IFeatureHost Features { get; }
    public IDependencyDiagnostics Diagnostics { get; }

    public static FlowScopeRuntime Build(IGameComposition composition)
    {
        var builder = new CompositionBuilder();
        composition.Configure(builder);
        return builder.BuildRuntime();
    }
}

自动注册契约 少写装配代码

public enum ServiceLifetime
{
    Root,
    Stage,
    Feature
}

[AttributeUsage(AttributeTargets.Class)]
public sealed class FeatureServiceAttribute : Attribute
{
    public ServiceLifetime Lifetime { get; }

    public FeatureServiceAttribute(
        ServiceLifetime lifetime = ServiceLifetime.Feature)
    {
        Lifetime = lifetime;
    }
}

public interface IModule
{
    void Install(IServiceRegistry services);
}

public interface IServiceRegistry
{
    void RegisterInstance<T>(T instance);
    void RegisterFactory<T>(Func<IServiceProvider, T> factory);
    IModuleScanBuilder Scan(Assembly assembly);
}

构造注入 依赖清晰

public sealed class StartFishingUseCase
{
    private readonly IFishingSession _session;
    private readonly IPlayerWallet _wallet;
    private readonly IFeatureNavigator _navigator;

    public StartFishingUseCase(
        IFishingSession session,
        IPlayerWallet wallet,
        IFeatureNavigator navigator)
    {
        _session = session;
        _wallet = wallet;
        _navigator = navigator;
    }

    public async ValueTask ExecuteAsync(CancellationToken ct)
    {
        if (!_wallet.CanPay(_session.EntryCost))
            return;

        await _navigator.SwitchAsync<FishingFeature>(
            FeatureSwitchRequest.Replace(), ct);
    }
}

能力接口 职责权限

public interface IFeatureContext
{
    IServiceProvider Services { get; }
    IFeatureLifetime Lifetime { get; }
    IResourceGroup Resources { get; }
    CancellationToken CancellationToken { get; }
}

public interface INavigableFeatureContext : IFeatureContext
{
    IFeatureNavigator Navigator { get; }
}

public interface IHasFeatureContext<out TContext>
    where TContext : IFeatureContext
{
    TContext Context { get; }
}

public interface ICanUseResources :
    IHasFeatureContext<IFeatureContext> {}

public interface ICanRequestNavigation :
    IHasFeatureContext<INavigableFeatureContext> {}

能力扩展方法 接口必须能复用

public static class FeatureCapabilityExtensions
{
    public static ValueTask<IResourceHandle<T>>
        LoadOwnedAsync<T>(
            this ICanUseResources self,
            string key)
        where T : class
    {
        return self.Context.Resources.LoadAsync<T>(
            key,
            self.Context.CancellationToken);
    }

    public static ValueTask SwitchToAsync<TFeature>(
        this ICanRequestNavigation self,
        FeatureSwitchRequest request)
        where TFeature : IFeature
    {
        return self.Context.Navigator.SwitchAsync<TFeature>(
            request,
            self.Context.CancellationToken);
    }
}

FeatureHost Scope 管生命周期

public sealed class FeatureHost : IFeatureHost
{
    private readonly IServiceScope _root;
    private ActiveFeature _active;

    public async ValueTask SwitchAsync<TFeature>(
        FeatureSwitchRequest request,
        CancellationToken ct)
        where TFeature : IFeature
    {
        if (_active != null)
            await _active.ExitAndDisposeAsync(ct);

        var scope = _root.CreateScope();
        var lifetime = new FeatureLifetime();
        var resources = scope.GetRequiredService<IResourceService>()
            .CreateGroup();

        var context = new FeatureContext(
            scope, lifetime, resources, ct, request.Args);

        var feature = scope.GetRequiredService<TFeature>();
        await feature.LoadAsync(context);
        await feature.EnterAsync(context);

        _active = new ActiveFeature(feature, context, scope);
    }
}

Feature 示例 能力接口实际用法

public sealed class MainMenuFeature :
    IFeature,
    ICanUseResources,
    ICanRequestNavigation
{
    public INavigableFeatureContext Context { get; private set; }
    IFeatureContext IHasFeatureContext<IFeatureContext>.Context
        => Context;

    public async ValueTask LoadAsync(IFeatureContext context)
    {
        Context = (INavigableFeatureContext)context;

        var panel = await this.LoadOwnedAsync<GameObject>(
            "UI/MainMenuPanel");

        Context.Lifetime.Add(panel);
    }

    public ValueTask EnterAsync(IFeatureContext context)
        => ValueTask.CompletedTask;

    public ValueTask ExitAsync(IFeatureContext context)
        => ValueTask.CompletedTask;
}

这里的能力接口只建议给 Feature、GameAct 这类框架生命周期对象使用。 UseCase、Command、ViewModel 不应该为了拿框架能力而实现一堆接口，它们更适合构造注入业务 Port。

诊断图

自动注册必须能回答三个问题：谁注册了它，它依赖谁，它属于哪个生命周期。

诊断接口 自动注册不黑箱

public interface IDependencyDiagnostics
{
    RegistrationReport BuildRegistrationReport();
    DependencyGraph BuildDependencyGraph(Type rootType);
}

public sealed record ServiceRegistration(
    Type ServiceType,
    Type ImplementationType,
    ServiceLifetime Lifetime,
    string ModuleName,
    IReadOnlyList<Type> Dependencies);

public sealed record RegistrationReport(
    IReadOnlyList<ServiceRegistration> Services,
    IReadOnlyList<string> Warnings);

输出示例 给团队看的报告

FishingModule
  IFishingSession -> FishingSession [Feature]
    depends on:
      IPlayerData
      IFishingApi

  IFishingEconomy -> FishingEconomy [Feature]
    depends on:
      IPlayerWallet
      Tables

MainMenuFeature
  depends on:
    IUIService
    IResourceService
    IFeatureNavigator

Warnings
  EventScratchPanel resolves PlayerData from RootScope.
  ScratchTicketManager registered as Root but implements IDisposable.

边界规则

这套设计不是“自动注册万能”，也不是“能力接口万能”。每种机制只解决一个问题。

机制	负责	不负责	容易误用
自动注册	减少重复装配代码。	不负责说明业务依赖。	扫全项目、无 Marker、无生命周期、无诊断。
构造注入	暴露类的真实依赖。	不负责减少注册代码。	构造函数塞进万能 Context 或 IServiceProvider。
能力接口	限制对象能做什么。	不负责业务依赖注入。	让所有业务对象都实现框架接口。
Scope	创建、隔离、释放生命周期对象。	不负责业务分层。	Feature 临时对象注册到 Root。
诊断图	让自动注册结果可见。	不替代架构边界。	只在出错时打印，不在启动报告里展示。

方案	消费侧感觉	好处	缺点
旧 GContext	全局入口很方便，哪里都能 Resolve 和 Publish。	接入快，适合业务快速堆功能。	依赖隐藏、生命周期不清、事件命令混用、自动发现难追踪。
散装 Bootstrap	消费侧能控制所有细节，但代码像一堆 new 和 Register。	启动顺序清楚，没有框架抢主控权。	缺少全局配方概念，项目越大越像脚本清单。
新版 GameComposition	消费侧声明一份项目配方，Bootstrap 只 Build Runtime。	既有全局概念，又不接管 App 启动；模块显式，模块内自动；可输出诊断图。	需要维护 Composition 规范；小项目会觉得比直接 new 多一层；Builder API 设计不好会变成新 DSL 负担。

GameComposition 成本	具体是什么意思	什么时候会出问题	规避方式
维护 Composition 规范	团队必须约定哪些东西写在 Composition，哪些东西写在 Module，哪些东西留在 Feature 内部。	如果所有人都往 Composition 塞注册、初始化、业务判断，它会变成新的总控脚本。	Composition 只声明结构：安装模块、注册项目级服务、选择策略；业务初始化放 Feature 或项目 Bootstrap 步骤。
小项目多一层	只有一个场景、几个服务、没有复杂 Feature 切换时，GameComposition 会显得比直接 new 多绕一步。	原型项目、Game Jam、小 Demo、一次性工具页面，会被框架流程拖慢。	提供 SimpleBootstrap 模式：允许直接 new ServiceContainer + FeatureHost；GameComposition 作为推荐，不作为强制。
Builder API 变 DSL 负担	如果 Builder 做太多语法糖，开发者需要学习一套框架专用语言，而不是普通 C#。	出现大量 `UseX().WithY().ForZ().When(...)` 链式调用，真实执行顺序反而不清楚。	Builder 只保留少量动词：`UseRoot`、`Install`、`Register`、`UsePolicy`、`EnableDiagnostics`。复杂逻辑回到普通 C#。

判断 GameComposition 是否值得引入，看项目是不是已经有跨模块服务、多个 Feature、资源释放、UI 生命周期和启动诊断需求。如果只是一个小 Demo，直接 Bootstrap 更合适；如果是长期 Unity 项目，Composition 能把“项目全局结构”从散落代码里抽出来。