简介
本文面向开发者，系统化梳理 DouPHP 文章管理模块的后台与前台实现，覆盖文章的创建、编辑、删除、列表查询、分类体系、SEO 优化、富文本内容处理、图片上传、访问统计等。文档同时给出关键流程的时序图与流程图，并提供可操作的 API 参考与扩展建议，帮助快速定位问题与二次开发。
项目结构
文章模块按“后台管理”和“前台展示”双端组织，采用控制器-服务-模型的分层设计：
- 后台管理（admin）
- 控制器：文章与分类的增删改查入口
- 服务：业务编排（表单数据组装、附件处理、审计日志）
- 模型：ORM 映射、筛选器、排序、关联
- 前台展示（front）
- 控制器：路由解析、页面数据组装、SEO 与导航
- 服务：列表/详情数据构建、点击量记录
- 模型：发布状态过滤、归档筛选、多语言、URL 生成、相关文推荐
graph TB
subgraph "后台"
AC["Admin ArticleController"]
ASvc["Admin ArticleService"]
AModel["Admin Article Model"]
CatC["Admin CategoryController"]
CatM["Admin Category Model"]
end
subgraph "前台"
FC["Front ArticleController"]
FSvc["Front ArticleService"]
FModel["Front Article Model"]
FCatM["Front Category Model"]
end
AC --> ASvc
ASvc --> AModel
CatC --> CatM
FC --> FSvc
FSvc --> FModel
FC --> FCatM核心组件
- 后台文章控制器：负责列表、新增、编辑、更新、删除、批量操作；通过 Request 校验后调用服务完成业务。
- 后台文章服务：封装列表数据构建、新增/更新/删除/批量逻辑，协调附件存储、XSS 清洗、Markdown 渲染、审计日志。
- 后台文章模型：声明表字段白名单、casts、关联分类、关键词筛选、默认排序。
- 前台文章控制器：解析路由（分类/归档/详情），组装 SEO、导航、面包屑，调用服务获取数据并渲染模板。
- 前台文章服务：构建列表/详情数据，Markdown 渲染，分类信息查询，点击量记录。
- 前台文章模型：已发布过滤、归档时间窗筛选、主图过滤、默认排序、多语言与 URL 生成。
- 分类模型（前后端）：树形结构、层级关系、同步到导航等能力。
架构总览
文章模块遵循“请求进入控制器 -> 服务编排 -> 模型持久化/查询 -> 视图渲染”的标准流程。后台侧重内容生产与审核，前台侧重内容消费与 SEO。
sequenceDiagram
participant Admin as "后台控制器"
participant Svc as "后台服务"
participant Model as "后台模型"
participant Att as "附件服务"
participant Aud as "审计日志"
Admin->>Svc : 提交新增/更新
Svc->>Att : 清洗并存储正文图片
Svc->>Model : 写入文章数据
Model-->>Svc : 返回主键/结果
Svc->>Aud : 记录操作日志
Svc-->>Admin : 重定向/响应详细组件分析
后台文章 CRUD
- 列表：支持按分类、关键词、分页、默认排序（手动排序开关影响）。
- 新增：草稿附件清理、Markdown 正文 XSS 清洗、远程图片本地化、主图上传、草稿认领、审计日志。
- 编辑：读取原始列值并按表单语义格式化，Markdown 预览转换。
- 更新：可选覆盖正文与主图，写回数据库并记录日志。
- 删除：二次确认或实际删除，附带审计日志。
- 批量：批量删除、批量转移分类。
flowchart TD
Start(["进入新增/编辑"]) --> Clean["清理草稿附件/生成Token"]
Clean --> Validate["Request 校验"]
Validate --> |失败| Error["抛出领域异常并提示"]
Validate --> |成功| Process["XSS清洗/远程图片本地化"]
Process --> Save["写入文章/主图"]
Save --> Claim["认领草稿附件"]
Claim --> Log["记录审计日志"]
Log --> Redirect["重定向到编辑页/列表"]前台文章展示与 SEO
- 列表/分类/归档：解析路由参数，按分类与归档时间窗筛选，分页加载，构建面包屑与导航。
- 详情：仅展示已发布文章，Markdown 渲染正文，记录点击量，注入 SEO 标题/关键词/描述与结构化数据。
- 侧栏搜索：回填全站搜索关键词（q），非法词不回填。
sequenceDiagram
participant U as "用户浏览器"
participant C as "前台控制器"
participant S as "前台服务"
participant M as "前台模型"
U->>C : 访问文章列表/详情
C->>S : 构建列表/详情数据
S->>M : 查询已发布/归档/分类
M-->>S : 返回数据
S->>S : Markdown 渲染/统计
S-->>C : 返回视图数据
C-->>U : 渲染页面(含SEO/导航)分类体系
- 后台分类：树形展示、CRUD、同步到导航、排序。
- 前台分类：树形导航、按分类筛选文章、分类信息多语言。
classDiagram
class Admin_ArticleCategory {
+table : "article_category"
+fillable : ["name","slug","parent_id","icon","keywords","description","sync_to_nav","sort"]
+flat()
}
class Front_ArticleCategory {
+translatable : ["name"]
+prefetchers : ["language"]
+tree(catId)
}
Admin_ArticleCategory <.. Front_ArticleCategory : "共享 article_category 表"富文本编辑器集成与图片处理
- 正文内容在后台新增/更新时进行 XSS 清洗，支持将远程图片下载到本地并替换链接。
- 主图上传走统一附件服务，支持管理员身份标记与归属。
- 前台详情页对正文进行 Markdown 渲染输出。
flowchart TD
In["接收 content/image"] --> XSS["XSS 清洗"]
XSS --> Remote{"是否包含远程图片?"}
Remote -- 是 --> Local["下载并替换为本地图片"]
Remote -- 否 --> Keep["保留原内容"]
Local --> Store["保存正文/主图"]
Keep --> Store
Store --> Done["完成入库"]版本控制与审核机制
- 当前实现未提供独立的文章版本历史表；如需版本控制，可在 Service 层引入版本快照策略（例如每次更新前复制一份至版本表）。
- 审核机制通过“状态字段”控制前台可见性：仅已发布（status=1）的文章在前台显示。
标签系统
- 当前代码中未发现独立的标签模型与关联逻辑；如需标签功能，建议在 Service 层增加标签关联与检索能力，并在列表/详情中展示。
依赖关系分析
- 控制器依赖服务，服务依赖模型与外部服务（附件、Markdown、审计）。
- 前台控制器还依赖导航、面包屑、SEO、Schema 等服务以增强展示与 SEO。
- 模型使用 traits 提供通用能力（分类筛选、内容格式化、URL 生成、相关文查询等）。
graph LR
AC["Admin ArticleController"] --> ASvc["Admin ArticleService"]
ASvc --> AModel["Admin Article Model"]
ASvc --> Att["附件服务"]
ASvc --> MD["MarkdownRenderer"]
ASvc --> Aud["审计日志"]
FC["Front ArticleController"] --> FSvc["Front ArticleService"]
FSvc --> FModel["Front Article Model"]
FC --> Nav["NavigationBuilder"]
FC --> BC["BreadcrumbBuilder"]
FC --> Seo["SeoResolver"]
FC --> Schema["SchemaService"]性能与缓存
- 列表查询使用 ORM 的 with('category') 预加载分类，减少 N+1 查询。
- 前台模型配置 prefetchers 批量预热 URL、多语言、附件，提升列表渲染性能。
- 分页限制每页条数，避免一次性加载过多数据。
- 建议：
- 对高频访问的分类/归档列表启用应用级缓存（如 Redis），设置合理过期策略。
- 对 Markdown 渲染结果进行缓存，结合内容变更事件失效。
- 对图片资源启用 CDN 与压缩。
安全与合规
- 输入校验：通过 Request 校验规则约束字段类型与必填项。
- XSS 防护：正文内容在入库前进行清洗。
- 权限与审计：后台操作记录审计日志，便于追踪与回溯。
- 建议：
- 对敏感操作（删除、批量操作）增加 CSRF 校验与二次确认。
- 对上传文件进行类型、大小、路径白名单校验。
- 对外部图片下载增加域名白名单与超时限制。
故障排查
- 新增/更新失败：检查 Request 校验错误、附件上传是否成功、Markdown 渲染是否异常。
- 列表为空：检查分类筛选、关键词、归档时间窗、分页参数是否正确。
- 详情页 404：确认路由参数（id/slug/year/month）是否有效，文章是否已发布。
- 图片不显示：确认附件归属、草稿认领是否完成、CDN 路径是否正确。
结论
DouPHP 文章模块采用清晰的分层架构，后台聚焦内容生产与安全，前台聚焦内容消费与 SEO。通过 ORM 预加载、分页、Markdown 渲染、附件服务与审计日志，实现了稳定高效的读写体验。后续可按需扩展版本控制、标签系统与应用级缓存，进一步提升可维护性与性能。
附录：API参考与示例
以下列出常用接口与典型用法，便于快速上手与集成。
-
后台文章
- 列表
- 方法：GET
- 路径：/admin/article
- 参数：category_id, keyword, page
- 返回：文章列表与分页信息
- 新增
- 方法：POST
- 路径：/admin/article
- 参数：title, category_id, content, image, keywords, description, defined, draft_token
- 行为：XSS 清洗、远程图片本地化、主图上传、草稿认领、审计日志
- 编辑
- 方法：GET
- 路径：/admin/article/edit?id={id}
- 返回：文章详情（Markdown 预览）
- 更新
- 方法：POST
- 路径：/admin/article
- 参数：id, title, content, image, keywords, description, defined
- 行为：可选覆盖正文与主图，审计日志
- 删除
- 方法：POST
- 路径：/admin/article/destroy?id={id}
- 行为：二次确认后删除，审计日志
- 批量操作
- 方法：POST
- 路径：/admin/article/action
- 参数：action(del_all/category_move), checkbox[], new_cat_id(转移分类用)
- 列表
-
前台文章
- 列表/分类/归档
- 方法：GET
- 路径：/article/category/{year}/{month}?page={page} 或 /article/category?category_id={id}
- 返回：文章列表与分页
- 详情
- 方法：GET
- 路径：/article/show/{id}
- 行为：Markdown 渲染、点击量+1、SEO 注入
- 列表/分类/归档