# 性能测试与诊断

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [composer.json](file://composer.json)
- [.example.env](file://.example.env)
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)
- [vendor/thinkcmf/cmf-install/src/install/data/thinkcmf.sql](file://vendor/thinkcmf/cmf-install/src/install/data/thinkcmf.sql)
- [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)
- [public/plugins/system_info/controller/AdminIndexController.php](file://public/plugins/system_info/controller/AdminIndexController.php)
- [public/plugins/system_info/controller/ApiIndexController.php](file://public/plugins/system_info/controller/ApiIndexController.php)
- [public/plugins/system_info/SystemInfoPlugin.php](file://public/plugins/system_info/SystemInfoPlugin.php)
- [public/plugins/tianditu/TiandituPlugin.php](file://public/plugins/tianditu/TiandituPlugin.php)
- [public/plugins/tianditu/config.php](file://public/plugins/tianditu/config.php)
</cite>

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

## 引言
本指南面向 ThinkCMF 应用的数据库性能测试与诊断，围绕以下目标展开：压力测试、负载测试与稳定性测试的方法论；性能基准测试的场景设计、数据准备与结果分析；性能问题诊断流程（瓶颈定位、根因分析与方案验证）；常用测试工具与脚本（MySQL 自带工具、第三方工具与自定义脚本）；性能优化效果评估、性能回归测试与持续性能监控实践。内容基于仓库中的配置、示例与插件结构进行系统化梳理，并提供可落地的操作步骤与图示。

## 项目结构
ThinkCMF 采用多应用架构与插件机制，入口位于 public 目录，核心入口文件包括前端入口 index.php、API 入口 api.php 与路由入口 router.php。数据库初始化 SQL 位于 cmf-install 包内。Swagger 插件提供 API 文档能力，System Info 插件提供系统信息展示，Tianditu 插件提供地图服务集成。

```mermaid
graph TB
A["public/index.php<br/>前端入口"] --> B["public/router.php<br/>路由入口"]
C["public/api.php<br/>API 入口"] --> B
D["vendor/thinkcmf/cmf-install/src/install/data/thinkcmf.sql<br/>数据库初始化SQL"] --> E["数据库"]
F["public/plugins/swagger/*<br/>Swagger 插件"] --> G["API 文档与调试"]
H["public/plugins/system_info/*<br/>系统信息插件"] --> I["系统状态与指标"]
J["public/plugins/tianditu/*<br/>地图插件"] --> K["外部服务调用"]
```

图表来源
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)
- [vendor/thinkcmf/cmf-install/src/install/data/thinkcmf.sql](file://vendor/thinkcmf/cmf-install/src/install/data/thinkcmf.sql)
- [public/plugins/swagger/controller/AdminIndexController.php](file://public/plugins/swagger/controller/AdminIndexController.php)
- [public/plugins/system_info/controller/AdminIndexController.php](file://public/plugins/system_info/controller/AdminIndexController.php)
- [public/plugins/tianditu/TiandituPlugin.php](file://public/plugins/tianditu/TiandituPlugin.php)

章节来源
- [README.md:96-101](file://README.md#L96-L101)
- [composer.json:46-56](file://composer.json#L46-L56)

## 核心组件
- 入口与路由
  - public/index.php：前端页面入口，承载前台模板渲染与静态资源访问。
  - public/api.php：RESTful API 入口，承载业务接口与数据交互。
  - public/router.php：统一路由入口，负责请求分发与中间件处理。
- 数据库与配置
  - .example.env：示例环境变量，包含数据库驱动、主机、端口、字符集、前缀等关键配置项。
  - vendor/thinkcmf/cmf-install/src/install/data/thinkcmf.sql：数据库初始化结构与示例数据，可用于测试数据准备。
- 插件生态
  - Swagger 插件：提供 OpenAPI 文档与接口调试能力，便于接口性能观测与压测。
  - System Info 插件：提供系统信息展示，辅助性能监控与状态采集。
  - Tianditu 插件：提供地图服务集成，涉及外部服务调用，需纳入性能测试范围。

章节来源
- [README.md:96-101](file://README.md#L96-L101)
- [.example.env:1-1](file://.example.env#L1-L1)
- [vendor/thinkcmf/cmf-install/src/install/data/thinkcmf.sql](file://vendor/thinkcmf/cmf-install/src/install/data/thinkcmf.sql)
- [public/plugins/swagger/controller/AdminIndexController.php](file://public/plugins/swagger/controller/AdminIndexController.php)
- [public/plugins/system_info/controller/AdminIndexController.php](file://public/plugins/system_info/controller/AdminIndexController.php)
- [public/plugins/tianditu/TiandituPlugin.php](file://public/plugins/tianditu/TiandituPlugin.php)

## 架构总览
下图展示了从浏览器到数据库的典型请求链路，以及与插件生态的交互关系。该链路是性能测试与诊断的关键路径。

```mermaid
sequenceDiagram
participant U as "用户浏览器"
participant IDX as "public/index.php"
participant R as "public/router.php"
participant API as "public/api.php"
participant SW as "Swagger 插件"
participant SI as "System Info 插件"
participant DB as "数据库"
U->>IDX : 访问前台页面
IDX->>R : 请求分发
U->>API : 调用 RESTful 接口
API->>SW : 可选：OpenAPI 文档/调试
API->>SI : 可选：系统状态查询
API->>DB : 执行 SQL 查询/写入
DB-->>API : 返回结果
API-->>U : 响应数据
```

图表来源
- [public/index.php](file://public/index.php)
- [public/router.php](file://public/router.php)
- [public/api.php](file://public/api.php)
- [public/plugins/swagger/controller/AdminIndexController.php](file://public/plugins/swagger/controller/AdminIndexController.php)
- [public/plugins/system_info/controller/AdminIndexController.php](file://public/plugins/system_info/controller/AdminIndexController.php)

## 详细组件分析

### 组件一：数据库连接与配置
- 关键点
  - 环境变量：通过 .example.env 提供数据库驱动、主机、端口、字符集、前缀、调试开关等配置项，便于在不同环境切换与压测参数调整。
  - 初始化 SQL：thinkcmf.sql 提供表结构与示例数据，可用于构造测试数据集与验证查询计划。
- 性能关注
  - 字符集与排序规则：utf8mb4 与合适排序规则影响索引与排序性能。
  - 前缀与命名：统一前缀有助于批量迁移与测试隔离。
  - 调试开关：开启数据库调试可输出慢查询与执行计划，便于定位瓶颈。

章节来源
- [.example.env:1-1](file://.example.env#L1-L1)
- [vendor/thinkcmf/cmf-install/src/install/data/thinkcmf.sql](file://vendor/thinkcmf/cmf-install/src/install/data/thinkcmf.sql)

### 组件二：Swagger 插件（API 文档与调试）
- 关键点
  - 控制器：AdminIndexController、ApiAdminIndexController、IndexController 提供后台与 API 的文档入口。
  - 服务：OpenApi 与 OpenApiSpec 提供文档生成与规范导出。
- 性能关注
  - 文档生成：在高并发下避免频繁生成文档导致的 CPU 占用。
  - 接口覆盖：确保压测场景覆盖文档中列出的接口，保证测试完整性。
  - 调试参数：利用文档提供的参数校验与示例，减少无效请求带来的数据库压力。

```mermaid
classDiagram
class AdminIndexController
class ApiAdminIndexController
class IndexController
class OpenApi
class OpenApiSpec
AdminIndexController --> OpenApi : "依赖"
ApiAdminIndexController --> OpenApi : "依赖"
IndexController --> OpenApiSpec : "依赖"
OpenApi --> OpenApiSpec : "生成规范"
```

图表来源
- [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)

章节来源
- [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)

### 组件三：System Info 插件（系统信息）
- 关键点
  - 控制器：AdminIndexController、ApiIndexController 提供后台与 API 的系统信息接口。
  - 插件：SystemInfoPlugin 作为插件入口，负责注册与生命周期管理。
- 性能关注
  - 系统指标：CPU、内存、磁盘、连接数等，可作为性能回归与监控基线。
  - 接口频率：避免在压测中过度调用系统信息接口，以免干扰测试结果。

```mermaid
classDiagram
class AdminIndexController
class ApiIndexController
class SystemInfoPlugin
AdminIndexController --> SystemInfoPlugin : "依赖"
ApiIndexController --> SystemInfoPlugin : "依赖"
```

图表来源
- [public/plugins/system_info/controller/AdminIndexController.php](file://public/plugins/system_info/controller/AdminIndexController.php)
- [public/plugins/system_info/controller/ApiIndexController.php](file://public/plugins/system_info/controller/ApiIndexController.php)
- [public/plugins/system_info/SystemInfoPlugin.php](file://public/plugins/system_info/SystemInfoPlugin.php)

章节来源
- [public/plugins/system_info/controller/AdminIndexController.php](file://public/plugins/system_info/controller/AdminIndexController.php)
- [public/plugins/system_info/controller/ApiIndexController.php](file://public/plugins/system_info/controller/ApiIndexController.php)
- [public/plugins/system_info/SystemInfoPlugin.php](file://public/plugins/system_info/SystemInfoPlugin.php)

### 组件四：Tianditu 插件（外部服务）
- 关键点
  - TiandituPlugin：插件主类，负责地图服务集成。
  - config.php：插件配置，可能包含服务地址、密钥等。
- 性能关注
  - 外部服务延迟与可用性：在压测中需区分内部接口与外部服务耗时，避免误判数据库瓶颈。
  - 超时与重试策略：合理设置超时与重试，防止雪崩效应。

章节来源
- [public/plugins/tianditu/TiandituPlugin.php](file://public/plugins/tianditu/TiandituPlugin.php)
- [public/plugins/tianditu/config.php](file://public/plugins/tianditu/config.php)

### 组件五：入口与路由
- 关键点
  - public/index.php：前台入口，承载模板渲染与静态资源。
  - public/api.php：API 入口，承载 RESTful 接口。
  - public/router.php：统一路由，负责中间件与分发。
- 性能关注
  - 中间件开销：在压测中评估中间件链路对响应时间的影响。
  - 路由命中率：确保高频接口路由稳定，避免不必要的分支判断。

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

## 依赖分析
- Composer 依赖
  - thinkcmf/cmf-app、cmf-api、cmf-install 等包构成核心框架与安装初始化能力。
  - autoload 配置将 app、api、plugins、themes 命名空间映射到对应目录，便于模块化开发与测试隔离。
- 插件依赖
  - Swagger 插件依赖 OpenAPI 服务与规范生成器。
  - System Info 插件依赖后台控制器与系统状态采集。
- 外部依赖
  - MySQL 5.7+（推荐）与 PHP 8.1+，满足性能测试与 ORM 使用需求。

```mermaid
graph LR
CMF["thinkcmf/cmf-app"] --> APP["应用层"]
API["thinkcmf/cmf-api"] --> API_LAYER["API 层"]
INSTALL["thinkcmf/cmf-install"] --> DB_INIT["数据库初始化"]
SW["Swagger 插件"] --> OPENAPI["OpenAPI 服务"]
SI["System Info 插件"] --> SYSCTL["系统控制器"]
```

图表来源
- [composer.json:30-42](file://composer.json#L30-L42)
- [composer.json:46-56](file://composer.json#L46-L56)

章节来源
- [composer.json:30-42](file://composer.json#L30-L42)
- [composer.json:46-56](file://composer.json#L46-L56)
- [README.md:84-94](file://README.md#L84-L94)

## 性能考虑
- 环境与配置
  - 使用 .example.env 中的数据库配置项，结合压测目标调整字符集、前缀与调试开关。
  - 在生产或压测环境中启用慢查询日志与执行计划分析，定位热点 SQL。
- 测试数据准备
  - 基于 thinkcmf.sql 构造与线上规模相当的数据集，覆盖高频查询与写入场景。
  - 对关键表建立必要索引，确保测试场景与线上一致。
- 场景设计
  - 压力测试：逐步提升并发与吞吐，观察数据库连接池、锁等待与错误率。
  - 负载测试：在稳定状态下长时间运行，监测内存泄漏、连接泄漏与资源占用。
  - 稳定性测试：模拟异常场景（网络抖动、数据库重启），验证恢复能力。
- 结果分析
  - 关注 QPS、P95/P99 延迟、错误率、连接数、锁等待与慢查询数量。
  - 对比优化前后指标，形成可复现的基准报告。

## 故障排查指南
- 瓶颈定位
  - 使用数据库自带工具（如 EXPLAIN、SHOW PROFILE/PROCESSLIST、INNODB STATUS）分析慢查询与锁竞争。
  - 利用 System Info 插件接口采集系统指标，结合 API 日志定位异常。
- 根因分析
  - 若外部服务（如 Tianditu）成为瓶颈，需区分外部耗时与内部耗时，避免误判数据库。
  - 检查路由与中间件链路，排除不必要的计算与 IO。
- 方案验证
  - 通过 Swagger 插件提供的接口与参数，快速验证索引、SQL 改写与缓存策略的效果。
  - 建立回归测试用例，确保修复不会引入新的性能退化。

## 结论
本指南从入口与路由、数据库配置、插件生态与依赖关系出发，构建了 ThinkCMF 的性能测试与诊断框架。通过明确测试方法论、基准设计与工具使用，结合系统化的诊断流程与验证手段，可有效提升数据库性能质量与稳定性。

## 附录
- 常用工具与脚本建议
  - MySQL 自带工具：EXPLAIN、SHOW ENGINE INNODB STATUS、SHOW PROCESSLIST、慢查询日志。
  - 第三方工具：sysbench（OLTP）、pt-query-digest（慢查询分析）、Percona Toolkit。
  - 自定义脚本：基于 Swagger 文档生成压测场景，结合 System Info 接口采集系统指标。
- 性能优化与回归
  - 建立性能基线与阈值，定期回归测试。
  - 将性能测试纳入 CI/CD，实现持续性能监控与预警。