场景树驱动的依赖注入：Godot C# 项目架构实践

一、问题的起点：一个看似简单的命令流程

在即时战略类游戏中，玩家框选一队单位、右键点击地图、单位寻路前往目标点——这是最基础的操作之一。但落到代码层面，这条链路至少涉及三个系统：

• 选择管理器：需要知道当前哪些单位被选中；
• 寻路服务：需要根据起点与终点计算路径；
• 编队控制器：需要让多个单位以合理队形移动。

最初的实现往往非常直接：

public partial class CommandIssuer : Node
{
    public override void _Ready()
    {
        var selectionManager = GetNode<SelectionManager>("/root/Game/SelectionManager");
        var pathfinding = GetNode<PathfindingService>("/root/PathfindingService");
        // 发布移动命令...
    }
}

这段代码能跑，但埋下了两个隐患。

第一，硬编码路径导致场景结构脆弱。 一旦为了重构把某个管理器节点挪到别的位置，所有 GetNode 调用都会在运行时失败。问题不会在编译期暴露，而是等到运行才爆出来。

第二，单元测试几乎无法编写。 寻路逻辑本身是纯计算，但因为它依赖具体节点，而节点又依赖完整场景树，测试就必须先搭建一整棵场景树。这不仅繁琐，而且测试用例之间容易互相污染。

二、从全局单例到生命周期困境

为了解决节点查找问题，一个自然的想法是使用全局单例：把寻路、迷雾等系统注册为自动加载的全局对象。这样任何脚本都能直接访问，路径问题确实消失了。

但新的问题随之而来：

• 生命周期管理混乱。 玩家从第一关切换到第二关时，旧关卡的寻路网格、迷雾数据仍然留在全局对象里，必须手写重置逻辑。一旦漏掉某个字段，就会出现上一关的残留状态影响下一关。
• 测试状态串扰。 全局对象在测试进程中是共享的，一个测试修改了内部状态，下一个测试就会读到脏数据。排查这类问题时，开发者往往要花大量时间定位状态来源。
• 依赖关系隐式化。 任何代码都可以访问全局对象，调用关系不再体现在构造函数或初始化流程中，代码的可读性和可维护性下降。

本质上，全局单例用“随处可访问”换来了“难以追踪的生命周期”和“不可隔离的测试环境”。

三、核心思路：把场景树当作作用域容器

场景树本身就是一棵有明确父子关系和生命周期事件的层级结构。父节点被添加时，子节点随之进入树；父节点被释放时，子节点也会被一并清理。这种天然的层级关系，恰好可以用来表达依赖注入中的作用域（Scope）。

一个典型的游戏场景结构可能如下：

Root
├── MainMenu (主菜单)
└── Campaign (战役)
    ├── Mission (关卡容器)
    │   ├── TerrainManager (地形)
    │   └── UnitManager (单位)
    └── UI (界面)
        ├── MiniMap (小地图)
        └── CommandPanel (命令面板)

如果让 Mission 节点充当关卡级别的服务容器，它负责创建并持有本关需要的所有服务——寻路网格、迷雾系统、单位注册表等。那么当关卡结束、Mission 节点被销毁时，这些服务会随节点一起释放，无需手动重置。切换关卡时，新关卡创建新的 Mission，天然获得干净的服务实例。

这就把“手动管理全局状态”变成了“由场景树层级自动管理生命周期”。

四、落地实现：从容器到注入

4.1 定义关卡级容器

容器本身可以是一个普通节点，负责注册和解析服务：

public partial class MissionScope : Node
{
    private readonly Dictionary<Type, object> _services = new();
    public void Register<T>(T service) where T : class
    {
        _services[typeof(T)] = service;
    }
    public T Resolve<T>() where T : class
    {
        if (_services.TryGetValue(typeof(T), out var service))
            return (T)service;
        throw new InvalidOperationException($"Service {typeof(T).Name} not registered.");
    }
}

在 Mission 的 _Ready 中完成注册：

public override void _Ready()
{
    var scope = GetNode<MissionScope>("MissionScope");
    scope.Register<IPathfindingService>(new GridPathfindingService());
    scope.Register<IFogOfWarService>(new FogOfWarService());
    scope.Register<IUnitRegistry>(new UnitRegistry());
}

4.2 通过构造注入获取依赖

与其在业务代码里主动查找服务，不如在创建对象时把依赖传进去：

public class CommandIssuer
{
    private readonly ISelectionManager _selection;
    private readonly IPathfindingService _pathfinding;
    private readonly IFormationController _formation;
    public CommandIssuer(
        ISelectionManager selection,
        IPathfindingService pathfinding,
        IFormationController formation)
    {
        _selection = selection;
        _pathfinding = pathfinding;
        _formation = formation;
    }
    public void IssueMoveCommand(Vector2 target)
    {
        var units = _selection.GetSelectedUnits();
        var path = _pathfinding.CalculatePath(units, target);
        _formation.ApplyFormation(units, path);
    }
}

这样 CommandIssuer 不再依赖任何具体节点，测试时只需传入接口的模拟实现即可。

4.3 接口隔离与可测试性

为每个服务定义接口，是让依赖注入真正发挥作用的关键：

public interface IPathfindingService
{
    IReadOnlyList<Vector2> CalculatePath(IReadOnlyList<Unit> units, Vector2 target);
}

在单元测试中，可以实现一个返回固定路径的假实现，从而在完全不涉及场景树的情况下验证命令发布逻辑。测试用例之间也不会再有状态残留，因为每个测试都可以创建独立的服务实例。

五、进阶考量：作用域层级与生命周期

场景树作为作用域容器，还有几个值得注意的设计点。

作用域可以嵌套。 例如 Campaign 级别可以注册跨关卡共享的服务（如玩家存档、全局配置），而 Mission 级别注册关卡专属服务。子作用域可以向上查找父作用域，形成链式解析。这与通用依赖注入框架中的作用域嵌套思路一致。

注册时机要清晰。 建议在容器的 _Ready 中完成所有服务注册，避免在运行过程中动态注册导致解析顺序不确定。

释放顺序要留意。 节点释放时，子节点先于父节点被清理。如果服务之间存在依赖关系，应确保被依赖的服务在依赖者之后释放，或在释放前显式解除引用。

避免过度注入。 并非所有对象都需要走容器。纯数据结构、工具类、无状态函数更适合直接使用静态方法或实例化，不必强行纳入依赖注入体系。

六、总结

在 Godot C# 项目中，依赖注入的核心痛点不在于“如何获取对象”，而在于“如何管理生命周期”和“如何隔离测试”。把场景树的层级结构直接用作依赖注入的作用域容器，可以同时解决这两个问题：

• 服务随关卡节点创建与销毁，生命周期由场景树自动管理；
• 每个关卡拥有独立服务实例，测试之间互不干扰；
• 通过构造注入和接口隔离，业务代码不再依赖具体节点路径，重构场景结构时不会引发连锁报错。

这套思路并不复杂，但它把场景树从“节点组织方式”提升为“架构组织方式”，让代码结构更贴近游戏本身的层级语义。对于中大型 Godot 项目而言，这种模式能在可维护性和可测试性上带来显著收益。