# API 开发流程

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

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

## 引言
本指南面向 ThinkCMF 的 API 开发实践，覆盖从需求分析到部署运维的完整生命周期。重点包括：
- API 控制器的创建与组织方式（命名规范、文件结构、代码模板）
- 新端点开发流程（请求参数处理、响应数据结构）
- 错误处理最佳实践（异常捕获、错误码与用户友好提示）
- API 版本管理策略（向后兼容与废弃处理）
- 代码质量保障（单元测试、集成测试、性能测试）
- 部署与运维（环境配置、监控告警、故障排查）

ThinkCMF 在 README 中明确支持 RESTful API 与 Swagger 文档能力，并通过插件化机制提供 OpenAPI 规范扫描与可视化文档。

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

## 项目结构
- 入口与路由
  - public/api.php 定义 API 应用命名空间为 api，并加载自动加载器后执行 HTTP 应用。
  - public/router.php 将未命中静态资源的请求交由 public/index.php 处理，实现 URL 美化与统一入口。
- 插件与 Swagger
  - public/plugins/swagger 提供 OpenAPI 扫描、生成与前端可视化展示能力。
  - public/plugins/system_info 提供一个基于 REST 基类的示例 API 控制器。
- 前端交互
  - public/static/js/admin.js 提供与 REST API 交互的通用逻辑（含全局 API 根路径、方法与结果处理）。

```mermaid
graph TB
A["public/api.php<br/>API 应用入口"] --> B["vendor/autoload.php<br/>自动加载"]
B --> C["App()->http->run()<br/>执行 HTTP 应用"]
C --> D["public/index.php<br/>统一入口"]
D --> E["public/router.php<br/>URL 美化路由"]
E --> F["插件 Swagger<br/>扫描与文档"]
E --> G["插件 System Info<br/>示例 API 控制器"]
H["public/static/js/admin.js<br/>前端交互"] --> C
```

**图示来源**
- [public/api.php:30-35](file://public/api.php#L30-L35)
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [public/plugins/swagger/controller/ApiAdminIndexController.php:15-16](file://public/plugins/swagger/controller/ApiAdminIndexController.php#L15-L16)
- [public/plugins/system_info/controller/ApiIndexController.php:15](file://public/plugins/system_info/controller/ApiIndexController.php#L15)

**章节来源**
- [public/api.php:28](file://public/api.php#L28)
- [public/router.php:13-19](file://public/router.php#L13-L19)
- [composer.json:46-56](file://composer.json#L46-L56)

## 核心组件
- API 入口与命名空间
  - public/api.php 将 APP_NAMESPACE 设为 api，确保 API 应用按 api 命名空间加载。
- Swagger 插件
  - OpenApi::generate 扫描 api 应用、vendor/thinkcmf/cmf-api 以及已启用插件的 controller 与 swagger 目录，生成 OpenAPI 规范。
  - ApiAdminIndexController::importApi 将扫描到的后台 API 导入到 admin_api 与 auth_rule 表，便于权限控制。
  - IndexController::config 返回 JSON 规范，供 Swagger UI 使用。
  - OpenApiSpec.php 定义 OpenAPI 基础信息、服务器地址、安全方案与通用参数/响应。
- 示例 API 控制器
  - System Info 插件的 ApiIndexController 展示了基于 REST 基类的 GET 接口实现与统一响应结构。
- 前端交互
  - admin.js 统一处理表单提交、REST API 调用、结果提示与跳转。

**章节来源**
- [public/api.php:28](file://public/api.php#L28)
- [public/plugins/swagger/service/OpenApi.php:10-64](file://public/plugins/swagger/service/OpenApi.php#L10-L64)
- [public/plugins/swagger/controller/ApiAdminIndexController.php:44-102](file://public/plugins/swagger/controller/ApiAdminIndexController.php#L44-L102)
- [public/plugins/swagger/controller/IndexController.php:29-39](file://public/plugins/swagger/controller/IndexController.php#L29-L39)
- [public/plugins/swagger/swagger/OpenApiSpec.php:6-68](file://public/plugins/swagger/swagger/OpenApiSpec.php#L6-L68)
- [public/plugins/system_info/controller/ApiIndexController.php:44-77](file://public/plugins/system_info/controller/ApiIndexController.php#L44-L77)
- [public/static/js/admin.js:235-639](file://public/static/js/admin.js#L235-L639)

## 架构总览
ThinkCMF 的 API 开发采用多应用架构与插件化扩展。API 请求通过 public/api.php 进入，经由框架路由与控制器处理，Swagger 插件负责扫描与生成 OpenAPI 规范，前端通过 admin.js 统一发起 REST 请求并处理响应。

```mermaid
graph TB
subgraph "前端"
UI["浏览器/移动端"]
JS["admin.js<br/>统一 AJAX/表单提交"]
end
subgraph "后端"
API["public/api.php<br/>API 应用入口"]
CTRL["控制器<br/>业务逻辑"]
SWAGGER["Swagger 插件<br/>扫描/生成/文档"]
DB["数据库<br/>admin_api/auth_rule"]
end
UI --> JS
JS --> API
API --> CTRL
CTRL --> DB
SWAGGER --> API
SWAGGER --> DB
```

**图示来源**
- [public/api.php:30-35](file://public/api.php#L30-L35)
- [public/plugins/swagger/service/OpenApi.php:10-64](file://public/plugins/swagger/service/OpenApi.php#L10-L64)
- [public/plugins/swagger/controller/ApiAdminIndexController.php:44-102](file://public/plugins/swagger/controller/ApiAdminIndexController.php#L44-L102)
- [public/static/js/admin.js:235-639](file://public/static/js/admin.js#L235-L639)

## 详细组件分析

### Swagger OpenAPI 扫描与导入
- 扫描范围
  - 动态扫描 api 应用、vendor/thinkcmf/cmf-api 内置应用、已启用插件的 controller 与 swagger 目录。
- 导入逻辑
  - 将后台 API 导入 admin_api 表，同时更新 auth_rule 权限规则，便于后台 RBAC 授权。
- 文档展示
  - IndexController::config 输出 JSON 规范，swagger.html 通过 SwaggerUIBundle 加载并渲染。

```mermaid
sequenceDiagram
participant Admin as "后台管理员"
participant Ctrl as "ApiAdminIndexController"
participant Service as "OpenApi : : generate"
participant DB as "admin_api/auth_rule"
Admin->>Ctrl : "触发导入后台API"
Ctrl->>Service : "扫描并生成 OpenAPI 规范"
Service-->>Ctrl : "返回规范数组(paths)"
loop 遍历 paths 与 methods
Ctrl->>DB : "查询/插入/更新 admin_api"
Ctrl->>DB : "查询/更新 auth_rule"
end
Ctrl-->>Admin : "导入成功提示"
```

**图示来源**
- [public/plugins/swagger/controller/ApiAdminIndexController.php:44-102](file://public/plugins/swagger/controller/ApiAdminIndexController.php#L44-L102)
- [public/plugins/swagger/service/OpenApi.php:10-64](file://public/plugins/swagger/service/OpenApi.php#L10-L64)

**章节来源**
- [public/plugins/swagger/controller/ApiAdminIndexController.php:44-102](file://public/plugins/swagger/controller/ApiAdminIndexController.php#L44-L102)
- [public/plugins/swagger/service/OpenApi.php:10-64](file://public/plugins/swagger/service/OpenApi.php#L10-L64)
- [public/plugins/swagger/controller/IndexController.php:29-39](file://public/plugins/swagger/controller/IndexController.php#L29-L39)
- [public/plugins/swagger/view/swagger.html:36-56](file://public/plugins/swagger/view/swagger.html#L36-L56)

### 示例 API 控制器（System Info）
- 继承关系
  - ApiIndexController 继承 PluginRestBaseController，遵循 ThinkCMF REST 基类约定。
- 请求与响应
  - GET /plugin/system_info/api_admin_index/index 返回统一结构的响应数据。
- Swagger 注解
  - 使用 OA\Get/OA\Response/OA\JsonContent 等注解描述接口行为与示例。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Ctrl as "ApiIndexController"
participant DB as "Db 查询"
participant Resp as "统一响应"
Client->>Ctrl : "GET /plugin/system_info/api_admin_index/index"
Ctrl->>DB : "查询数据库信息"
DB-->>Ctrl : "返回查询结果"
Ctrl->>Resp : "封装统一响应结构"
Resp-->>Client : "JSON 响应"
```

**图示来源**
- [public/plugins/system_info/controller/ApiIndexController.php:44-77](file://public/plugins/system_info/controller/ApiIndexController.php#L44-L77)

**章节来源**
- [public/plugins/system_info/controller/ApiIndexController.php:15-16](file://public/plugins/system_info/controller/ApiIndexController.php#L15-L16)
- [public/plugins/system_info/controller/ApiIndexController.php:26-42](file://public/plugins/system_info/controller/ApiIndexController.php#L26-L42)
- [public/plugins/system_info/controller/ApiIndexController.php:44-77](file://public/plugins/system_info/controller/ApiIndexController.php#L44-L77)

### 前端交互与统一 AJAX
- 全局变量
  - admin.js 通过 GV.API_ROOT 指定不同 API 命名空间的基础路径，支持多应用 API 根。
- 表单提交
  - 统一处理 beforeSubmit、success、错误提示与跳转逻辑，确保与后端统一响应结构一致。
- 方法与 URL 解析
  - 自动拼接 API 根路径，支持自定义 method 与命名空间。

```mermaid
flowchart TD
Start(["开始"]) --> GetCfg["读取按钮/表单 data-api 与 method"]
GetCfg --> BuildURL["拼接 API 根路径(GV.API_ROOT)"]
BuildURL --> Ajax["$.ajax 发起请求"]
Ajax --> Success{"响应 code==1?"}
Success --> |是| Notify["提示成功并执行跳转"]
Success --> |否| Alert["提示错误消息"]
Notify --> End(["结束"])
Alert --> End
```

**图示来源**
- [public/static/js/admin.js:235-639](file://public/static/js/admin.js#L235-L639)

**章节来源**
- [public/static/js/admin.js:235-639](file://public/static/js/admin.js#L235-L639)

### API 控制器创建与组织规范
- 命名与文件结构
  - 控制器位于插件或应用的 controller 目录，遵循 PSR-4 命名空间映射。
  - API 控制器建议继承 REST 基类（如 PluginRestBaseController），以获得统一的响应与校验能力。
- 代码模板要点
  - 使用 OA 注解声明接口元数据（tags、path、summary、responses 等）。
  - 在控制器方法内进行参数校验、业务处理与统一响应封装。
  - 对于后台 API，结合 Swagger 插件扫描与导入，纳入权限体系。

**章节来源**
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/plugins/system_info/controller/ApiIndexController.php:15-16](file://public/plugins/system_info/controller/ApiIndexController.php#L15-L16)
- [public/plugins/swagger/controller/ApiAdminIndexController.php:25-42](file://public/plugins/swagger/controller/ApiAdminIndexController.php#L25-L42)

## 依赖分析
- 自动加载与命名空间
  - composer.json 定义 psr-4 映射，将 api 命名空间指向 app 或 api 目录，确保 API 控制器可被正确加载。
- Swagger 扫描依赖
  - OpenApi::generate 依赖插件启用状态与目录存在性，动态扩展扫描路径。
- 前端依赖
  - admin.js 依赖全局变量 GV.API_ROOT 与后端统一响应结构。

```mermaid
graph LR
COM["composer.json<br/>PSR-4 映射"] --> API["API 控制器命名空间"]
SWG["OpenApi::generate<br/>扫描路径"] --> API
API --> RESP["统一响应结构"]
RESP --> JS["admin.js<br/>AJAX 处理"]
```

**图示来源**
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/plugins/swagger/service/OpenApi.php:10-64](file://public/plugins/swagger/service/OpenApi.php#L10-L64)
- [public/static/js/admin.js:235-639](file://public/static/js/admin.js#L235-L639)

**章节来源**
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/plugins/swagger/service/OpenApi.php:10-64](file://public/plugins/swagger/service/OpenApi.php#L10-L64)
- [public/static/js/admin.js:235-639](file://public/static/js/admin.js#L235-L639)

## 性能考虑
- 路由与入口
  - 使用 public/router.php 实现 URL 美化，减少不必要的重定向与额外处理。
- Swagger 扫描
  - OpenApi::generate 会扫描多个目录，建议在生产环境避免频繁触发扫描，可通过缓存或定时任务生成规范文件。
- 前端请求
  - admin.js 统一处理请求与响应，避免重复的 DOM 操作与网络请求，提升交互体验。

[本节为通用指导，无需特定文件引用]

## 故障排查指南
- Swagger 文档不可见
  - 确认已安装并启用 Swagger 插件，且后台开启调试或管理员登录状态。
  - 参考 swagger.html 的授权与跨域设置，确保前端可访问 /plugin/swagger/Index/config。
- API 权限未生效
  - 检查 ApiAdminIndexController::importApi 是否成功导入后台 API 到 admin_api 与 auth_rule。
  - 在后台 RBAC 授权页面核对权限分配与角色绑定。
- 前端请求失败
  - 确认 GV.API_ROOT 已正确配置，且与控制器命名空间匹配。
  - 检查后端响应结构是否符合 admin.js 的期望（code、msg、url 等字段）。

**章节来源**
- [public/plugins/swagger/view/swagger.html:36-56](file://public/plugins/swagger/view/swagger.html#L36-L56)
- [public/plugins/swagger/controller/ApiAdminIndexController.php:44-102](file://public/plugins/swagger/controller/ApiAdminIndexController.php#L44-L102)
- [public/themes/admin_default/admin/rbac/api_authorize.html:41-65](file://public/themes/admin_default/admin/rbac/api_authorize.html#L41-L65)
- [public/static/js/admin.js:235-639](file://public/static/js/admin.js#L235-L639)

## 结论
通过 ThinkCMF 的多应用架构与插件化扩展，API 开发具备清晰的入口、统一的控制器基类与完善的 Swagger 文档能力。遵循本文的命名规范、组织方式与最佳实践，可高效完成从需求到上线的全流程开发，并确保版本演进与运维稳定性。

[本节为总结性内容，无需特定文件引用]

## 附录

### API 错误处理最佳实践
- 异常捕获
  - 在控制器层捕获业务异常，转换为统一响应结构，避免泄露内部错误细节。
- 错误码与用户提示
  - 使用统一的响应字段（如 code、msg、data），前端根据 code 判断成功/失败并提示用户。
- 日志与追踪
  - 记录关键错误日志，便于定位问题与审计。

[本节为通用指导，无需特定文件引用]

### API 版本管理策略
- 版本标识
  - 通过 OpenApiSpec.php 中的安全方案与服务器地址，统一管理 XX-Api-Version 头部与 /api 基础路径。
- 向后兼容
  - 新增字段采用可选策略，避免破坏现有客户端；变更字段需在新版本中提供过渡期。
- 废弃处理
  - 对于废弃接口，保留一段时间并提供迁移指引，逐步引导客户端切换至新接口。

**章节来源**
- [public/plugins/swagger/swagger/OpenApiSpec.php:15-31](file://public/plugins/swagger/swagger/OpenApiSpec.php#L15-L31)

### 代码质量保证
- 单元测试
  - 针对控制器方法进行输入校验、业务逻辑与响应结构的断言。
- 集成测试
  - 使用 Swagger 规范驱动接口联调，确保各端点行为一致。
- 性能测试
  - 对热点接口进行压测，关注响应时间与吞吐量，必要时引入缓存与异步处理。

[本节为通用指导，无需特定文件引用]

### 部署与运维指南
- 环境配置
  - 参考 README 的环境推荐与最低要求，确保 PHP、MySQL 与 rewrite 已正确配置。
- 监控告警
  - 关注 API 响应时间、错误率与数据库连接池使用情况，设置阈值告警。
- 故障排查
  - 结合 Swagger 文档核对请求参数与响应结构，利用日志与权限配置快速定位问题。

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