简介

本技术文档围绕 DouPHP 的轻量级依赖注入容器（DI Container）展开，系统讲解服务注册、解析、生命周期管理、单例模式、上下文绑定、工厂闭包、别名机制，以及中间件与服务发现如何与容器协作。面向初学者解释依赖注入概念与优势；面向高级开发者提供扩展容器、自定义服务与插件 Provider 的实践指南。

项目结构

DouPHP 将容器实现放在核心基础层，并在启动引导、路由解析、插件注册等关键路径中广泛使用。

graph TB
A["应用入口<br/>admin/init/Init.php"] --> B["容器实例<br/>Container::getInstance()"]
B --> C["服务注册<br/>instance()/singleton()/bind()/factory()"]
B --> D["服务解析<br/>make()/call()"]
E["路由解析<br/>DelegatingRouter.php"] --> D
F["插件注册器<br/>ConnectPluginRegistry.php"] --> D
G["中间件<br/>AuthMiddleware.php"] --> D

核心组件

• 容器类 Container：提供全局单例、服务绑定、单例缓存、工厂闭包、上下文绑定、别名、反射自动注入、方法调用参数注入等能力。
• 上下文绑定构建器 ContextualBindingBuilder：链式声明 when()->needs()->give() 的上下文替换策略。
• 启动引导 Init：在后台初始化阶段向容器注册视图引擎、语言契约、插件服务等。
• 路由 DelegatingRouter：从容器中解析 Request 并提取路由信息。
• 插件注册器 ConnectPluginRegistry：通过容器 make 动态创建插件 Provider。
• 中间件 AuthMiddleware：在请求管道中执行鉴权逻辑，配合容器提供的服务完成认证恢复。

架构总览

容器的职责是“解耦对象创建与依赖装配”，贯穿应用的启动、路由、插件、中间件与服务层。

sequenceDiagram
participant Boot as "启动引导 Init"
participant C as "容器 Container"
participant R as "路由 DelegatingRouter"
participant M as "中间件 AuthMiddleware"
participant P as "插件注册器 ConnectPluginRegistry"
Boot->>C : instance()/singleton()/bind() 注册服务
R->>C : bound(Request)? make(Request)
R-->>R : 解析模块/动作/路由
M->>C : 通过容器获取已注册服务(如 auth)
P->>C : make(ProviderClass) 动态加载插件
Note over C,P : 容器负责反射构造、依赖注入、单例缓存

详细组件分析

Container 类设计

• 全局单例：通过 getInstance() 提供进程内唯一容器实例，便于跨模块共享状态。
• 服务注册：
  • bind(): 抽象到具体类的映射，每次解析新建实例。
  • singleton(): 标记为单例，首次解析后缓存。
  • factory(): 以闭包作为工厂，覆盖先前绑定/单例缓存，适合延迟或条件创建。
  • instance(): 直接注入已有实例，覆盖工厂绑定。
  • alias(): 别名转发，提升可读性与兼容性。
• 服务解析：
  • make(): 支持别名、工厂、单例缓存、反射构造函数自动注入、FormRequest 场景参数注入。
  • call(): 对任意对象方法进行参数依赖注入。
• 上下文绑定：when(consumer)->needs(abstract)->give(concrete|callable)，仅影响指定消费者。
• 状态查询：has/bound/resolved/reset/forgetInstance，便于测试隔离与运行时控制。

classDiagram
class Container {
-static $instance
-array $bindings
-array $singletons
-array $factories
-array $contextualBindings
-array $aliases
-array $buildStack
+getInstance() Container
+setInstance(Container) void
+reset() void
+bind(string, string|null) void
+singleton(string, string|null) void
+factory(string, callable) void
+instance(string, mixed) void
+alias(string, string) void
+has(string) bool
+bound(string) bool
+resolved(string) bool
+forgetInstance(string) void
+when(string) ContextualBindingBuilder
+make(string, array) mixed
+call(object, string, array) mixed
-build(string, array) mixed
-resolveDependencies(array, array) array
-getParamClass(ReflectionParameter) ReflectionClass|null
-resolveContextual(string) string|callable|null
+addContextualBinding(string, string, string|callable) void
}
class ContextualBindingBuilder {
-Container $container
-string $consumer
-string|null $abstract
+__construct(Container, string)
+needs(string) ContextualBindingBuilder
+give(string|callable) void
}
Container --> ContextualBindingBuilder : "when() 返回"

服务注册与生命周期（Init 中的典型用法）

• 视图引擎与模板渲染接口通过 instance() 注入，确保后续所有消费方拿到同一实例。
• 语言契约、插件服务、消息响应器等在服务引导阶段注册为单例，避免重复创建。
• 根据 features 动态决定是否注册用户模块服务，体现按需装配。

flowchart TD
Start(["启动引导"]) --> GetC["获取容器实例"]
GetC --> RegView["注册视图引擎与模板渲染接口"]
RegView --> RegLang["注册语言契约实例"]
RegLang --> RegPlugin["注册插件服务单例"]
RegPlugin --> CheckFeature{"是否启用用户模块?"}
CheckFeature --> |是| RegUser["注册用户服务"]
CheckFeature --> |否| SkipUser["跳过用户服务"]
RegUser --> End(["引导完成"])
SkipUser --> End

服务解析与依赖注入（路由与插件）

• 路由解析时，若容器已绑定 Request，则通过 make() 解析出当前请求对象，用于提取模块、动作、路由字符串等信息。
• 插件注册器扫描 manifest.php，解析出 Provider 类名后，通过容器 make() 创建实例并进行类型校验，随后缓存于本地实例表，避免重复创建。

sequenceDiagram
participant Router as "路由 DelegatingRouter"
participant C as "容器 Container"
participant Req as "Request"
participant Reg as "插件注册器"
participant Prov as "Provider"
Router->>C : bound(Request.class)?
alt 已绑定
Router->>C : make(Request.class)
C-->>Router : Request 实例
Router->>Req : 读取路由信息
end
Reg->>C : make(ProviderClass)
C-->>Reg : Provider 实例
Reg->>Reg : 类型校验并缓存

中间件与容器集成

• 中间件在请求管道中运行，可借助容器获取已注册的服务（如认证、配置、日志等）。
• 认证中间件通过 auth('admin')->restoreFromSession() 恢复登录态，未登录抛出异常跳转登录页。

sequenceDiagram
participant MW as "中间件 AuthMiddleware"
participant C as "容器 Container"
participant Auth as "认证服务"
MW->>C : 获取 auth('admin')
C-->>MW : 认证服务实例
MW->>Auth : restoreFromSession(ip)
alt 未登录
MW-->>MW : 抛出 HttpResponseException
else 已登录
MW-->>Next : 继续管道
end

复杂逻辑流程：make() 解析与依赖注入

flowchart TD
S(["进入 make()"]) --> A["处理别名"]
A --> B{"是否工厂绑定?"}
B --> |是| F["调用工厂闭包"] --> R["返回结果"]
B --> |否| C{"是否单例且已缓存?"}
C --> |是| R
C --> |否| D["解析具体类名"]
D --> E["反射构建并注入依赖"]
E --> G{"是否单例?"}
G --> |是| H["写入单例缓存"]
G --> |否| I["不缓存"]
H --> R
I --> R

依赖关系分析

• 容器与启动引导：Init 在启动阶段集中注册服务，形成全局可用依赖图。
• 容器与路由：路由通过容器解析 Request，解耦路由与请求对象的创建。
• 容器与插件：插件注册器通过容器动态创建 Provider，降低耦合度。
• 容器与中间件：中间件通过容器获取服务，保持单一职责。

graph LR
Init["Init.php"] --> C["Container.php"]
Router["DelegatingRouter.php"] --> C
Plugin["ConnectPluginRegistry.php"] --> C
Middleware["AuthMiddleware.php"] --> C

性能与内存管理

• 单例缓存：singleton() 与 instance() 将实例缓存在 singletons 数组中，避免重复创建昂贵对象（如数据库连接、视图引擎）。
• 工厂闭包：factory() 允许延迟创建与条件创建，减少不必要的初始化开销。
• 别名与上下文绑定：通过 alias() 和 when()->needs()->give() 减少深层依赖重构成本，提高可维护性。
• 构建栈与错误定位：buildStack 记录当前消费者链，便于快速定位依赖解析失败位置。
• 建议：
  • 将重量级服务注册为单例或工厂，按需创建。
  • 使用 context binding 针对特定消费者替换实现，避免全局污染。
  • 在测试中使用 reset() 清空容器状态，保证用例隔离。

故障排查与调试

• 常见错误：
  • 无法解析参数：当构造函数参数既无默认值又不可空且未注册时，会抛出运行时异常，包含依赖链信息，便于定位。
  • 非可实例化类：尝试 new 不可实例化的类会抛出运行时异常。
  • 上下文绑定顺序错误：在使用 give() 前未调用 needs() 会抛出逻辑异常。
• 调试技巧：
  • 使用 has()/bound() 检查服务是否已注册。
  • 使用 resolved() 检查单例是否已实例化。
  • 使用 forgetInstance() 清除单例缓存，强制重建。
  • 使用 reset() 重置容器状态，适用于测试或重启场景。
  • 结合 buildStack 输出，查看依赖链，快速定位问题源头。

结论

DouPHP 的容器实现了轻量而强大的依赖注入能力，涵盖服务注册、解析、生命周期管理、上下文绑定与工厂模式。它在启动引导、路由、插件与中间件中广泛使用，有效降低了模块间耦合，提升了可测试性与可维护性。通过合理运用单例、工厂与上下文绑定，可以在保证性能的同时实现灵活的依赖装配。

附录：使用示例与最佳实践

• 注册自定义服务：
  • 使用 bind() 将接口映射到实现，或在启动引导中用 instance() 注入已有实例。
  • 对于需要延迟或条件创建的服务，使用 factory() 注册工厂闭包。
• 进行依赖注入：
  • 在控制器或服务构造函数中声明类型提示，容器会自动解析并注入依赖。
  • 对于 FormRequest，可通过 __scene 参数传递场景信息，容器会按场景创建对应实例。
• 上下文绑定：
  • 使用 when(Consumer)->needs(Abstract)->give(Concrete|Callable) 为特定消费者替换依赖实现。
• 中间件集成：
  • 在中间件中通过容器获取已注册服务，完成鉴权、限流、安全头等横切逻辑。
• 性能优化：
  • 将重量级服务注册为单例或工厂，避免重复创建。
  • 使用 reset() 在测试中隔离容器状态。
  • 利用 has()/bound()/resolved() 进行运行时检查，避免不必要的解析。