# 架构设计

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [composer.json](file://composer.json)
- [public/index.php](file://public/index.php)
- [public/api.php](file://public/api.php)
- [public/router.php](file://public/router.php)
- [public/plugins/swagger/SwaggerPlugin.php](file://public/plugins/swagger/SwaggerPlugin.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/themes/default/manifest.json](file://public/themes/default/manifest.json)
- [public/themes/admin_default/manifest.json](file://public/themes/admin_default/manifest.json)
</cite>

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

## 引言
本文件面向 ThinkCMF 的架构设计与实现进行系统化梳理，重点覆盖以下方面：
- 多应用架构：前台应用（app/）与 API 应用（api/）的分离策略与职责边界
- MVC 架构在 ThinkCMF 中的落地：控制器、模型、视图的层次与交互
- 命名空间规范、自动加载机制与依赖注入的使用现状
- 插件系统与钩子机制：如何通过钩子实现系统扩展
- 主题系统：模板渲染引擎与可视化设计能力
- 数据流与控制流：从请求进入到底层数据处理的完整路径
- 架构图表与组件关系图，帮助开发者快速理解整体设计

## 项目结构
ThinkCMF 采用“多应用 + 插件 + 主题”的分层组织方式：
- 应用层：前台应用 app/ 与 API 应用 api/ 分离部署，分别由独立入口文件引导
- 插件层：位于 public/plugins 下，每个插件以独立命名空间与目录组织，提供钩子扩展点
- 主题层：位于 public/themes 下，包含前台 default 与后台 admin_default 两大主题，均以 manifest.json 描述元信息
- 根目录 composer.json 定义 PSR-4 自动加载映射，将 app、api、plugins、themes 映射到对应目录

```mermaid
graph TB
subgraph "入口与路由"
R["public/router.php"]
I["public/index.php"]
A["public/api.php"]
end
subgraph "应用层"
APP["app/"]
API["api/"]
end
subgraph "插件层"
SW["public/plugins/swagger/"]
SI["public/plugins/system_info/"]
TD["public/plugins/tianditu/"]
end
subgraph "主题层"
DEF["public/themes/default/"]
ADM["public/themes/admin_default/"]
end
R --> I
R --> A
I --> APP
A --> API
APP --> SW
APP --> SI
APP --> TD
API --> SW
DEF --> APP
ADM --> API
```

**图表来源**
- [public/router.php:1-20](file://public/router.php#L1-L20)
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [composer.json:46-56](file://composer.json#L46-L56)

**章节来源**
- [README.md:10-18](file://README.md#L10-L18)
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [public/index.php:27-31](file://public/index.php#L27-L31)
- [public/api.php:30-34](file://public/api.php#L30-L34)

## 核心组件
- 多应用入口
  - 前台入口：public/index.php 加载 vendor 自动加载后，启动 HTTP 应用并运行
  - API 入口：public/api.php 在前台入口基础上额外定义 APP_NAMESPACE 为 api，从而切换应用命名空间
- 自动加载与命名空间
  - composer.json 使用 PSR-4 将 app\、api\、plugins\、themes\ 映射到相应目录，确保按需自动加载
- 插件系统
  - 插件以独立命名空间组织，继承通用插件基类，提供 install/uninstall 生命周期与钩子方法
- 主题系统
  - 主题以 manifest.json 描述元信息；前台 default 与后台 admin_default 提供基础模板与可视化设计能力

**章节来源**
- [public/index.php:27-31](file://public/index.php#L27-L31)
- [public/api.php:28-34](file://public/api.php#L28-L34)
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/themes/default/manifest.json:1-11](file://public/themes/default/manifest.json#L1-L11)
- [public/themes/admin_default/manifest.json:1-10](file://public/themes/admin_default/manifest.json#L1-L10)

## 架构总览
ThinkCMF 的请求处理遵循“入口文件 -> 应用实例 -> 路由分发 -> 控制器 -> 模型/服务 -> 视图/响应”的标准 MVC 流程。多应用架构通过不同的入口文件与命名空间实现前台与 API 的隔离与协同。

```mermaid
sequenceDiagram
participant C as "客户端"
participant R as "public/router.php"
participant E as "入口文件(index.php 或 api.php)"
participant L as "自动加载(composer)"
participant H as "HTTP应用(App)"
participant D as "路由/调度"
participant CTRL as "控制器"
participant M as "模型/服务"
participant V as "视图/模板"
participant RESP as "响应"
C->>R : 发起请求
R->>E : 转交至入口文件
E->>L : 加载自动加载器
E->>H : 构建并运行HTTP应用
H->>D : 解析路由与中间件
D->>CTRL : 实例化控制器并调用动作
CTRL->>M : 读取/写入数据
M-->>CTRL : 返回数据
CTRL->>V : 渲染视图或序列化数据
V-->>RESP : 组装响应体
RESP-->>C : 返回结果
```

**图表来源**
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [public/index.php:27-31](file://public/index.php#L27-L31)
- [public/api.php:30-34](file://public/api.php#L30-L34)

## 详细组件分析

### 多应用架构：前台与 API 的分离
- 设计理念
  - 前台应用（app/）负责面向用户的页面渲染与交互
  - API 应用（api/）负责对外提供 RESTful 接口，便于移动端、小程序、第三方系统集成
- 入口差异
  - 前台入口仅定义命名空间与路径常量，随后启动 HTTP 应用
  - API 入口在前台基础上显式设置 APP_NAMESPACE 为 api，使框架按 API 应用解析路由与控制器
- 路由与控制器
  - 两套入口共享同一自动加载与公共配置，但控制器与路由按应用命名空间隔离
- 优势
  - 前后端职责清晰，API 可独立演进与安全加固
  - 便于引入 Swagger 等工具对 API 进行文档化与自动化测试

```mermaid
flowchart TD
S["请求到达"] --> J{"是否 API 请求?"}
J --> |是| AP["使用 public/api.php 入口"]
J --> |否| IDX["使用 public/index.php 入口"]
AP --> NS["设置 APP_NAMESPACE=api"]
IDX --> NS2["保持 APP_NAMESPACE=app"]
NS --> RUN["启动 HTTP 应用"]
NS2 --> RUN
RUN --> DIS["路由分发"]
DIS --> CTRL["控制器动作"]
CTRL --> RESP["响应输出"]
```

**图表来源**
- [public/index.php:27-31](file://public/index.php#L27-L31)
- [public/api.php:28-34](file://public/api.php#L28-L34)

**章节来源**
- [README.md:10-18](file://README.md#L10-L18)
- [public/index.php:27-31](file://public/index.php#L27-L31)
- [public/api.php:28-34](file://public/api.php#L28-L34)

### MVC 架构在 ThinkCMF 中的实现
- 控制器（Controller）
  - 位于 app/controller 与 api/controller 下，按应用命名空间组织
  - 负责接收请求参数、调用服务/模型、选择视图或返回 JSON
- 模型（Model）
  - 位于 app/model 与 api/model 下，封装数据访问与业务规则
  - 与数据库表映射，提供增删改查与关联查询等能力
- 视图（View）
  - 位于 app/view 与 api/view 下，或主题模板目录
  - 支持模板标签、变量渲染与组件化（如 widgets）

```mermaid
classDiagram
class 控制器 {
+接收请求()
+调用服务()
+渲染视图()
+返回响应()
}
class 模型 {
+数据访问()
+业务规则()
+关联查询()
}
class 视图 {
+模板渲染()
+变量替换()
+组件挂载()
}
控制器 --> 模型 : "读写数据"
控制器 --> 视图 : "渲染输出"
```

[本图为概念示意，无需图表来源]

**章节来源**
- [README.md:20-70](file://README.md#L20-L70)

### 命名空间规范、自动加载与依赖注入
- 命名空间与目录映射
  - composer.json 使用 PSR-4 将 app\、api\、plugins\、themes\ 映射到对应目录
  - 插件与主题以各自命名空间组织，避免冲突
- 自动加载
  - 入口文件 require vendor/autoload.php，按需加载类文件
- 依赖注入
  - 代码库未直接展示集中式容器配置；通常通过 ThinkPHP 的服务容器与构造函数注入实现

```mermaid
graph LR
PSR["PSR-4 映射(app, api, plugins, themes)"] --> AUTO["vendor/autoload.php"]
AUTO --> NSP["命名空间解析"]
NSP --> CLS["类文件加载"]
```

**图表来源**
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/index.php:27](file://public/index.php#L27)

**章节来源**
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/index.php:27](file://public/index.php#L27)

### 插件系统与钩子机制
- 插件结构
  - 每个插件拥有独立目录与命名空间，包含控制器、服务、视图与配置
  - 插件类继承通用插件基类，提供 info、install、uninstall 与钩子方法
- 钩子扩展
  - 插件通过钩子方法在系统关键节点插入行为（如后台仪表盘、弹窗、API 导入等）
  - 钩子名称即方法名，系统在合适时机触发
- 示例
  - Swagger 插件：扫描 API 注解生成 OpenAPI 规范，并同步到后台权限与菜单
  - SystemInfo 插件：在后台首页展示服务器信息区块
  - Tianditu 插件：提供地图弹窗组件

```mermaid
classDiagram
class 插件基类 {
+install()
+uninstall()
}
class Swagger插件 {
+adminApiImportView()
}
class SystemInfo插件 {
+adminDashboard()
}
class Tianditu插件 {
+adminDialogMapView()
}
插件基类 <|-- Swagger插件
插件基类 <|-- SystemInfo插件
插件基类 <|-- Tianditu插件
```

**图表来源**
- [public/plugins/swagger/SwaggerPlugin.php:17-105](file://public/plugins/swagger/SwaggerPlugin.php#L17-L105)
- [public/plugins/system_info/SystemInfoPlugin.php:14-84](file://public/plugins/system_info/SystemInfoPlugin.php#L14-L84)
- [public/plugins/tianditu/TiandituPlugin.php:13-45](file://public/plugins/tianditu/TiandituPlugin.php#L13-L45)

**章节来源**
- [public/plugins/swagger/SwaggerPlugin.php:32-103](file://public/plugins/swagger/SwaggerPlugin.php#L32-L103)
- [public/plugins/system_info/SystemInfoPlugin.php:27-82](file://public/plugins/system_info/SystemInfoPlugin.php#L27-L82)
- [public/plugins/tianditu/TiandituPlugin.php:26-43](file://public/plugins/tianditu/TiandituPlugin.php#L26-L43)

### 主题系统：模板渲染与可视化设计
- 主题结构
  - 前台 default 与后台 admin_default 均提供 manifest.json 描述元信息
  - 主题包含模板文件、公共资源与可视化设计所需的数据结构
- 渲染引擎
  - 支持模板标签、变量与组件化渲染，便于拖拽式可视化设计
- 可视化设计
  - 后台主题支持自由布局与组件拖拽，提升页面定制能力

```mermaid
graph TB
MAN["主题清单(manifest.json)"] --> DEF["default(前台)"]
MAN --> ADM["admin_default(后台)"]
DEF --> TPL["模板文件与组件"]
ADM --> TPL2["模板文件与组件"]
TPL --> RENDER["模板渲染引擎"]
TPL2 --> RENDER
```

**图表来源**
- [public/themes/default/manifest.json:1-11](file://public/themes/default/manifest.json#L1-L11)
- [public/themes/admin_default/manifest.json:1-10](file://public/themes/admin_default/manifest.json#L1-L10)

**章节来源**
- [README.md:13-31](file://README.md#L13-L31)
- [public/themes/default/manifest.json:1-11](file://public/themes/default/manifest.json#L1-L11)
- [public/themes/admin_default/manifest.json:1-10](file://public/themes/admin_default/manifest.json#L1-L10)

### 数据流与控制流：从请求到响应
- 请求进入
  - 通过 public/router.php 将静态资源请求交给 Web 服务器处理，否则转交入口文件
- 应用启动
  - 入口文件加载自动加载器并启动 HTTP 应用
- 路由与调度
  - 框架根据请求路径与方法匹配路由，定位到对应控制器的动作
- 控制器处理
  - 控制器接收参数、调用服务/模型、准备数据
- 视图渲染或数据序列化
  - 前台通常渲染视图模板，API 返回 JSON
- 响应输出
  - 组装响应并返回给客户端

```mermaid
flowchart TD
IN["请求进入(public/router.php)"] --> ENT["入口文件(public/index.php 或 public/api.php)"]
ENT --> LOAD["加载自动加载器(vendor/autoload.php)"]
LOAD --> APP["启动HTTP应用(App)"]
APP --> ROUTE["路由解析与调度"]
ROUTE --> CTRL["控制器动作"]
CTRL --> MODEL["模型/服务处理"]
MODEL --> VIEW["视图渲染或JSON序列化"]
VIEW --> RESP["响应输出"]
```

**图表来源**
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [public/index.php:27-31](file://public/index.php#L27-L31)
- [public/api.php:30-34](file://public/api.php#L30-L34)

**章节来源**
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [public/index.php:27-31](file://public/index.php#L27-L31)
- [public/api.php:30-34](file://public/api.php#L30-L34)

## 依赖分析
- Composer 依赖
  - 核心包：thinkcmf/cmf-app、thinkcmf/cmf-api、thinkcmf/cmf-install、thinkcmf/cmf-appstore、thinkcmf/cmf-root
  - 运行环境：PHP >= 8.1，启用 JSON、cURL、PDO、mbstring、zip 扩展
- 自动加载映射
  - PSR-4 将 app、api、plugins、themes 映射到对应目录，确保命名空间与目录一致
- 插件与主题
  - 插件与主题作为扩展模块，通过 composer.json 的 autoload 字段被自动发现与加载

```mermaid
graph TB
ROOT["根目录 composer.json"] --> DEPS["核心依赖(thinkcmf/*)"]
ROOT --> PSR["PSR-4 映射(app, api, plugins, themes)"]
PSR --> APP["app/"]
PSR --> API["api/"]
PSR --> PLG["public/plugins/"]
PSR --> THR["public/themes/"]
```

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

## 性能考虑
- 自动加载优化
  - 合理组织命名空间与目录，减少类查找时间
  - 生产环境建议开启 opcache 与类预加载
- 路由与中间件
  - 将高频路由置于前部，避免复杂正则匹配
  - 中间件链路尽量短，避免阻塞
- 视图渲染
  - 合理拆分模板与组件，避免重复渲染
  - 对静态资源启用 CDN 与缓存头
- 插件与钩子
  - 钩子数量与执行顺序需谨慎评估，避免在热路径上执行重逻辑

[本节为通用建议，无需章节来源]

## 故障排查指南
- 入口与路由
  - 若静态资源 404 或被错误转交入口，检查 public/router.php 的条件判断
- 自动加载
  - 若类未找到，确认 composer.json 的 PSR-4 映射与命名空间一致
- 多应用入口
  - API 请求未命中 API 应用：确认是否使用 public/api.php 入口并设置了正确的 APP_NAMESPACE
- 插件钩子
  - 钩子未生效：检查插件是否已安装、钩子方法名是否正确、是否在对应生命周期被触发
- 主题渲染
  - 模板未找到或回退默认主题：检查主题清单与模板路径

**章节来源**
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/api.php:28-34](file://public/api.php#L28-L34)
- [public/plugins/swagger/SwaggerPlugin.php:32-103](file://public/plugins/swagger/SwaggerPlugin.php#L32-L103)

## 结论
ThinkCMF 的多应用架构通过前台与 API 的入口分离，实现了前后端职责的清晰划分；结合 PSR-4 自动加载与插件钩子机制，提供了良好的扩展性；主题系统与可视化设计进一步提升了前端定制能力。整体架构在保证灵活性的同时，也强调了模块化与可维护性，适合构建中大型内容管理与 API 驱动的应用平台。

[本节为总结，无需章节来源]

## 附录
- 关键入口与配置
  - 入口文件：public/index.php、public/api.php
  - 路由入口：public/router.php
  - 自动加载：composer.json（PSR-4 映射）
- 插件示例
  - Swagger 插件：API 文档与权限同步
  - SystemInfo 插件：后台仪表盘信息展示
  - Tianditu 插件：地图弹窗组件
- 主题清单
  - 前台 default 与后台 admin_default 的 manifest.json

**章节来源**
- [public/index.php:27-31](file://public/index.php#L27-L31)
- [public/api.php:30-34](file://public/api.php#L30-L34)
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/plugins/swagger/SwaggerPlugin.php:32-103](file://public/plugins/swagger/SwaggerPlugin.php#L32-L103)
- [public/plugins/system_info/SystemInfoPlugin.php:27-82](file://public/plugins/system_info/SystemInfoPlugin.php#L27-L82)
- [public/plugins/tianditu/TiandituPlugin.php:26-43](file://public/plugins/tianditu/TiandituPlugin.php#L26-L43)
- [public/themes/default/manifest.json:1-11](file://public/themes/default/manifest.json#L1-L11)
- [public/themes/admin_default/manifest.json:1-10](file://public/themes/admin_default/manifest.json#L1-L10)