简介

本章节说明 DouPHP 的数据库配置与连接机制，覆盖主机地址、端口、数据库名、用户名、密码、表前缀、字符集等关键参数；解释不同数据库环境（MySQL/MariaDB）的连接要点；提供连接池与性能优化建议；并给出安全配置最佳实践。

项目结构

DouPHP 主站与独立 API 子模块均通过配置文件定义数据库连接参数，并在启动阶段加载到框架配置中，随后由数据库访问层统一建立连接与执行查询。

graph TB
A["应用入口<br/>前台/后台/API"] --> B["配置加载<br/>读取 dbhost/dbname/dbuser/dbpass/prefix/charset"]
B --> C["框架配置容器<br/>Config::set('db', ...)"]
C --> D["数据库访问层<br/>Database::instance()"]
D --> E["MySQL 连接<br/>mysqli_connect + SET NAMES"]

核心组件

• 配置文件：集中声明数据库主机、库名、用户、密码、表前缀与字符集常量。
• 启动装配：将配置项注入到框架配置容器中，供后续服务使用。
• 数据库访问层：负责解析 host:port、建立连接、设置字符集、选择数据库、提供链式查询与事务能力。

架构总览

下图展示从配置到连接的完整流程，以及字符集与表前缀的处理点。

sequenceDiagram
participant App as "应用"
participant Boot as "启动器 Bootstrap"
participant Cfg as "配置容器 Config"
participant DB as "数据库访问层 Database"
participant MySQL as "MySQL/MariaDB"
App->>Boot : 请求进入
Boot->>Cfg : set('db', {host,user,pass,name,prefix,charset})
App->>DB : Database : : instance()
DB->>DB : 解析 host : port默认端口3306
DB->>MySQL : mysqli_connect(host,user,pass,port)
DB->>MySQL : SET NAMES utf8mb4/utf8
DB->>MySQL : SELECT DATABASE / use dbname
DB-->>App : 连接就绪，可执行查询

详细组件分析

数据库连接参数与配置位置

• 主机地址与端口
  • 支持以“主机:端口”形式传入，未显式指定端口时默认使用 3306。
  • 主站配置文件位于根目录 config/config.php；API 示例位于 _'.api/data/config*.php。
• 数据库名、用户名、密码
  • 在配置文件中分别对应 dbname、dbuser、dbpass。
• 表前缀
  • 通过 prefix 配置，所有表名在访问时自动加上反引号与前缀，避免多站点或多租户场景下的表名冲突。
• 字符集
  • 通过 DOU_CHARSET 常量定义，连接时优先设置为 utf8mb4，若失败回退为 utf8。

表前缀的作用与冲突规避

• 作用
  • 所有表名在构建 SQL 时自动添加前缀与反引号，确保在不同环境或部署下不会与其他系统共用同名表。
• 冲突规避
  • 为每个站点或租户分配唯一前缀；在迁移或升级脚本中保持一致的前缀策略。
  • 使用统一的表命名规范，避免硬编码表名绕过前缀逻辑。

字符集配置的重要性（utf-8/utf8mb4）

• 为什么重要
  • 保证中文、表情符号等多字节字符正确存储与显示，避免乱码。
• 实现方式
  • 连接建立后优先尝试 utf8mb4；若驱动不支持则回退到 utf8。
  • 同时设置 sql_mode 为空，减少严格模式带来的兼容性问题。

不同数据库环境的连接配置示例

• MySQL 本地开发
  • 主机：127.0.0.1
  • 端口：3306（默认）
  • 库名：自定义业务库
  • 用户：root 或专用账户
  • 密码：强口令
  • 前缀：dou_
  • 字符集：utf-8（实际连接使用 utf8mb4）
• MariaDB
  • 连接参数与 MySQL 一致；字符集同样优先 utf8mb4。
• 远程数据库
  • 主机填写远程 IP 或域名；确保网络与防火墙放行 3306 端口；建议使用最小权限账户。

连接流程时序图（含错误处理）

sequenceDiagram
participant App as "应用"
participant DB as "Database"
participant MySQL as "MySQL/MariaDB"
App->>DB : instance()
DB->>DB : 解析 host : port
DB->>MySQL : 建立连接
alt 连接成功
DB->>MySQL : SET NAMES utf8mb4/utf8
DB->>MySQL : 选择数据库
DB-->>App : 返回实例
else 连接失败
DB-->>App : 输出 JSON 500 错误并终止
end

依赖关系分析

• 配置到连接
  • 配置文件提供原始参数；启动器将其写入配置容器；数据库访问层从容器读取并建立连接。
• 表名前缀
  • 所有表访问均通过统一方法生成带前缀的表名，降低耦合与出错概率。
• 字符集
  • 连接初始化阶段统一设置，贯穿整个会话。

graph LR
CFG["配置文件<br/>dbhost/dbname/dbuser/dbpass/prefix/DOU_CHARSET"] --> BOOT["启动器<br/>Config::set('db', ...)"]
BOOT --> DB["Database::instance()"]
DB --> CONN["mysqli_connect + SET NAMES"]
DB --> TBL["tableName()<br/>自动加前缀与反引号"]

性能考虑

• 连接复用
  • 使用单例模式获取数据库实例，避免重复创建连接。
• 字符集与模式
  • 优先使用 utf8mb4 以获得更好的兼容性；必要时根据服务器能力调整。
• 查询优化
  • 合理使用字段选择、条件过滤与排序，避免全表扫描。
• 事务与锁
  • 对写操作使用事务保证一致性；在高并发场景谨慎使用行级锁。
• 连接池建议
  • 当前实现基于 mysqli 单连接；如需连接池，可在 Web 服务器层使用持久连接或引入外部连接池方案，并确保与现有单例模式协调。

故障排查指南

• 无法连接数据库
  • 检查主机地址与端口是否正确；确认网络可达与防火墙策略。
  • 核对用户名与密码；查看错误响应中的详细信息。
• 字符集异常
  • 确认 DOU_CHARSET 设置为 utf-8；连接会优先使用 utf8mb4，如失败回退至 utf8。
• 表不存在或前缀问题
  • 确认 prefix 配置与实际表前缀一致；检查建表脚本是否已执行。
• 权限不足
  • 使用最小权限原则创建数据库账户，仅授予必要权限。

结论

DouPHP 的数据库配置集中在配置文件中，并通过启动器注入到框架配置容器，最终由数据库访问层统一建立连接、设置字符集与表前缀。遵循最小权限原则、合理设置字符集与表前缀，并结合查询与事务的最佳实践，可获得稳定、安全且高效的数据库访问体验。

附录

配置项速查

• 主机地址：dbhost（支持 host:port）
• 端口：未显式指定时使用默认 3306
• 数据库名：dbname
• 用户名：dbuser
• 密码：dbpass
• 表前缀：prefix（用于避免表名冲突）
• 字符集：DOU_CHARSET（推荐 utf-8，连接时优先 utf8mb4）