简介
本指南面向 DouPHP 的数据库连接与连接复用能力，聚焦以下目标：
- 说明 PDO 持久化连接（pconnect）的配置方式与作用。
- 解释连接复用机制的工作原理：连接生命周期、空闲回收、泄漏检测。
- 给出开发、测试、生产环境的差异化连接池配置建议。
- 提供连接池监控与调优方法：使用率监控、指标收集、瓶颈诊断。
- 提供配置文件示例与常见问题解决方案。
重要说明：DouPHP 主站默认通过 mysqli 建立连接，未内置“最大/最小连接数”等显式连接池参数；但项目内包含基于 PDO 的连接适配器与连接管理器，可用于实现连接复用与 TTL 管理。因此，本文同时覆盖“原生连接行为”和“可选的 PDO 连接复用扩展”。
项目结构
- 应用配置位于 config/config.php，定义数据库主机、库名、用户、密码、表前缀与字符集等基础信息。
- 主站数据库访问由 core/infra/database/Connection.php 实现，采用 mysqli 直连，支持事务、链式查询、调试日志等。
- 门面层 core/facade/DB.php 将 Connection 以静态门面暴露给业务代码。
- API 子模块 _'/.api/lib/Database.php 提供独立部署时的数据库访问封装，同样基于 mysqli。
- 插件 SDK 中提供了基于 PDO 的连接适配器与连接管理器，可实现持久化连接与进程内缓存复用。
graph TB
A["应用配置<br/>config/config.php"] --> B["主站连接类<br/>core/infra/database/Connection.php"]
B --> C["门面 DB<br/>core/facade/DB.php"]
D["API 数据库封装<br/>_'/.api/lib/Database.php"] --> E["外部服务/数据库"]
B --> E
F["PDO 连接适配器<br/>plugin/.../DbConnectionAdapterPdo.php"] --> G["连接管理器<br/>plugin/.../DbConnectionManager.php"]
G --> E核心组件
- 应用配置：集中维护数据库连接基本信息（主机、库名、用户、密码、前缀、字符集）。
- 主站连接：基于 mysqli 的连接与查询封装，负责连接建立、字符集设置、SQL 模式、选择数据库、事务控制等。
- 门面：为业务提供统一的 DB 静态调用入口。
- API 数据库封装：独立部署场景下的数据库访问层，提供单例与链式查询。
- PDO 连接适配器：根据配置创建 PDO 实例，支持 pconnect 持久化连接。
- 连接管理器：进程内连接池，按 key 缓存连接并带过期时间，避免重复建连。
架构总览
下图展示了请求从门面到连接的调用路径，以及可选的 PDO 连接复用流程。
sequenceDiagram
participant App as "业务代码"
participant Facade as "DB 门面"
participant Conn as "Connection(mysqli)"
participant DB as "API Database(mysqli)"
participant PDOA as "PDO 适配器"
participant Pool as "连接管理器"
participant MySQL as "MySQL 服务器"
App->>Facade : 调用 table()/where() 等
Facade->>Conn : 获取连接并执行查询
Conn-->>App : 返回结果或错误
App->>DB : API 场景下使用独立封装
DB-->>App : 返回结果或错误
App->>Pool : 需要复用连接时
Pool->>PDOA : 构造 PDO(可开启 pconnect)
PDOA-->>Pool : 返回 PDO 实例
Pool-->>App : 返回复用连接
Note over Conn,Pool : 主站默认无显式池大小参数；可选通过连接管理器实现 TTL 复用详细组件分析
主站数据库连接（mysqli）
- 连接建立：解析主机与端口，尝试建立 mysqli 连接，设置字符集（utf8mb4 降级策略），设置 SQL 模式，选择数据库。
- 事务支持：beginTransaction/commit/rollback，支持嵌套保存点。
- 调试与错误：在调试模式下记录最后 SQL 与绑定参数；非调试模式统一错误提示，避免敏感信息泄露。
flowchart TD
Start(["开始"]) --> CheckExt["检查 mysqli 扩展"]
CheckExt --> |已启用| ParseHost["解析 host:port / IPv6"]
CheckExt --> |未启用| ErrExt["输出扩展缺失错误"]
ParseHost --> Connect["建立 mysqli 连接"]
Connect --> SetCharset["设置字符集(含 utf8mb4 降级)"]
SetCharset --> SetMode["设置 SQL 模式"]
SetMode --> SelectDB["选择数据库"]
SelectDB --> Done(["完成"])
ErrExt --> End(["结束"])API 数据库封装（mysqli）
- 单例模式：通过 instance() 读取 db.* 配置并创建共享连接。
- 连接建立：与主站类似，支持 host:port、字符集、选择数据库。
- 事务与错误：提供 begin/commit/rollback，错误统一 JSON 响应。
PDO 连接适配器（可选）
- 持久化连接：当配置项 pconnect 为 true 时，PDO::ATTR_PERSISTENT 设为 true，否则 false。
- DSN 构建：根据 adapter 类型（pdo_mysql/pdo_sqlite/pdo_pgsql/odbc）拼接 DSN。
- 适用场景：适合长驻进程（如 CLI、常驻 Worker）复用连接，减少握手开销。
连接管理器（进程内连接池）
- 连接键：基于 adapter/host/port/username/dbname 生成唯一键。
- 缓存策略：saveConnection 时将连接与 expire_time 存入静态数组，后续优先复用。
- 获取流程：先尝试新建连接，再尝试从缓存获取；均失败则报错。
classDiagram
class DbConnectionManager {
+getConnection(group, node, role)
-getConnectionKey(connConf) string
-saveConnection(connConf, connection, ttl) void
+$connectionPool array
}
class PdoAdapter {
+connect(connConf) PDO
}
DbConnectionManager --> PdoAdapter : "创建/复用连接"依赖关系分析
- 配置依赖：config/config.php 提供基础连接参数，被主站与 API 模块读取。
- 运行时依赖：Connection 依赖 mysqli 扩展；API Database 同理。
- 可选依赖：若启用 PDO 适配器与连接管理器，需确保 PHP 已加载对应 PDO 驱动。
graph LR
Cfg["配置 config/config.php"] --> MainConn["主站 Connection"]
Cfg --> ApiDb["API Database"]
MainConn --> MySQL["MySQL"]
ApiDb --> MySQL
Adapter["PDO 适配器"] --> Pool["连接管理器"]
Pool --> MySQL性能考量
- 连接创建成本：每次新建连接存在握手与认证开销。在高并发场景，建议使用持久化连接或进程内连接池以减少建连次数。
- 主站默认行为：当前主站 Connection 使用 mysqli 直连，未暴露最大/最小连接数参数；可通过连接管理器或外部代理（如 ProxySQL）实现池化。
- 持久化连接注意事项：
- pconnect=true 可减少建连开销，但需注意连接状态（会话变量、事务）可能跨请求残留。
- 建议在连接使用前重置必要状态，或在连接管理器中设置合理 TTL。
- 字符集与 SQL 模式：
- 自动 utf8mb4 降级保证兼容性。
- STRICT_TRANS_TABLES 避免静默截断导致的数据不一致。
- 事务与锁：合理使用事务与保存点，避免长事务占用连接。
故障排查指南
- 无法连接数据库：
- 检查主机、端口、用户名、密码是否正确。
- 确认 mysqli 扩展已启用。
- 查看错误日志中的连接错误信息。
- 字符集异常：
- 确认服务端支持 utf8mb4；不支持时会自动降级至 utf8。
- 事务回滚失败：
- 检查是否在事务中；确认最外层提交/回滚逻辑正确。
- 连接泄漏：
- 在主站 Connection 中，连接随请求结束释放；若使用连接管理器，请确保 TTL 生效且缓存清理正常。
- 使用 pconnect 时，注意连接状态隔离，必要时在连接使用前重置会话变量。
结论
- DouPHP 主站默认使用 mysqli 直连，未内置显式的连接池参数（最大/最小连接数）。
- 如需连接复用，可在业务侧引入 PDO 适配器与连接管理器，利用 pconnect 与 TTL 缓存实现进程内连接池。
- 不同环境建议：
- 开发环境：关闭 pconnect，缩短 TTL，便于调试与快速切换。
- 测试环境：适度开启 pconnect，设置中等 TTL，模拟真实负载。
- 生产环境：结合连接管理器与监控，合理设置 TTL，关注连接使用率与慢查询。
- 监控与调优：
- 统计连接创建次数、复用率、TTL 命中率。
- 观察慢查询与事务时长，优化 SQL 与索引。
- 对高并发场景考虑引入数据库代理进行连接池与读写分离。
附录
配置参数说明（PDO 连接复用）
- pconnect：是否启用持久化连接（true/false）。
- adapter：数据库驱动类型（pdo_mysql/pdo_sqlite/pdo_pgsql/odbc）。
- host/port/dbname/username/password：连接目标与凭据。
- TTL（连接管理器）：连接在进程内的存活时间，用于空闲回收与防泄漏。
不同环境连接池配置建议
- 开发环境
- pconnect=false，TTL=较短（例如 10-30 秒），便于调试与快速变更。
- 关闭严格模式或降低限制，提升迭代效率。
- 测试环境
- pconnect=true，TTL=中等（例如 60-120 秒），模拟生产复用效果。
- 开启严格模式，验证数据一致性。
- 生产环境
- pconnect=true，TTL=根据负载设定（例如 300-600 秒），配合监控动态调整。
- 开启严格模式，确保数据质量；定期巡检慢查询与连接使用率。
连接池监控与调优要点
- 指标采集
- 连接创建次数、复用次数、TTL 命中率、活跃连接数、等待队列长度。
- 慢查询数量、平均执行时间、事务持续时间。
- 瓶颈定位
- 连接耗尽：检查是否存在长事务或未释放连接；调整 TTL 与 pconnect。
- 慢查询：优化 SQL、添加索引、拆分复杂查询。
- 网络抖动：增加重试与超时控制，考虑连接健康检查。
- 调优实践
- 逐步提高 pconnect 与 TTL，观察吞吐与延迟变化。
- 对热点表与高频接口进行专项优化。
- 结合数据库代理实现连接池与读写分离。
配置文件示例（参考位置）
- 主站基础配置：见 config/config.php 中的数据库相关常量与变量。
- API 数据库配置：见 _'/.api/lib/Database.php 中 instance() 读取的 db.* 配置项。
- PDO 连接复用：在连接适配器中通过 connConf['pconnect'] 控制持久化连接。