架构设计文档

架构设计文档

Architecture Documentation

系统概述

MyBlog 是一个基于 PHP 的现代化博客系统，采用模块化设计，支持 Markdown、数学公式、代码高亮等功能。

技术栈

  • 语言: PHP 8.3+
  • Markdown 解析: Parsedown（安全模式）
  • 数学公式: KaTeX
  • 代码高亮: highlight.js
  • 图表: Mermaid
  • 缓存: 文件缓存 + Redis（可选）
  • 依赖管理: Composer（PSR-4 自动加载）

目录结构

myblog/
├── _blog/                    # 博客核心目录
│   ├── src/                  # 源代码
│   │   ├── Renderer/         # 渲染器
│   │   │   ├── BlogRenderer.php
│   │   │   └── BlogContentProcessor.php
│   │   ├── Parser/           # 解析器
│   │   │   └── Parsedown.php
│   │   ├── Security/         # 安全类
│   │   │   ├── SecurityFilter.php
│   │   │   ├── PathValidator.php
│   │   │   ├── InputValidator.php
│   │   │   └── CSRFProtection.php
│   │   └── Services/         # 服务类
│   │       └── CacheService.php
│   ├── helpers/              # 辅助函数
│   ├── cache/                # 缓存目录
│   ├── config.php            # 配置文件
│   └── style.css             # 样式文件
├── tests/                    # 测试文件
│   ├── Unit/                 # 单元测试
│   └── Integration/          # 集成测试
├── docs/                     # 文档
├── index.php                 # 首页入口
├── tags.php                  # 标签云页面
├── tag.php                   # 单个标签页面
├── sitemap.php               # 站点地图
├── composer.json             # 依赖配置
└── .env                      # 环境变量（不提交）

核心组件

1. BlogRenderer

负责将 Markdown 内容渲染为完整的 HTML 文档。

主要功能:

  • Markdown 解析
  • LaTeX 数学公式处理
  • HTML 文档生成（文章页面、索引页面）
  • SEO 标签生成
  • 结构化数据生成

2. BlogContentProcessor

BlogRenderer 的上层封装，提供更高级的内容处理功能。

主要功能:

  • Markdown 文件处理
  • YAML Front Matter 解析
  • 标题提取
  • 目录（TOC）生成
  • 元数据提取（description, author, tags 等）

3. CacheService

提供缓存功能，支持文件缓存和 Redis 缓存。

主要功能:

  • 文件缓存
  • Redis 缓存
  • 自动探测缓存类型
  • 基于文件修改时间的缓存失效
  • 缓存统计

4. Security 类

安全相关类，提供 XSS 防护、路径验证、输入验证等功能。

数据流

文章渲染流程

Markdown 文件
    ↓
BlogContentProcessor::processMarkdownFile()
    ↓
提取 Front Matter（title, description, tags 等）
    ↓
解析 Markdown → HTML
    ↓
添加标题 ID、生成 TOC
    ↓
BlogRenderer::renderDocument()
    ↓
生成完整 HTML（包含 SEO 标签、结构化数据）
    ↓
缓存（可选）
    ↓
输出 HTML

索引页面流程

目录扫描
    ↓
获取 Markdown 文件和子目录
    ↓
BlogRenderer::renderIndex()
    ↓
生成索引页面 HTML
    ↓
缓存（可选）
    ↓
输出 HTML

缓存策略

  1. 缓存键生成: 基于内容哈希
  2. 缓存失效:

- 基于文件修改时间（自动失效） - 基于 TTL（可选）

  1. 缓存类型:

- 文件缓存（默认） - Redis 缓存（如果可用） - 自动探测和回退

安全机制

  1. XSS 防护: SecurityFilter 类转义所有输出
  2. 路径遍历防护: PathValidator 类验证所有文件路径
  3. 输入验证: InputValidator 类验证所有用户输入
  4. CSRF 保护: CSRFProtection 类（按需使用）

扩展性

系统采用模块化设计，易于扩展：

  • 新增渲染器：继承或扩展 BlogRenderer
  • 新增服务：在 Services 目录下创建新类
  • 新增安全功能：在 Security 目录下创建新类

性能优化

  1. 缓存: 渲染结果缓存
  2. CDN: 外部资源使用 CDN
  3. 版本控制: 资源文件版本号控制
  4. 懒加载: 支持资源懒加载（待实现）
← 返回目录