内容管理API | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

内容管理API

简介

本文件为内容管理模块的API接口文档，覆盖前台公开接口与后台管理接口。重点包括：

文章内容管理：列表、详情、分类浏览、归档筛选等
案例展示功能：案例录入（后台）、分类浏览、详情查看等
课程管理：课程发布（后台）、章节管理（通过服务层扩展）、学习进度跟踪（通过服务层扩展）
下载中心：文件上传（后台）、版本管理（通过服务层扩展）、下载统计（访问计数）
搜索与推荐：统一搜索接口，支持按模块、分类、排序等
富文本编辑器集成与多媒体处理：通过后台表单校验与服务层完成
审核流程与权限控制：基于后台控制器+请求校验+中间件的组合机制

说明：

前台API以“只读”为主，提供列表与详情；写操作集中在后台管理端。
分页大小由配置项控制，默认值在各控制器中读取。
所有接口返回统一的成功响应封装。

项目结构

内容管理相关的路由与控制器分布在以下位置：

前台API路由：api/route/*.php
前台API控制器：api/controller/*
后台管理控制器：admin/controller/*

graph TB
subgraph "前台API"
R1["article.php"] --> C1["ArticleController"]
R2["cases.php"] --> C2["CasesController"]
R3["course.php"] --> C3["CourseController"]
R4["download.php"] --> C4["DownloadController"]
R5["search.php"] --> S1["SearchController"]
end
subgraph "后台管理"
A1["admin/article/ArticleController.php"]
A2["admin/cases/CasesController.php"]
A3["admin/course/CourseController.php"]
A4["admin/download/DownloadController.php"]
end
C1 --> |调用服务| SVC1["Front ArticleService"]
C2 --> |调用服务| SVC2["Front CasesService"]
C3 --> |调用服务| SVC3["Front CourseService"]
C4 --> |调用服务| SVC4["Front DownloadService"]
S1 --> |调用服务| SVCS["Front SearchService"]
A1 --> |调用服务| ASVC1["Admin ArticleService"]
A2 --> |调用服务| ASVC2["Admin CasesService"]
A3 --> |调用服务| ASVC3["Admin CourseService"]
A4 --> |调用服务| ASVC4["Admin DownloadService"]

核心组件

前台文章API：提供文章列表与详情，支持按分类、归档、分页查询，并记录访问次数。
前台案例API：提供案例列表与详情，支持分类、归档、分页查询，并记录访问次数。
前台课程API：提供课程列表与详情，支持分类、归档、分页查询，并记录访问次数。
前台下载API：提供下载列表与详情，支持分类、归档、分页查询，并记录访问次数。
前台搜索API：统一搜索入口，支持关键词、模块、分类、排序、分页。
后台文章管理：列表、新增、编辑、删除、批量操作，表单校验与草稿附件清理。
后台案例管理：列表、新增、编辑、删除、批量操作，表单校验与草稿附件清理。
后台课程管理：列表、新增、编辑、删除、批量操作，表单校验与草稿附件清理。
后台下载管理：列表、新增、编辑、删除、批量操作，表单校验与草稿附件清理。

架构总览

前台API采用声明式路由映射到控制器，控制器再调用对应的前台服务进行数据组装与统计。后台管理通过控制器接收表单，使用FormRequest进行字段白名单与规则校验，再交由服务层执行业务逻辑。

sequenceDiagram
participant Client as "客户端"
participant Route as "路由"
participant Ctrl as "控制器"
participant Service as "服务层"
participant Model as "模型/数据"
Client->>Route : 请求 /api/?route=article
Route->>Ctrl : 分发到 ArticleController : : index
Ctrl->>Service : buildArticleListData(...)
Service->>Model : 查询文章/分类/归档
Model-->>Service : 数据集合
Service-->>Ctrl : 列表数据
Ctrl-->>Client : ApiResponse 成功结果
Note over Client,Service : 详情接口类似，额外记录访问次数

详细组件分析

文章管理API（前台）

列表接口
- 路径：/api/?route=article
- 方法：GET
- 参数：id/category_slug（分类）、year/month（归档）、page（页码）
- 行为：解析分类ID，支持归档过滤，分页获取文章列表与分类树，返回标题、分类信息、文章列表
- 参考实现：ArticleController::index:55-89
详情接口
- 路径：/api/?route=article/{id}
- 方法：GET
- 参数：id/category_slug/slug（文章标识）
- 行为：加载文章详情，记录访问次数，附加评论列表（若启用），返回文章与自定义字段
- 参考实现：ArticleController::show:98-122

flowchart TD
Start(["进入文章列表"]) --> ParseCat["解析分类ID<br/>支持category_slug"]
ParseCat --> Archive{"是否归档?"}
Archive --> |是| UseArchive["设置catId=0"]
Archive --> |否| KeepCat["保持原分类ID"]
UseArchive --> BuildList["构建列表数据(分页)"]
KeepCat --> BuildList
BuildList --> Return["返回ApiResponse成功"]

案例展示API（前台）

列表接口
- 路径：/api/?route=cases
- 方法：GET
- 参数：id/category_id/category_slug（兼容小程序）、year/month（归档）、page
- 行为：解析分类ID，支持归档过滤，分页获取案例列表与分类树，返回标题、分类信息、案例列表
- 参考实现：CasesController::index:56-98
详情接口
- 路径：/api/?route=cases/{id}
- 方法：GET
- 参数：id/category_slug/slug
- 行为：加载案例详情，记录访问次数，附加评论列表（若启用），返回案例与自定义字段
- 参考实现：CasesController::show:106-130

sequenceDiagram
participant Client as "客户端"
participant Ctrl as "CasesController"
participant Service as "CasesService"
Client->>Ctrl : GET /api/?route=cases
Ctrl->>Service : buildCasesListData(catId, page, pageSize, archive)
Service-->>Ctrl : 案例列表
Ctrl-->>Client : ApiResponse 成功结果

课程管理API（前台）

列表接口
- 路径：/api/?route=course
- 方法：GET
- 参数：id/category_slug（分类）、year/month（归档）、page
- 行为：解析分类ID，支持归档过滤，分页获取课程列表与分类树，返回标题、分类信息、课程列表
- 参考实现：CourseController::index:56-91
详情接口
- 路径：/api/?route=course/{id}
- 方法：GET
- 参数：id/category_slug/slug
- 行为：加载课程详情，记录访问次数，附加评论列表（若启用），返回课程与自定义字段
- 参考实现：CourseController::show:99-123

下载中心API（前台）

列表接口
- 路径：/api/?route=download
- 方法：GET
- 参数：id/category_slug（分类）、year/month（归档）、page
- 行为：解析分类ID，支持归档过滤，分页获取下载列表与分类树，返回标题、分类信息、下载列表
- 参考实现：DownloadController::index:55-89
详情接口
- 路径：/api/?route=download/{id}
- 方法：GET
- 参数：id/category_slug/slug
- 行为：加载下载详情，记录访问次数，返回下载信息与分类信息
- 参考实现：DownloadController::show:97-120

搜索与推荐API（前台）

搜索接口
- 路径：/api/?route=search
- 方法：GET
- 参数：q（关键词）、module（模块，默认product）、category_id（分类）、page（页码）、by（排序字段）、sort（排序方向）
- 行为：校验关键词，选择搜索模块，调用服务层构建搜索结果，返回标题、关键词、模块、结果列表与排序选项
- 参考实现：SearchController::index:29-74

flowchart TD
Start(["进入搜索"]) --> Validate["校验关键词"]
Validate --> Module{"指定模块?"}
Module --> |是| UseModule["使用指定模块"]
Module --> |否| DefaultModule["默认模块 product"]
UseModule --> BuildResult["构建搜索结果(分页/排序)"]
DefaultModule --> BuildResult
BuildResult --> Return["返回ApiResponse成功"]

后台文章管理（增删改查）

列表：支持分类、关键词、分页
新增：表单校验（ArticleFormRequest），生成草稿令牌，插入数据
编辑：加载编辑数据，支持多语言按钮
删除：校验ID，调用服务层删除
批量操作：调用服务层批量动作
参考实现：admin/article/ArticleController:64-219

后台案例管理（增删改查）

列表：支持分类、关键词、分页
新增：表单校验（CasesFormRequest），生成草稿令牌，插入数据
编辑：加载编辑数据，支持多语言按钮
删除：校验ID，调用服务层删除
批量操作：调用服务层批量动作
参考实现：admin/cases/CasesController:65-218

后台课程管理（增删改查）

列表：支持分类、关键词、分页
新增：表单校验（CourseFormRequest），生成草稿令牌，插入数据
编辑：加载编辑数据，支持多语言按钮
删除：校验ID，调用服务层删除
批量操作：调用服务层批量动作
参考实现：admin/course/CourseController:65-218

后台下载管理（增删改查）

列表：支持分类、关键词、分页
新增：表单校验（DownloadFormRequest），生成草稿令牌，插入数据
编辑：加载编辑数据，支持多语言按钮
删除：校验ID，调用服务层删除
批量操作：调用服务层批量动作
参考实现：admin/download/DownloadController:65-218

依赖分析

路由到控制器：每个资源模块在api/route下声明资源路由，仅暴露index/show两个动作，保证前台API最小化。
控制器到服务：控制器负责参数解析、分页、分类与归档处理，以及访问统计；具体数据组装与业务规则在服务层。
后台控制器到服务：后台控制器负责表单校验（FormRequest）、草稿令牌处理、视图渲染与重定向；业务逻辑在服务层。
外部依赖：语言包、配置项（分页大小）、评论模块（可选）。

graph LR
Route["路由"] --> Controller["控制器"]
Controller --> Service["服务层"]
Service --> Model["模型/数据"]
Controller --> Config["配置(分页)"]
Controller --> Lang["语言包"]
Controller --> Comment["评论模块(可选)"]

性能考虑

分页控制：各控制器从配置读取分页大小，避免一次性加载过多数据。
归档过滤：通过日期参数减少不必要的数据扫描。
访问统计：详情接口对点击数进行增量更新，注意在高并发场景下的写入压力。
分类树：按需加载分类树，避免全量加载。
评论模块：仅在启用时加载，降低无关开销。

故障排查指南

页面错误：当分类或文章/案例/课程/下载不存在时，会抛出领域异常，提示页面错误。检查传入的id/category_slug/slug是否正确。
非法操作：后台编辑/更新/删除要求有效的ID与POST请求，否则抛出非法操作异常。确认请求方法与参数。
关键词无效：搜索接口对关键词进行校验，非法关键词将返回错误。检查q参数格式。
评论模块未启用：若评论模块未启用，详情接口不会返回评论数据，属正常现象。

结论

本模块通过清晰的前后台分离与声明式路由，提供了稳定的内容管理API。前台侧重只读与统计，后台负责完整的CRUD与校验。服务层承载业务规则，便于扩展章节管理与学习进度等功能。建议在生产环境中结合缓存与异步任务优化访问统计与搜索性能。

附录

富文本编辑器集成：后台控制器在创建/编辑表单时注入草稿令牌与多语言按钮，配合前端编辑器完成富文本内容的提交与保存。
多媒体内容处理：通过附件系统与存储服务层处理图片、视频等多媒体资源，确保内容与媒体关联一致。
审核流程与权限控制：后台控制器依赖表单校验与中间件（如权限、CSRF）保障数据安全；建议在服务层增加审核状态流转与角色权限判断。

添加日期：2026-10-05