简介
本文件为“通用功能模块”的API接口文档，面向所有API使用者，覆盖系统初始化、验证码、全局搜索、国际化语言包、统一错误码与响应格式等通用能力。文档以实际源码为依据，给出接口职责、请求参数、返回数据、调用流程与注意事项，帮助快速集成与排错。
项目结构
本项目采用模块化路由与控制器分层：
- API入口位于 api/ 目录，控制器按业务域划分（如 bootstrap、captcha、search 等）。
- 路由定义在 api/route/*.php，将URL映射到具体控制器方法。
- 通用基础设施位于 core/ 目录，提供统一响应封装、请求对象、验证码、错误码等。
- 业务服务多位于 front/service/ 或 core/service/，通过依赖注入在控制器中使用。
graph TB
Client["客户端"] --> Router["API路由<br/>api/route/*.php"]
Router --> CBoot["引导控制器<br/>BootstrapController"]
Router --> CCapt["验证码控制器<br/>CaptchaController"]
Router --> CSrch["搜索控制器<br/>SearchController"]
CBoot --> SBoot["引导服务<br/>BootstrapService"]
CCapt --> SReg["注册服务<br/>RegistrationService"]
CCapt --> SCap["验证码服务<br/>Captcha"]
CSrch --> SSrch["搜索服务<br/>SearchService"]
CBoot --> Resp["统一响应<br/>ApiResponse"]
CCapt --> Resp
CSrch --> Resp核心组件
- 统一响应封装：ApiResponse，用于标准化成功/失败响应体。
- 统一错误码：ApiCodes，集中管理业务错误码。
- 请求对象：Request，提供安全的输入读取与类型转换。
- 验证码服务：Captcha，负责短信/图形验证码发送与校验。
- 注册服务：RegistrationService，生成验证码表单token对。
- 搜索服务：SearchService，构建搜索结果数据。
- 引导服务：BootstrapService，构建应用启动所需的基础信息。
架构总览
API层遵循“路由→控制器→服务→基础设施”的分层模式：
- 路由层仅做路径解析与调度。
- 控制器负责参数校验、调用服务、组装响应。
- 服务层承载业务逻辑，可复用前台或核心服务。
- 基础设施提供跨模块能力（响应、错误码、验证码、请求处理）。
sequenceDiagram
participant U as "客户端"
participant R as "路由"
participant C as "控制器"
participant S as "服务"
participant I as "基础设施"
U->>R : HTTP请求
R->>C : 分发到对应控制器方法
C->>S : 执行业务逻辑
S->>I : 调用验证码/搜索/配置等能力
I-->>S : 返回结果
S-->>C : 返回业务数据
C->>I : ApiResponse : : success/error
I-->>U : 标准JSON响应详细组件分析
系统初始化接口（引导）
- 作用：获取版本信息、站点基础配置、导航列表、语言包指纹等启动所需数据。
- 路由：参考 api/route/bootstrap.php
- 控制器：BootstrapController::index
- 服务：BootstrapService::build
- 响应：统一使用 ApiResponse::success 返回数据体
调用序列
sequenceDiagram
participant U as "客户端"
participant R as "路由"
participant C as "BootstrapController"
participant S as "BootstrapService"
participant A as "ApiResponse"
U->>R : GET /bootstrap
R->>C : index()
C->>S : build()
S-->>C : 基础数据
C->>A : success(data)
A-->>U : JSON响应验证码接口
- 作用：颁发验证码表单token对；下发验证码（支持短信/图形），并返回验证所需信息。
- 路由：参考 api/route/captcha.php
- 控制器：CaptchaController
- token：颁发 captcha_token 与 storage_captcha_token
- verification：发送验证码，内部调用 Captcha::sendCaptcha
- 服务：
- RegistrationService::createApiVerificationToken
- Captcha::sendCaptcha
- 响应：成功返回 data；失败返回统一错误码与消息
调用序列
sequenceDiagram
participant U as "客户端"
participant R as "路由"
participant C as "CaptchaController"
participant RS as "RegistrationService"
participant CAP as "Captcha"
participant A as "ApiResponse"
U->>R : POST /captcha/token
R->>C : token()
C->>RS : createApiVerificationToken()
RS-->>C : {captcha_token, storage_captcha_token}
C->>A : success({captcha_token, storage_captcha_token})
A-->>U : JSON响应
U->>R : POST /captcha/verification
R->>C : verification(request)
C->>CAP : sendCaptcha(type, account, captcha_token, check, storage_captcha_token)
CAP-->>C : {code : 'success'|'fail', msg, verification?}
alt 成功
C->>A : success(verification)
A-->>U : JSON响应
else 失败
C->>A : error(ApiCodes : : BUSINESS_RULE_VIOLATION, msg, status=422)
A-->>U : JSON响应
end全局搜索接口
- 作用：根据关键词、模块、分类、分页、排序等条件查询内容。
- 路由：参考 api/route/search.php
- 控制器：SearchController::index
- 服务：SearchService::buildSearchResultData
- 参数：
- q：搜索关键词（必填校验）
- module：搜索模块（默认 product）
- category_id：分类ID
- page：页码
- by/sort：排序字段与方向
- 响应：返回标题、关键词、模块、结果集、排序选项等
调用序列
sequenceDiagram
participant U as "客户端"
participant R as "路由"
participant C as "SearchController"
participant S as "SearchService"
participant A as "ApiResponse"
U->>R : GET /search?q=...&module=...
R->>C : index(request)
C->>C : 参数校验与默认值处理
C->>S : buildSearchResultData(keyword,module,category_id,page,by,sort)
S-->>C : 搜索结果数据
C->>A : success(data)
A-->>U : JSON响应国际化支持（语言包）
- 说明：引导接口会返回语言包指纹 lang_v，便于客户端增量更新语言包。语言包具体内容通过独立 route=lang 接口下发（路由定义见 api/route/lang.php）。
- 建议：客户端首次启动时获取 lang_v，若与服务端不一致则拉取最新语言包。
文件上传接口
- 现状：当前仓库未提供统一的“文件上传”API控制器。前端与后台存在附件存储实现（如 attachment()->store/storeDraft），但API层未暴露通用上传接口。
- 建议：如需API上传能力，可在 api/controller/file 下新增控制器，复用 core/filesystem 与 attachment 能力，并遵循统一响应与错误码规范。
数据字典与系统日志
- 现状：未在API层发现专用的“数据字典”“系统日志”控制器。此类能力通常由后台管理模块提供，或通过特定业务模块接口间接获取。
- 建议：如需对外暴露，可在相应模块下新增控制器，并遵循统一响应与错误码规范。
依赖关系分析
- 控制器依赖服务：BootstrapController→BootstrapService；CaptchaController→RegistrationService、Captcha；SearchController→SearchService。
- 服务依赖基础设施：验证码服务依赖 Captcha；搜索服务依赖搜索底层能力；引导服务依赖站点配置与缓存。
- 统一响应与错误码贯穿所有控制器。
graph LR
BootCtrl["BootstrapController"] --> BootSvc["BootstrapService"]
CaptCtrl["CaptchaController"] --> RegSvc["RegistrationService"]
CaptCtrl --> CapSvc["Captcha"]
SearCtrl["SearchController"] --> SearSvc["SearchService"]
BootCtrl --> Resp["ApiResponse"]
CaptCtrl --> Resp
SearCtrl --> Resp性能注意事项
- 引导接口应缓存站点配置与导航，避免每次请求都重建。
- 验证码发送需限制频率与IP/账号维度防刷。
- 搜索接口建议结合索引与分页，减少大结果集传输。
- 语言包按需加载，客户端基于 lang_v 增量更新。
故障排查指南
- 统一错误码：使用 ApiCodes 中的常量进行错误分类，便于客户端统一处理。
- 常见错误：
- 验证码失败：检查 type、account、captcha_token、storage_captcha_token 是否匹配且有效。
- 搜索关键词非法：确保关键词符合规则，必要时清理空格与特殊字符。
- 响应格式：始终使用 ApiResponse::success/error 包装返回体，保证客户端解析一致性。
结论
本仓库已提供稳定的通用API能力：系统初始化、验证码、全局搜索与国际化语言包指纹。所有接口均遵循统一响应与错误码规范，便于客户端集成与维护。对于文件上传、数据字典、系统日志等能力，当前API层尚未暴露，可按需扩展。
附录
统一响应格式
- 成功：{ code: "success", data: {...}, message: "" }
- 失败：{ code: "error", data: {}, message: "错误描述" }
- 状态码：HTTP 200/422 等由控制器决定，业务错误码集中在 ApiCodes。
版本管理与向后兼容策略
- 版本标识：引导接口返回 version 与 lang_v，客户端据此判断是否需要升级资源。
- 兼容性：新增字段保持可选，废弃字段保留一段时间并提供迁移提示；破坏性变更通过新路由或新版本前缀发布。
- 建议：在路由或服务层增加版本协商机制，逐步淘汰旧接口。