post_waver

系统架构总览

版本: v1.0 最后更新: 2026-04-03 受众: 开发者、架构师 阅读时间: 20 分钟

📋 概述

PostWaver 采用模块化 Monorepo 架构，将系统分为多个独立但协作的包。本文档详细说明了系统的架构设计、各层的职责以及包之间的关系。

🎯 设计原则

1. 关注点分离（Separation of Concerns）

每个包专注于单一职责：

core: 内容解析和处理
transformer: 平台格式转换
database: 数据持久化
engine: 工作流编排

2. 依赖倒置（Dependency Inversion）

高层模块不依赖低层模块，都依赖抽象：

包之间通过接口通信
使用依赖注入
易于测试和替换

3. 单一数据源（Single Source of Truth）

Markdown 文件是内容的唯一来源
数据库仅存储元数据和状态
避免数据同步问题

4. 可扩展性（Extensibility）

插件化平台: 添加新平台无需修改核心代码
配置驱动: 通过配置文件控制行为
钩子系统: 在关键点提供扩展点

5. 本地优先（Local-First）

用户拥有数据完全控制权
可以离线工作
易于备份和迁移

🏗️ 分层架构

┌─────────────────────────────────────────────────────────┐
│                     应用层 (Application)                  │
│  ┌──────────────┐           ┌──────────────┐            │
│  │   Web UI     │           │ Converter Web │            │
│  │  (React)     │           │   (React)     │            │
│  └──────────────┘           └──────────────┘            │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                      引擎层 (Engine)                      │
│  ┌────────────────────────────────────────────────┐     │
│  │  Engine (Hono.js)                              │     │
│  │  - API 服务器                                   │     │
│  │  - 工作流编排                                   │     │
│  │  - 预览系统                                     │     │
│  └────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                      业务层 (Business)                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │  Core    │  │ Linker   │  │Transform │              │
│  │ 解析/扫描 │  │ 关系生成 │  │ 平台转换 │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                      数据层 (Data)                        │
│  ┌──────────┐           ┌──────────┐                    │
│  │ Database │           │  Config  │                    │
│  │(Prisma)  │           │ Manager  │                    │
│  └──────────┘           └──────────┘                    │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                   存储层 (Storage)                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │  SQLite  │  │ Markdown │  │   Hexo   │              │
│  │ (元数据)  │  │ (内容)    │  │  (博客)  │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└─────────────────────────────────────────────────────────┘

层次说明

1. 应用层（Application Layer）

职责: 用户界面和交互

组件:

Web UI: React 网页界面
Converter Web: 独立的转换工具

2. 引擎层（Engine Layer）

职责: 工作流编排和 API 服务

组件:

Engine Package: API 服务器（Hono.js）
- RESTful API
- 发布工作流
- 预览系统

3. 业务层（Business Layer）

职责: 核心业务逻辑

组件:

Core Package: 内容解析和处理
Linker Package: 内容关系生成
Transformer Package: 平台格式转换

4. 数据层（Data Layer）

职责: 数据持久化和配置管理

组件:

Database Package: 数据库访问层
Config Package: 配置管理

5. 存储层（Storage Layer）

职责: 底层存储

组件:

SQLite: 元数据存储
Markdown 文件: 内容存储
Hexo 博客: 博客生成

📦 包架构

包依赖关系

                    ┌─────────────┐
                    │   web-ui    │
                    │ converter-web│
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │   engine    │
                    └──────┬──────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
┌───────▼────────┐ ┌───────▼────────┐ ┌──────▼─────┐
│     core       │ │    linker      │ │transformer │
└───────┬────────┘ └───────┬────────┘ └──────┬─────┘
        │                  │                  │
        └──────────────────┼──────────────────┘
                           │
                    ┌──────▼──────┐
                    │   config    │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │  database   │
                    └─────────────┘

包职责

包	职责	主要依赖	输出
core	内容解析、扫描、注入	database, linker	解析后的内容、元数据
linker	内容关系生成	database	相关文章列表
transformer	平台格式转换	无	平台特定格式
adapter	平台 API 适配	无	API 调用结果
database	数据持久化	无	CRUD 操作
config	配置管理	无	配置对象
engine	工作流编排、API	core, transformer, adapter, database, config	API 响应
web-ui	React 界面	engine	UI 组件
converter-web	独立转换工具	transformer	转换结果

🔄 数据流

内容发布流程

┌─────────────┐
│ 用户写作     │
│ Markdown    │
└──────┬──────┘
       ↓
┌─────────────┐
│ 扫描内容     │  ← core/scanner
│ 生成 frontmatter │
└──────┬──────┘
       ↓
┌─────────────┐
│ 解析内容     │  ← core/parser
│ 提取图片     │
└──────┬──────┘
       ↓
┌─────────────┐
│ 生成关系     │  ← linker
│ 相关文章     │
│ 前后篇       │
└──────┬──────┘
       ↓
┌─────────────┐
│ 存储元数据   │  ← database
│ SQLite DB   │
└──────┬──────┘
       ↓
┌─────────────┐
│ 平台转换     │  ← transformer
│ 格式适配     │
└──────┬──────┘
       ↓
┌─────────────┐
│ 上传图片     │  ← adapter
│ (如果需要)   │
└──────┬──────┘
       ↓
┌─────────────┐
│ 发布到平台   │  ← adapter/engine
│ 或同步博客   │
└─────────────┘

关键数据流

1. 内容扫描

Markdown 文件 → Scanner → Frontmatter 生成 → 数据库存储

2. 内容解析

Markdown → Parser → AST → 提取内容/图片

3. 关系生成

数据库查询 → Linker → 关系计算 → 相关文章列表

4. 平台转换

通用内容 → Transformer → 平台特定格式

5. Hexo 同步

转换后内容 → 模板注入 → Hexo 博客 → Git 提交

🛠️ 技术栈

前端技术栈

技术	版本	用途
React	18.2.0	UI 框架
React Router	6.21.0	路由管理
Vite	5.0.11	构建工具
TypeScript	5.3.3	类型系统
Tailwind CSS	Latest	样式框架

后端技术栈

技术	版本	用途
Node.js	18+	运行时
Hono.js	Latest	Web 框架
Prisma	5.22.0	ORM
SQLite	3.x	数据库

内容处理技术栈

技术	版本	用途
unified	11.0.5	统一处理接口
remark	15.0.1	Markdown 解析
remark-html	16.0.1	Markdown 转 HTML
gray-matter	4.0.3	Frontmatter 解析
juice	-	CSS 内联化（WeChat）

开发工具

工具	版本	用途
pnpm	8+	包管理器
ESLint	Latest	代码检查
Prettier	Latest	代码格式化
Vitest	Latest	测试框架
TypeScript	5.3.3	类型检查

🔌 扩展点

1. 添加新平台

实现位置: packages/transformer/src/

步骤:

创建新的转换器函数
实现 Transformer 接口
在 adapter 中实现平台 API（如需要）

2. 添加新的内容注入器

实现位置: packages/core/src/

步骤:

创建新的注入器
实现 Injector 接口
在扫描流程中调用

3. 添加新的数据库模型

实现位置: packages/database/prisma/schema.prisma

步骤:

定义模型
运行迁移
创建 DAL 方法

4. 添加新的 API 端点

实现位置: packages/engine/src/

步骤:

添加路由
实现处理函数
添加类型定义

🎨 架构优势

1. 模块化

每个包独立开发和测试
降低耦合度
易于维护

2. 可扩展

添加新功能无需修改核心代码
支持插件化扩展
配置驱动

3. 可测试

每个包都有独立的测试套件
依赖注入便于 mock
集成测试覆盖完整流程

4. 类型安全

全面使用 TypeScript
编译时类型检查
减少运行时错误

5. 本地优先

用户拥有数据
离线工作
易于备份

📚 相关文档

最后更新: 2026-04-03 维护者: PostWaver Team 反馈: GitHub Issues

This site is open source. Improve this page.