简介

本指南面向DouPHP的页面缓存配置，覆盖静态页面生成、动态内容缓存策略、缓存失效机制以及性能优化建议。文档基于仓库中实际代码实现进行说明，重点包括：

• 静态资源版本与浏览器缓存控制（通过 manifest 世代）
• 后台登录后的缓存清理流程
• 路由层进程级字段缓存与预热
• 用户会话与令牌缓存策略
• 缓存目录结构与命名规则
• 手动清理、自动清理与CDN集成的实践建议

项目结构

DouPHP将“缓存”相关能力分布在多处：

• 静态资源版本管理：由 ManifestCacheGeneration 负责，落盘于 storage/cache 下的世代文件，用于给 lang_js/routes_js 等静态资源追加 ?v= 参数，配合浏览器强缓存策略使用。
• 后台缓存清理：由 CacheClearService 提供统一删除目录能力；AdminLoginFlow 在登录后触发清理动作。
• 路由与URL构建：UrlBuilder 使用进程级静态缓存加速列表页与详情页的URL生成，并提供批量字段缓存预热方法。
• 用户会话与令牌：前台 Auth 解析用户上下文，UserAuthService 写入 session 或签发 token，作为动态内容的短期缓存载体。
• 系统常量：system.php 定义前端固定模块、保留段等，影响路由与页面生成范围，间接决定哪些页面可被缓存。

graph TB
A["管理员操作"] --> B["后台登录流程<br/>AdminLoginFlow"]
B --> C["缓存清理服务<br/>CacheClearService"]
D["静态资源请求"] --> E["ManifestCacheGeneration<br/>读取/递增世代"]
F["页面渲染"] --> G["UrlBuilder<br/>进程级字段缓存/预热"]
H["用户访问"] --> I["前台Auth<br/>Session/Token解析"]
J["系统常量"] --> K["system.php<br/>固定模块/保留段"]

核心组件

• 静态资源版本与浏览器缓存控制：ManifestCacheGeneration 提供 current()/bump()/urlVersion()，通过 storage/cache/manifest_generation.txt 管理世代号，使 HTML 中的 ?v={contentHash}-{generation} 变化，强制浏览器回源更新。
• 后台缓存清理：CacheClearService::clearCache($dir) 调用 FileHelper::delDir 递归删除指定目录；AdminLoginFlow 在登录后串联清理逻辑。
• 路由层缓存与预热：UrlBuilder 使用进程级静态数组缓存字段与分类信息，warmupFieldCache/warmupCatIdCache 减少重复查询，提升列表页与详情页URL生成性能。
• 用户会话与令牌：前台 Auth 解析用户上下文，UserAuthService 在登录时写入 session 或签发 token，作为动态内容的短期缓存载体。

架构总览

下图展示页面缓存的关键路径：管理员登录后触发缓存清理；静态资源请求通过 manifest 世代控制浏览器缓存；页面渲染阶段利用 UrlBuilder 的进程级缓存加速；用户访问通过 Auth 解析会话或令牌。

sequenceDiagram
participant Admin as "管理员"
participant Login as "后台登录流程<br/>AdminLoginFlow"
participant Clear as "缓存清理服务<br/>CacheClearService"
participant Browser as "浏览器"
participant Manifest as "ManifestCacheGeneration"
participant Page as "页面渲染<br/>UrlBuilder"
participant User as "用户"
participant Auth as "前台Auth"
Admin->>Login : 提交登录
Login->>Clear : 触发清理目录
Clear-->>Login : 清理完成
Note over Login,Clear : 登录后副作用包含缓存清理
Browser->>Manifest : 请求静态资源(带?v=)
Manifest-->>Browser : 返回资源(含contentHash-generation)
User->>Page : 访问页面
Page->>Page : 进程级字段缓存/预热
Page-->>User : 返回页面
User->>Auth : 携带Session/Token
Auth-->>User : 解析用户上下文

详细组件分析

静态页面生成与资源版本控制

• 机制说明：
  • 静态资源（如 lang_js、routes_js）在HTML中以 ?v={contentHash}-{generation} 形式引用，其中 contentHash 为内容指纹，generation 为 manifest 世代号。
  • 管理员清空缓存时，ManifestCacheGeneration::bump() 将世代号+1并落盘到 storage/cache/manifest_generation.txt，浏览器因URL变化而重新拉取资源，打破本地强缓存。
  • 磁盘文件名与ETag仍仅使用内容hash，确保CDN与边缘缓存稳定命中。
• 目录与命名：
  • 世代文件路径：storage/cache/manifest_generation.txt（若 STORAGE_PATH 未定义则回退至 ROOT_PATH . 'storage/'）。
  • URL版本拼接：urlVersion(contentHash) 根据当前世代返回 contentHash 或 contentHash-generation。
• 适用场景：
  • 适用于所有需要浏览器强缓存的静态资源，避免频繁全量刷新导致带宽浪费。

flowchart TD
Start(["请求静态资源"]) --> ReadGen["读取世代文件<br/>current()"]
ReadGen --> GenCheck{"世代>0?"}
GenCheck -- "否" --> UseHash["返回 contentHash"]
GenCheck -- "是" --> AppendGen["返回 contentHash-generation"]
AppendGen --> End(["响应资源"])
UseHash --> End

后台缓存清理流程

• 触发点：
  • 后台登录成功后，AdminLoginFlow 会调用 CacheClearService 清理缓存目录，确保管理员操作后前端及时生效。
• 清理方式：
  • CacheClearService::clearCache($dir) 使用 FileHelper::delDir 递归删除指定目录及其子目录内容。
• 注意事项：
  • 清理前需确认目标目录权限与路径正确，避免误删业务数据。
  • 建议在CI/CD或发布流程中集成缓存清理步骤。

sequenceDiagram
participant Admin as "管理员"
participant Flow as "AdminLoginFlow"
participant Service as "CacheClearService"
Admin->>Flow : 提交登录
Flow->>Service : clearCache(目标目录)
Service-->>Flow : 删除完成
Flow-->>Admin : 登录成功并重定向

路由层缓存与预热

• 进程级缓存：
  • UrlBuilder 使用静态数组缓存字段（如 slug、created_at）与分类ID，跨实例保留，供列表预热与逐条生成共用。
• 预热方法：
  • warmupFieldCache：批量查询并回填字段缓存，减少重复SQL。
  • warmupCatIdCache：针对列表行自带 category_id 的情况优先回填，否则查库并缓存。
• 适用场景：
  • 列表页、详情页URL生成频繁的场景，显著降低数据库压力。

flowchart TD
Entry(["列表/详情URL生成"]) --> CheckCache["检查进程级缓存"]
CheckCache --> Hit{"命中?"}
Hit -- "是" --> ReturnCached["直接返回缓存值"]
Hit -- "否" --> QueryDB["批量查询字段/分类"]
QueryDB --> FillCache["回填缓存"]
FillCache --> ReturnResult["返回结果"]
ReturnCached --> End(["结束"])
ReturnResult --> End

动态内容缓存策略

• 页面片段缓存：
  • 可通过模板层对高频片段（如导航、公告）进行局部缓存，结合 UrlBuilder 的进程级缓存减少渲染开销。
• 局部刷新缓存：
  • 前端通过API获取数据时，可利用浏览器缓存与后端ETag/Last-Modified策略减少重复传输。
• 用户会话缓存：
  • 前台 Auth 解析用户上下文，UserAuthService 在登录时写入 session 或签发 token，作为动态内容的短期缓存载体。
  • API端使用不透明随机token，前端存储并在后续请求中携带。

sequenceDiagram
participant Client as "客户端"
participant Front as "前台Auth"
participant UserSvc as "UserAuthService"
Client->>Front : 携带Session/Token访问
Front->>Front : 解析用户上下文
Front->>UserSvc : 验证/恢复身份
UserSvc-->>Front : 返回用户信息
Front-->>Client : 返回受保护数据

缓存失效策略

• 内容更新时自动清理缓存：
  • 后台登录成功后触发缓存清理，确保管理员操作后立即生效。
• 定时任务清理过期缓存：
  • 可结合系统任务调度定期清理 storage/cache 下临时文件或过期资源。
• 手动清除缓存功能：
  • 通过 CacheClearService::clearCache($dir) 手动删除指定目录，适用于紧急修复或发布后清理。

依赖关系分析

• ManifestCacheGeneration 依赖文件系统读写，用于持久化世代号。
• CacheClearService 依赖 FileHelper 进行目录删除。
• AdminLoginFlow 依赖 CacheClearService 与认证服务，串联登录与清理流程。
• UrlBuilder 依赖数据库查询与进程级静态缓存，提升URL生成效率。
• Auth 与 UserAuthService 协作处理用户会话与令牌，支撑动态内容缓存。

graph LR
M["ManifestCacheGeneration"] --> FS["文件系统"]
C["CacheClearService"] --> FH["FileHelper"]
L["AdminLoginFlow"] --> C
U["UrlBuilder"] --> DB["数据库"]
A["前台Auth"] --> S["Session/Token存储"]

性能考虑

• 缓存预热：
  • 使用 UrlBuilder 的 warmupFieldCache/warmupCatIdCache 在列表页加载前预热字段与分类缓存，减少首次请求延迟。
• 缓存压缩：
  • 启用服务器端Gzip/Brotli压缩静态资源，结合浏览器强缓存策略提升加载速度。
• CDN集成：
  • 将静态资源托管至CDN，利用 contentHash 与 generation 组合的URL实现长期缓存与按需刷新。
• 会话优化：
  • 合理设置Session生命周期，避免频繁重建；API端使用短生命周期token提高安全性与性能。

故障排除指南

• 静态资源未更新：
  • 检查 storage/cache/manifest_generation.txt 是否存在且可读；确认管理员已执行清空缓存操作以递增世代。
• 缓存清理失败：
  • 检查目标目录权限与路径是否正确；确认 FileHelper::delDir 调用无误。
• 用户无法登录或状态异常：
  • 检查 Session/Token 存储是否可用；确认前台 Auth 解析逻辑正常。
• 页面渲染缓慢：
  • 检查 UrlBuilder 进程级缓存是否命中；必要时调整预热策略或增加缓存粒度。

结论

DouPHP的页面缓存体系围绕静态资源版本控制、后台缓存清理、路由层预热与用户会话管理展开。通过合理的配置与实践，可显著提升页面加载速度与系统整体性能。建议在生产环境中启用浏览器强缓存、CDN加速与定时清理任务，并结合业务特性调整缓存粒度与生命周期。

附录：配置示例与最佳实践

• 静态资源版本控制：
  • 在HTML中引入静态资源时，使用 urlVersion(contentHash) 生成带世代的URL，确保浏览器缓存有效且可刷新。
• 后台缓存清理：
  • 在发布流程中集成缓存清理步骤，确保新版本资源立即生效。
• 路由层预热：
  • 在列表页加载前调用 warmupFieldCache/warmupCatIdCache，预热常用字段与分类缓存。
• 用户会话管理：
  • 合理设置Session生命周期，API端使用短生命周期token，平衡安全与性能。
• 系统常量配置：
  • 根据 system.php 定义的前台固定模块与保留段，合理规划路由与缓存策略。