# API 开发

<cite>
**本文引用的文件**
- [public/api.php](file://public/api.php)
- [public/router.php](file://public/router.php)
- [composer.json](file://composer.json)
- [README.md](file://README.md)
- [public/plugins/swagger/SwaggerPlugin.php](file://public/plugins/swagger/SwaggerPlugin.php)
- [public/plugins/swagger/composer.json](file://public/plugins/swagger/composer.json)
- [public/plugins/swagger/swagger/OpenApiSpec.php](file://public/plugins/swagger/swagger/OpenApiSpec.php)
- [public/plugins/swagger/controller/ApiAdminIndexController.php](file://public/plugins/swagger/controller/ApiAdminIndexController.php)
- [public/themes/admin_default/admin/rbac/api_authorize.html](file://public/themes/admin_default/admin/rbac/api_authorize.html)
- [public/static/js/admin.js](file://public/static/js/admin.js)
</cite>

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

## 简介
本指南面向 ThinkCMF 的 API 开发者，系统讲解 RESTful API 的设计与实现、API 应用结构与入口、Swagger 文档集成与在线测试、认证与授权机制、最佳实践（错误处理、数据验证、版本管理）、以及从接口设计到测试部署的完整流程，并给出性能优化与监控建议。

## 项目结构
- API 应用位于独立命名空间 api 下，入口文件为 public/api.php。
- ThinkCMF 使用多应用架构，PSR-4 自动加载将 api 命名空间映射到 api/ 目录。
- Swagger 插件提供 OpenAPI 注解、文档生成与后台 API 导入能力。
- 后台 JS 提供对 RESTful API 的调用支持与全局 API 根路径配置。

```mermaid
graph TB
A["浏览器/客户端"] --> B["public/api.php<br/>API 应用入口"]
B --> C["多应用加载<br/>PSR-4: api\\ => api/"]
C --> D["API 控制器与路由"]
D --> E["Swagger 插件<br/>OpenAPI 注解/生成/导入"]
D --> F["后台 RBAC 权限<br/>api_authorize.html"]
D --> G["后台 JS 调用 REST API<br/>admin.js"]
```

图表来源
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [composer.json:46-56](file://composer.json#L46-L56)

章节来源
- [public/api.php:15-30](file://public/api.php#L15-L30)
- [composer.json:46-56](file://composer.json#L46-L56)

## 核心组件
- API 应用入口与命名空间
  - public/api.php 定义 CMF 根目录、数据目录、应用目录与命名空间 APP_NAMESPACE 为 api，随后加载 vendor 并执行 HTTP 应用。
- 多应用与自动加载
  - composer.json 中 PSR-4 将 api 命名空间映射至 api/，使 API 控制器按命名空间组织。
- Swagger 插件
  - 提供 OpenAPI 注解、文档生成与后台 API 导入，支持 Attributes 与 Annotations。
- 后台权限与调用
  - 后台模板中可基于 RBAC 对 API 授权；admin.js 支持 RESTful API 调用，可通过全局变量配置 API 根路径。

章节来源
- [public/api.php:15-30](file://public/api.php#L15-L30)
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/plugins/swagger/composer.json:12-15](file://public/plugins/swagger/composer.json#L12-L15)
- [public/themes/admin_default/admin/rbac/api_authorize.html:23-42](file://public/themes/admin_default/admin/rbac/api_authorize.html#L23-L42)
- [public/static/js/admin.js:606-639](file://public/static/js/admin.js#L606-L639)

## 架构总览
ThinkCMF 的 API 架构以多应用为核心，API 应用通过独立入口与命名空间隔离，结合 Swagger 插件实现文档化与自动化导入，配合后台 RBAC 实现细粒度权限控制，前端通过 admin.js 统一发起 RESTful 请求。

```mermaid
graph TB
subgraph "API 应用层"
API["public/api.php"]
CTRL["API 控制器"]
SW["Swagger 注解/生成"]
end
subgraph "后台管理"
RBAC["RBAC 权限配置<br/>api_authorize.html"]
ADMINJS["后台 JS 调用<br/>admin.js"]
end
API --> CTRL
CTRL --> SW
RBAC --> CTRL
ADMINJS --> CTRL
```

图表来源
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [public/plugins/swagger/swagger/OpenApiSpec.php:1-72](file://public/plugins/swagger/swagger/OpenApiSpec.php#L1-L72)
- [public/themes/admin_default/admin/rbac/api_authorize.html:23-42](file://public/themes/admin_default/admin/rbac/api_authorize.html#L23-L42)
- [public/static/js/admin.js:606-639](file://public/static/js/admin.js#L606-L639)

## 详细组件分析

### API 应用入口与路由
- 入口文件 public/api.php
  - 定义常量：CMF_ROOT、CMF_DATA、APP_PATH、WEB_ROOT。
  - 设置命名空间 APP_NAMESPACE 为 api。
  - 加载 vendor 自动加载器并执行 HTTP 应用，响应后结束。
- 路由转发
  - public/router.php 将未命中静态资源的请求转发至 index.php，确保 ThinkCMF 路由体系正常工作。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Entry as "public/api.php"
participant Loader as "自动加载器"
participant Http as "HTTP 应用"
participant Ctrl as "API 控制器"
Client->>Entry : "HTTP 请求"
Entry->>Loader : "require vendor/autoload.php"
Entry->>Http : "创建并运行 HTTP 应用"
Http->>Ctrl : "匹配路由并执行控制器"
Ctrl-->>Http : "返回响应对象"
Http-->>Client : "发送响应并结束"
```

图表来源
- [public/api.php:30-41](file://public/api.php#L30-L41)

章节来源
- [public/api.php:15-30](file://public/api.php#L15-L30)
- [public/api.php:30-41](file://public/api.php#L30-L41)
- [public/router.php:13-19](file://public/router.php#L13-L19)

### Swagger 文档集成与使用
- 插件信息与依赖
  - Swagger 插件信息与版本在 SwaggerPlugin.php 中定义；插件 composer.json 依赖 zircote/swagger-php 与 doctrine/annotations。
- OpenAPI 规范与安全方案
  - OpenApiSpec.php 定义了 Info、Server、SecurityScheme、Parameter、Response 等 OpenAPI 元数据，声明了 Authorization、XX-Device-Type、XX-Api-Version 等头部安全方案。
- 文档生成与后台导入
  - ApiAdminIndexController::importApi 通过 OpenApi::generate 生成 OpenAPI 规范，遍历 paths，筛选 admin 前缀的 API，导入后台 admin_api 表与 auth_rule 权限规则，便于 RBAC 授权与测试。

```mermaid
sequenceDiagram
participant Admin as "后台管理员"
participant Ctrl as "ApiAdminIndexController"
participant Gen as "OpenApi : : generate"
participant DB as "数据库(admin_api/auth_rule)"
participant View as "widget.html"
Admin->>Ctrl : "点击导入后台API"
Ctrl->>Gen : "生成 OpenAPI 规范(JSON)"
Gen-->>Ctrl : "返回 JSON 规范"
Ctrl->>DB : "遍历 paths 并写入 admin_api/auth_rule"
DB-->>Ctrl : "写入完成"
Ctrl-->>Admin : "渲染导入成功视图(widget.html)"
```

图表来源
- [public/plugins/swagger/controller/ApiAdminIndexController.php:25-43](file://public/plugins/swagger/controller/ApiAdminIndexController.php#L25-L43)
- [public/plugins/swagger/SwaggerPlugin.php:44-103](file://public/plugins/swagger/SwaggerPlugin.php#L44-L103)
- [public/plugins/swagger/swagger/OpenApiSpec.php:6-43](file://public/plugins/swagger/swagger/OpenApiSpec.php#L6-L43)

章节来源
- [public/plugins/swagger/composer.json:12-15](file://public/plugins/swagger/composer.json#L12-L15)
- [public/plugins/swagger/swagger/OpenApiSpec.php:6-43](file://public/plugins/swagger/swagger/OpenApiSpec.php#L6-L43)
- [public/plugins/swagger/controller/ApiAdminIndexController.php:25-43](file://public/plugins/swagger/controller/ApiAdminIndexController.php#L25-L43)
- [public/plugins/swagger/SwaggerPlugin.php:44-103](file://public/plugins/swagger/SwaggerPlugin.php#L44-L103)

### 认证与授权机制
- 安全方案与头部字段
  - OpenApiSpec.php 声明了 Authorization、XX-Device-Type、XX-Api-Version 三个头部安全方案，作为 API 调用的必要参数。
- 后台权限配置
  - 后台模板 api_authorize.html 展示了按标签分组的 API 列表，支持勾选授权给角色，形成细粒度的权限控制。
- 后台 JS 调用
  - admin.js 在后台页面中封装了 RESTful API 调用逻辑，支持根据全局变量 GV.API_ROOT 拼接 API 根路径，统一处理响应与跳转。

```mermaid
flowchart TD
Start(["开始"]) --> CheckHeaders["校验请求头<br/>Authorization/XX-Device-Type/XX-Api-Version"]
CheckHeaders --> HeadersOK{"头部有效？"}
HeadersOK --> |否| Deny["拒绝访问/返回鉴权错误"]
HeadersOK --> |是| LoadRules["加载权限规则<br/>RBAC: auth_rule"]
LoadRules --> MatchRule{"匹配到授权规则？"}
MatchRule --> |否| Deny
MatchRule --> |是| Allow["允许访问并执行控制器"]
Deny --> End(["结束"])
Allow --> End
```

图表来源
- [public/plugins/swagger/swagger/OpenApiSpec.php:18-37](file://public/plugins/swagger/swagger/OpenApiSpec.php#L18-L37)
- [public/themes/admin_default/admin/rbac/api_authorize.html:23-42](file://public/themes/admin_default/admin/rbac/api_authorize.html#L23-L42)
- [public/static/js/admin.js:606-639](file://public/static/js/admin.js#L606-L639)

章节来源
- [public/plugins/swagger/swagger/OpenApiSpec.php:18-37](file://public/plugins/swagger/swagger/OpenApiSpec.php#L18-L37)
- [public/themes/admin_default/admin/rbac/api_authorize.html:23-42](file://public/themes/admin_default/admin/rbac/api_authorize.html#L23-L42)
- [public/static/js/admin.js:606-639](file://public/static/js/admin.js#L606-L639)

### API 设计与实现最佳实践
- 资源命名与 HTTP 方法
  - 使用名词复数形式表示资源集合，路径中使用连字符或下划线保持一致性；GET/POST/PUT/PATCH/DELETE 映射查询、创建、完整更新、增量更新、删除。
- 状态码规范
  - 成功：200/201/204；参数错误：400；未授权/鉴权失败：401；禁止访问：403；资源不存在：404；冲突：409；服务器错误：500。
- 错误处理与数据验证
  - 使用 ThinkPHP 验证器进行输入校验；统一错误响应结构，包含 code/msg/data 字段；在基础控制器中实现统一的验证失败处理方法。
- 版本管理
  - 通过 XX-Api-Version 头部指定 API 版本，服务端据此选择对应版本的控制器与行为；OpenApiSpec.php 中声明默认版本与服务器地址前缀。
- 跨域与安全
  - ThinkCMF 已优化 API 跨域处理；生产环境建议开启 HTTPS、限制来源域名、实施 CORS 策略。

章节来源
- [README.md:103-113](file://README.md#L103-L113)
- [public/plugins/swagger/swagger/OpenApiSpec.php:6-43](file://public/plugins/swagger/swagger/OpenApiSpec.php#L6-L43)

### 从设计到测试部署的完整流程
- 设计阶段
  - 明确资源与动作，设计路径与方法；在控制器上使用 Swagger 注解描述接口（tags、path、summary、responses、parameters）。
- 实现阶段
  - 在 api 命名空间下创建控制器与动作；实现业务逻辑与数据验证；确保响应结构一致。
- 文档与测试
  - 通过 Swagger 插件生成 OpenAPI 规范；在后台导入 API 至 admin_api 与 auth_rule；使用 Swagger UI 在线测试接口。
- 部署与监控
  - 配置 Web 服务器重写规则；在生产环境启用调试关闭与日志记录；对高频接口进行缓存与限流；监控响应时间与错误率。

章节来源
- [public/plugins/swagger/controller/ApiAdminIndexController.php:25-43](file://public/plugins/swagger/controller/ApiAdminIndexController.php#L25-L43)
- [public/plugins/swagger/SwaggerPlugin.php:44-103](file://public/plugins/swagger/SwaggerPlugin.php#L44-L103)

## 依赖关系分析
- Composer 自动加载
  - PSR-4 将 api 命名空间映射到 api/，使 API 控制器按命名空间组织与加载。
- Swagger 插件依赖
  - zircote/swagger-php 与 doctrine/annotations 提供注解解析与 OpenAPI 规范生成能力。
- 运行时依赖
  - ThinkCMF 多应用框架、HTTP 应用执行、数据库与权限表。

```mermaid
graph LR
CMF["ThinkCMF 核心"] --> API["API 应用(api)"]
API --> CTRL["API 控制器"]
API --> SW["Swagger 插件"]
SW --> GEN["OpenAPI 生成器"]
SW --> DB["后台权限表(admin_api/auth_rule)"]
```

图表来源
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/plugins/swagger/composer.json:12-15](file://public/plugins/swagger/composer.json#L12-L15)

章节来源
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/plugins/swagger/composer.json:12-15](file://public/plugins/swagger/composer.json#L12-L15)

## 性能考虑
- 路由与中间件
  - 合理拆分控制器与中间件，避免在路由层做复杂逻辑；使用缓存中间件缓存热点数据。
- 数据访问
  - 使用模型缓存与索引优化查询；批量读取与延迟加载减少 N+1 查询。
- 响应优化
  - 对大对象分页返回；启用 gzip 压缩；合理设置 ETag/Last-Modified 实现条件请求。
- 并发与限流
  - 对外部接口调用设置超时与重试；对敏感接口实施限流与 IP 白名单。
- 监控与日志
  - 记录慢查询与错误堆栈；对关键接口埋点监控 QPS、P95 延迟与错误率。

## 故障排查指南
- API 无法访问
  - 检查 public/api.php 是否正确加载 vendor；确认 Web 服务器已将请求指向 public/ 并启用重写。
- Swagger 文档未生成
  - 确认 Swagger 插件已安装且 composer 依赖已安装；检查注解是否符合规范。
- 权限不足
  - 检查后台 RBAC 中是否已将 API 导入 admin_api 与 auth_rule；确认角色已授权。
- 跨域问题
  - 确认已按 README 优化跨域处理；检查浏览器控制台 Network 面板中的 CORS 响应头。

章节来源
- [public/api.php:30-41](file://public/api.php#L30-L41)
- [README.md:202](file://README.md#L202)

## 结论
ThinkCMF 的 API 开发以多应用与 Swagger 为核心，结合后台 RBAC 实现完善的文档化与权限控制。遵循 RESTful 设计、统一错误与版本管理、配合性能优化与监控，可构建稳定、可维护、易测试的 API 体系。

## 附录
- 参考文档与链接
  - OpenAPI 规范与 Swagger-PHP 文档见 README 中 Swagger 相关章节。

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