# 数据库性能优化

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [.example.env](file://.example.env)
- [composer.json](file://composer.json)
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)
- [public/themes/admin_default/admin/setting/clear_cache.html](file://public/themes/admin_default/admin/setting/clear_cache.html)
- [public/plugins/swagger/SwaggerPlugin.php](file://public/plugins/swagger/SwaggerPlugin.php)
- [public/plugins/swagger/controller/AdminIndexController.php](file://public/plugins/swagger/controller/AdminIndexController.php)
- [public/plugins/swagger/controller/ApiAdminIndexController.php](file://public/plugins/swagger/controller/ApiAdminIndexController.php)
- [public/plugins/swagger/controller/IndexController.php](file://public/plugins/swagger/controller/IndexController.php)
- [public/plugins/swagger/service/OpenApi.php](file://public/plugins/swagger/service/OpenApi.php)
- [public/plugins/swagger/swagger/OpenApiSpec.php](file://public/plugins/swagger/swagger/OpenApiSpec.php)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向 ThinkCMF 项目，聚焦数据库性能优化与调优实践，涵盖以下主题：
- 查询优化：慢查询分析、查询计划分析、索引优化策略
- 结构优化：表设计、索引设计、分区策略
- 缓存机制：查询缓存、结果缓存、分布式缓存
- 连接池配置：连接数、超时、连接复用
- 监控与指标：查询统计、连接状态、资源使用
- 实战案例：热点数据优化、并发控制、负载均衡
- 测试与诊断：性能测试方法、问题定位技巧

说明：本仓库未直接提供数据库配置与 ORM 使用示例，但通过入口文件、插件与框架信息可推导出数据库层的集成方式与优化切入点。

## 项目结构
ThinkCMF 采用多应用架构与插件机制，数据库层通常由底层框架（如 ThinkPHP）提供的 ORM/驱动负责。入口文件与插件是理解请求链路与潜在性能瓶颈的关键。

```mermaid
graph TB
A["入口脚本<br/>public/index.php"] --> B["路由分发<br/>public/router.php"]
A --> C["API 入口<br/>public/api.php"]
B --> D["控制器/服务层<br/>应用与插件"]
C --> D
D --> E["数据库层<br/>ORM/驱动"]
F["环境配置示例<br/>.example.env"] --> E
```

图表来源
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)
- [.example.env](file://.example.env)

章节来源
- [README.md:1-120](file://README.md#L1-L120)
- [composer.json:1-77](file://composer.json#L1-L77)
- [.example.env:1-1](file://.example.env#L1-L1)

## 核心组件
- 入口与路由
  - public/index.php：应用入口，初始化框架与服务容器
  - public/router.php：路由分发，决定请求进入控制器或 API
  - public/api.php：API 入口，面向 RESTful 接口
- 数据库配置
  - .example.env：示例环境变量，包含数据库连接关键字段（主机、端口、库名、字符集、前缀等）
- 插件生态
  - Swagger 插件：提供 API 文档能力，便于接口性能评估与回归测试

章节来源
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)
- [.example.env:1-1](file://.example.env#L1-L1)
- [README.md:103-113](file://README.md#L103-L113)

## 架构总览
从入口到数据库的典型调用链如下：

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Entry as "入口脚本<br/>public/index.php"
participant Router as "路由<br/>public/router.php"
participant API as "API 入口<br/>public/api.php"
participant Ctrl as "控制器/服务"
participant ORM as "ORM/驱动"
participant DB as "数据库"
Client->>Entry : HTTP 请求
Entry->>Router : 初始化并分发
alt RESTful API
Router->>API : 转交 API 入口
API->>Ctrl : 控制器/服务处理
else Web 应用
Router->>Ctrl : 控制器/服务处理
end
Ctrl->>ORM : 发起查询/事务
ORM->>DB : 执行 SQL
DB-->>ORM : 返回结果
ORM-->>Ctrl : 组装数据
Ctrl-->>Client : 响应
```

图表来源
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)

## 详细组件分析

### 入口与路由组件
- 入口脚本负责加载框架、服务发现与自动迁移等生命周期事件
- 路由与 API 入口决定业务处理路径，直接影响 ORM 调用频率与并发压力
- 优化建议
  - 在路由层减少不必要的中间件与鉴权开销
  - 对高频接口启用缓存与限流
  - 合理拆分 API 与 Web 路由，避免混用导致的额外处理

章节来源
- [composer.json:67-73](file://composer.json#L67-L73)
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)

### Swagger 插件与 API 文档
- Swagger 插件提供 OpenAPI 规范生成与文档展示，有助于：
  - 明确接口契约，减少无效请求
  - 辅助压测与回归测试，稳定性能基线
- 性能关注点
  - 文档生成与缓存策略
  - 接口分组与版本化，降低一次性加载成本

章节来源
- [README.md:103-113](file://README.md#L103-L113)
- [public/plugins/swagger/SwaggerPlugin.php](file://public/plugins/swagger/SwaggerPlugin.php)
- [public/plugins/swagger/controller/AdminIndexController.php](file://public/plugins/swagger/controller/AdminIndexController.php)
- [public/plugins/swagger/controller/ApiAdminIndexController.php](file://public/plugins/swagger/controller/ApiAdminIndexController.php)
- [public/plugins/swagger/controller/IndexController.php](file://public/plugins/swagger/controller/IndexController.php)
- [public/plugins/swagger/service/OpenApi.php](file://public/plugins/swagger/service/OpenApi.php)
- [public/plugins/swagger/swagger/OpenApiSpec.php](file://public/plugins/swagger/swagger/OpenApiSpec.php)

### 数据库配置与连接要点
- 环境变量示例包含数据库驱动、主机、端口、库名、字符集、前缀、调试与安全码等关键项
- 连接池与超时
  - 在应用侧通过框架配置连接池大小、空闲回收、超时时间
  - 在数据库侧设置最大连接数、wait_timeout、interactive_timeout
- 字符集与排序规则
  - 建议统一使用 utf8mb4，避免排序与比较的额外开销
- 前缀与命名
  - 使用统一前缀隔离多租户或多实例场景

章节来源
- [.example.env:1-1](file://.example.env#L1-L1)

### 查询优化与索引策略
- 慢查询分析
  - 启用慢查询日志，阈值建议从 1s 逐步下调至 100ms
  - 分析执行计划，关注全表扫描、回表次数、临时表与 filesort
- 索引优化
  - 遵循“最左前缀原则”，复合索引列顺序按过滤性与等值条件排序
  - 避免在索引列上使用函数/表达式，防止失效
  - 定期评估冗余索引，合并重复索引
- 查询重写
  - 将 OR 改写为 UNION/UNION ALL（必要时）
  - 使用覆盖索引减少回表
  - 分页优化：大偏移量使用延迟关联或基于主键的游标翻页

章节来源
- [README.md:84-94](file://README.md#L84-L94)

### 结构优化：表设计与分区
- 表设计
  - 字段类型选择：优先使用更小的整型与合适长度的字符串
  - 严格区分 NOT NULL 与默认值，减少存储与计算开销
  - 历史表与归档表分离，保留近期热数据
- 分区策略
  - 时间维度分区（按日/月/年），结合归档策略
  - 列表分区用于枚举类高基数字段
  - 注意分区键选择与查询谓词匹配度

章节来源
- [README.md:84-94](file://README.md#L84-L94)

### 缓存机制
- 查询缓存
  - 对稳定查询结果进行缓存，设置合理过期时间
  - 使用多级缓存（进程内/本地/分布式），降低数据库压力
- 结果缓存
  - 对聚合查询与复杂联表结果进行缓存
  - 采用“读写穿透”与“失效策略”，保证一致性
- 分布式缓存
  - Redis/Memcached：键空间设计、过期策略、热点保护
  - 使用 Lua 或 RedLock 保障原子性与一致性

章节来源
- [README.md:103-113](file://README.md#L103-L113)

### 连接池配置
- 连接数
  - 应用侧：根据 QPS 与并发会话数设定最小/最大连接数
  - 数据库侧：max_connections 与 innodb_thread_concurrency
- 超时
  - wait_timeout、interactive_timeout、net_read_timeout、net_write_timeout
- 复用策略
  - 连接池复用、事务边界明确、及时释放连接
  - 避免长事务占用连接

章节来源
- [.example.env:1-1](file://.example.env#L1-L1)

### 监控与性能指标
- 查询统计
  - 慢查询计数、平均/95 分位耗时、命中率
- 连接状态
  - 已用/最大连接、等待队列长度、超时次数
- 资源使用
  - CPU、内存、磁盘 IO、网络带宽
- 可视化
  - 结合 Prometheus/Grafana 或数据库自带报表

章节来源
- [README.md:84-94](file://README.md#L84-L94)

### 实战案例
- 热点数据优化
  - 读写分离：热点表只读实例扩容
  - 缓存预热：定时任务提前加载热点
- 并发控制
  - 限流与熔断：对高成本接口限流
  - 乐观锁/分布式锁：写冲突场景
- 负载均衡
  - 多实例部署，配合连接池与一致性哈希
- API 文档辅助
  - Swagger 插件用于接口契约校验与回归测试

章节来源
- [README.md:103-113](file://README.md#L103-L113)

### 性能测试与诊断
- 压测工具
  - wrk/JMeter/Locust，构造真实业务场景
- 关键指标
  - TPS、P95/P99 延迟、错误率、连接池利用率
- 诊断步骤
  - 采集慢查询日志与执行计划
  - 检查索引使用与覆盖情况
  - 核对连接池与数据库参数
  - 对比基准版本，定位回归

章节来源
- [README.md:84-94](file://README.md#L84-L94)

## 依赖分析
- 入口脚本与框架生命周期
  - composer.json 中定义了服务发现与迁移脚本，这些脚本可能涉及数据库初始化与迁移，需关注其执行时机与资源占用
- 插件与 API
  - Swagger 插件提供 API 文档能力，有助于性能测试与回归验证

```mermaid
graph LR
Composer["composer.json"] --> Scripts["脚本钩子<br/>service:discover / vendor:publish / migrate:run"]
Entry["public/index.php"] --> Router["public/router.php"]
Entry --> API["public/api.php"]
Router --> Plugins["插件生态<br/>Swagger 等"]
API --> Plugins
Plugins --> Docs["API 文档<br/>Swagger"]
```

图表来源
- [composer.json:67-73](file://composer.json#L67-L73)
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)
- [public/plugins/swagger/SwaggerPlugin.php](file://public/plugins/swagger/SwaggerPlugin.php)

章节来源
- [composer.json:67-73](file://composer.json#L67-L73)
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)

## 性能考量
- 代码层面
  - 减少 N+1 查询，批量加载关联数据
  - 合理使用分页与投影，避免 SELECT *
- 数据库层面
  - 定期维护统计信息，保持执行计划稳定
  - 控制长事务与锁竞争
- 运维层面
  - 连接池容量与超时参数随流量波动动态调整
  - 监控与告警联动，快速止损

## 故障排查指南
- 常见症状与定位
  - 响应缓慢：检查慢查询、索引缺失、锁等待
  - 连接不足：检查连接池上限与 wait_timeout
  - 内存飙升：排查大结果集与临时表
- 清理与恢复
  - 后台提供“清缓存”页面，可用于快速恢复与验证

章节来源
- [public/themes/admin_default/admin/setting/clear_cache.html:1-42](file://public/themes/admin_default/admin/setting/clear_cache.html#L1-L42)

## 结论
数据库性能优化是一个系统工程，需从入口链路、查询设计、索引策略、缓存体系、连接池与监控等多维度协同推进。结合 ThinkCMF 的多应用与插件架构，建议以 API 文档为契约，以缓存与连接池为抓手，以监控与压测为保障，持续迭代优化。

## 附录
- 环境与配置
  - 参考 .example.env 中的数据库配置项，结合生产环境进行参数校准
- 入口与路由
  - public/index.php、public/router.php、public/api.php 是定位性能瓶颈的重要入口

章节来源
- [.example.env:1-1](file://.example.env#L1-L1)
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)