依赖注入容器 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

依赖注入容器

简介

本文件面向 DouPHP 框架的依赖注入容器，系统性说明容器的职责、能力与在应用启动中的位置。重点覆盖：

服务注册（绑定、单例、工厂、别名、上下文绑定）
实例管理（缓存、生命周期、重置）
依赖解析（反射自动注入、FormRequest 场景参数、错误链提示）
单例模式与工厂模式的实现方式
容器在应用启动过程中的作用与顺序
服务绑定的最佳实践
性能优化建议、循环依赖处理策略、错误诊断方法
在控制器与服务中通过构造函数注入或辅助函数获取服务的用法

项目结构

DouPHP 将 DI 容器置于核心基础层，配合“服务提供者”在启动阶段完成能力装配；HTTP 请求对象、路由调度器在引导早期即入容器，供后续各层消费。

graph TB
A["应用入口<br/>core/bootstrap.php"] --> B["全局容器实例<br/>Container::getInstance()"]
B --> C["早期绑定 Request 单例"]
B --> D["早期绑定 DelegatingRouter 单例"]
B --> E["加载 helpers.php<br/>app()/request()/route() 等"]
F["系统引导 SystemBootstrap"] --> G["通过容器解析模块/语言/特性读取器"]
H["服务提供者 DataServiceProvider"] --> I["DataServiceContract -> 真实现/NullDataService"]
J["服务提供者 LanguageServiceProvider"] --> K["Language/AdminLanguage -> 真实现/NullLanguageService"]
L["服务提供者 PluginServiceProvider"] --> M["PluginServiceContract -> 真实现/NullPluginService"]
N["插件注册 ConnectPluginRegistry"] --> O["通过容器 make 创建 Provider 实例"]

图示来源

bootstrap.php:144-168
SystemBootstrap.php:55-90
DataServiceProvider.php:39-48
LanguageServiceProvider.php:39-56
PluginServiceProvider.php:40-49
ConnectPluginRegistry.php:92-164

核心组件

容器 Container：提供 bind/singleton/factory/instance/alias/when()->needs()->give()、make/call、has/bound/resolved/reset、构建栈与上下文绑定解析。
服务提供者：按能力域（数据、语言、插件）将契约绑定到具体实现或空实现，保证调用面稳定。
引导 bootstrap：在应用启动早期创建容器并预绑定关键对象（Request、路由），随后加载 helpers 暴露 app() 等便捷入口。
系统引导 SystemBootstrap：通过容器解析模块/语言/特性读取器，组装系统配置。
插件注册 ConnectPluginRegistry：扫描插件清单并通过容器创建 Provider 实例。

架构总览

容器是 DouPHP 的核心装配中心。启动流程如下：

初始化常量与配置后，创建全局容器实例。
提前绑定 Request 与 DelegatingRouter 为单例，确保路由与请求元信息可用。
加载 helpers.php，暴露 app()、request()、route()、language()、data()、plugin() 等便捷入口。
各端 Init 阶段调用服务提供者 register()，将契约绑定到具体实现或空实现。
业务代码通过构造函数注入或 app()/facade 获取服务。

sequenceDiagram
participant Boot as "引导 bootstrap.php"
participant C as "容器 Container"
participant R as "Request"
participant DR as "DelegatingRouter"
participant Prov as "服务提供者"
participant App as "业务代码"
Boot->>C : getInstance()
Boot->>C : instance(Request, capture())
Boot->>C : instance(DelegatingRouter, new ...)
Boot->>Boot : 加载 helpers.php
Note over Boot,C : 暴露 app()/request()/route() 等
Prov->>C : factory/register(...)
App->>C : make/bind/resolve
C-->>App : 返回实例/依赖树

图示来源

bootstrap.php:144-168
helpers.php:40-60
DataServiceProvider.php:39-48
LanguageServiceProvider.php:39-56
PluginServiceProvider.php:40-49

详细组件分析

容器 Container：能力与行为

服务注册
- bind：抽象到具体类的非单例绑定。
- singleton：标记为单例，首次解析后缓存。
- factory：以闭包作为工厂，每次解析调用（可覆盖先前绑定）。
- instance：直接注入已有实例为单例（可覆盖工厂）。
- alias：别名转发。
- when()->needs()->give()：上下文绑定，仅对指定消费者生效。
实例管理
- has/bound：判断是否已注册（含别名）。
- resolved：判断单例是否已实例化。
- forgetInstance：移除单例缓存，保留绑定。
- reset：清空全部状态，便于测试隔离。
依赖解析
- make：优先别名、工厂、单例缓存，再解析具体类。
- build：反射构造，支持无参、默认值、可空类型。
- resolveDependencies：按名称覆盖、类型提示、上下文绑定、FormRequest 场景参数递归解析。
- getParamClass：兼容 PHP 5.6/8.x 的类型读取，避免 ReflectionException 污染错误形态。
- resolveContextual：仅看当前构建栈顶消费者的上下文绑定，避免父级影响子依赖。
错误处理
- 不可实例化抛出运行时异常。
- 无法解析参数时抛出包含依赖链信息的运行时异常，便于定位。

flowchart TD
Start(["make(abstract)"]) --> CheckAlias{"有别名?"}
CheckAlias --> |是| MakeAlias["make(目标)"]
CheckAlias --> |否| CheckFactory{"有工厂?"}
CheckFactory --> |是| CallFactory["调用工厂闭包"]
CheckFactory --> |否| CheckSingleton{"单例已缓存?"}
CheckSingleton --> |是| ReturnInst["返回缓存实例"]
CheckSingleton --> |否| ResolveConcrete["解析具体类名"]
ResolveConcrete --> Build["build(concrete)"]
Build --> NewObj["反射构造 + 依赖注入"]
NewObj --> SaveSingle{"是否单例?"}
SaveSingle --> |是| Cache["写入单例缓存"]
SaveSingle --> |否| End(["返回实例"])
Cache --> End
CallFactory --> End
ReturnInst --> End
MakeAlias --> End

图示来源

Container.php:262-294
Container.php:318-344
Container.php:353-401

服务提供者：能力装配与降级

DataServiceProvider：根据 features.data 与实现类存在性，将 DataServiceContract 绑定到真实实现或 NullDataService。
LanguageServiceProvider：根据 features.language 与实现类存在性，将 LanguageContract 与 AdminLanguageContract 绑定到对应实现或 NullLanguageService。
PluginServiceProvider：根据 plugin 模块是否存在，将 PluginServiceContract 绑定到真实实现或 NullPluginService。

这些提供者允许重复调用且会覆盖前一次工厂闭包，从而支持动态切换与测试替换。

引导与助手：启动期绑定与便捷访问

bootstrap.php：创建全局容器，预绑定 Request 与 DelegatingRouter，加载 helpers.php。
helpers.php：暴露 app()、request()、route()、attachment()、message()、plugin()、audit()、auth()、locale()、language()、lang*、user()、data()、other() 等便捷函数，统一走容器解析。

系统引导：通过容器装配模块/语言/特性

SystemBootstrap::loadCore 通过容器解析 ModuleSettingReader、CoreModuleSettings、SystemConstantsReader、ModuleLanguageManifest、ModuleFeatureGate，组装 module/system/features/lang 四部分结果，供 Init 写入配置。

插件注册：基于容器的 Provider 发现与实例化

ConnectPluginRegistry 扫描插件 manifest，校验 provider 类名与接口，通过容器 make 创建 Provider 实例并缓存。

依赖关系分析

容器与引导：bootstrap 在极早期创建容器并绑定 Request、路由，使后续路由调度与中间件能安全访问请求上下文。
容器与服务提供者：Provider 在 Init 阶段注册契约到实现的映射，业务代码只依赖契约，解耦强。
容器与插件：插件通过容器创建 Provider，避免硬耦合与重复扫描。
路由与容器：DelegatingRouter 在需要时从容器取 Request，保证三端一致。

graph LR
Boot["bootstrap.php"] --> C["Container"]
C --> Req["Request(单例)"]
C --> Router["DelegatingRouter(单例)"]
C --> Helpers["helpers.php(app/request/route/...)"]
C --> Providers["服务提供者(Data/Lang/Plugin)"]
Providers --> Contracts["契约 DataService/Lang/Plugin"]
C --> Plugins["ConnectPluginRegistry"]
Plugins --> ProviderInstances["Provider 实例"]

图示来源

bootstrap.php:144-168
helpers.php:40-60
DataServiceProvider.php:39-48
LanguageServiceProvider.php:39-56
PluginServiceProvider.php:40-49
ConnectPluginRegistry.php:92-164

性能考量

单例缓存：singleton/instance 路径在首次解析后直接命中内存缓存，减少反射与构造开销。
工厂覆盖语义：factory 会清除同 abstract 的单例标记与缓存，避免旧实例被误用；适合按需重建的场景。
上下文绑定：when()->needs()->give() 仅在特定消费者生效，避免全局覆盖带来的额外查找成本。
懒加载与条件绑定：服务提供者依据 features 与 class_exists 决定绑定实现，未启用模块不会引入额外开销。
构建栈与错误链：resolveDependencies 维护构建栈，错误信息包含依赖链，有助于快速定位瓶颈与问题点。
建议
- 将重量级资源（数据库连接、外部客户端）注册为单例。
- 将可变状态对象（如请求相关）通过 request() 或上下文绑定注入，避免跨请求污染。
- 谨慎使用全局 instance() 覆盖，优先使用 factory 或 when()->needs()->give() 进行细粒度控制。

故障排查指南

无法解析参数
- 现象：抛出“Cannot resolve parameter [...]”异常，附带依赖链。
- 原因：缺少类型提示、默认值或可空声明；或未被绑定/别名/上下文绑定覆盖。
- 处理：检查构造函数参数类型、补充默认值或可空类型；在 Provider 中注册绑定或使用 when()->needs()->give() 指定实现。
单例未生效
- 现象：多次 make 返回不同实例。
- 原因：使用了 factory 覆盖了单例标记；或先 instance() 后被 factory() 覆盖。
- 处理：确认注册顺序；如需每次新建，显式使用 factory；如需单例，使用 singleton/instance。
上下文绑定无效
- 现象：某消费者仍解析到默认实现。
- 原因：when()->needs()->give() 未正确声明；或抽象名与实际类型不一致。
- 处理：核对消费者类名与抽象类型；确保 give() 传入的是类名或闭包。
循环依赖
- 现象：深度嵌套解析导致栈增长或报错。
- 现状：容器未内置循环检测；构建栈用于错误信息展示。
- 处理：重构依赖，引入接口或事件总线；或将易变依赖改为 lazy 工厂或延迟解析。
模块卸载/功能关闭
- 现象：调用 data()/language()/plugin() 等方法失败。
- 机制：服务提供者已提供 Null* 兜底实现，通常不会抛错。
- 处理：检查 features.* 开关与模块类是否存在；必要时在 Provider 中调整判定逻辑。

结论

DouPHP 的依赖注入容器提供了轻量而实用的 DI 能力：支持绑定、单例、工厂、别名与上下文绑定；通过反射自动注入依赖，并在错误时给出清晰的依赖链；在服务提供者中按功能开关与模块存在性进行条件绑定，保证系统在模块卸载或功能关闭时的稳定性。结合引导阶段的早期绑定与 helpers 便捷入口，开发者可以在控制器与服务中以最小代价获得解耦、可测试、可扩展的服务访问方式。

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

在控制器中使用依赖注入

推荐做法：在控制器构造函数中声明所需服务类型提示，由容器自动注入。
若需针对某个控制器注入特定实现，可使用 when()->needs()->give() 进行上下文绑定。
在控制器内部也可通过 request()、route()、language()、data()、plugin() 等 helper 获取服务。

在服务中使用依赖注入

在服务构造函数中声明依赖，容器会递归解析其依赖树。
对于可选或环境相关的依赖，可通过 FormRequest 场景参数或上下文绑定注入。
对重量级服务建议使用 singleton 或 instance 注册，避免重复创建。

服务绑定的最佳实践

将“契约”与“实现”分离，通过服务提供者集中注册。
使用 singleton/instance 管理共享资源（如数据库连接、外部客户端）。
使用 factory 管理可变对象或需要延迟创建的实例。
使用 when()->needs()->give() 进行细粒度的消费者级替换，避免全局覆盖。
在测试中利用 reset() 清理容器状态，确保用例隔离。

容器在应用启动中的作用

引导阶段创建全局容器并预绑定 Request、路由，确保后续路由与中间件可用。
加载 helpers.php 暴露便捷入口，统一通过容器解析服务。
服务提供者按功能开关与模块存在性注册契约到实现的映射，保证系统在不同配置下稳定运行。

添加日期：2026-10-05