488 lines
15 KiB
Markdown
488 lines
15 KiB
Markdown
# Note2Any v1.4.0 Architecture Overview
|
|
|
|
> **重大架构升级**: v1.4.0引入了全新的模块化核心系统，本文档描述升级后的完整架构。
|
|
>
|
|
> 相关文档：
|
|
> - [v1.3.x旧架构](./architecture.md) - 升级前架构参考
|
|
> - [优化报告](./OPTIMIZATION_REPORT_v1.3.12.md) - 详细优化过程
|
|
> - [模块设计图](./diagrams.md) - 架构可视化图表
|
|
|
|
## 1. 全新分层架构
|
|
|
|
### 1.1 Core System Layer (新增)
|
|
```
|
|
┌─────────────────────────────────────────────┐
|
|
│ Core System Layer - 核心支撑系统 │
|
|
│ │
|
|
│ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ErrorHandler │ │ProgressInd. │ 错误&进度 │
|
|
│ └─────────────┘ └─────────────┘ │
|
|
│ │
|
|
│ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ConfigManager│ │PublisherMgr │ 配置&发布 │
|
|
│ └─────────────┘ └─────────────┘ │
|
|
│ │
|
|
│ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ContentProc. │ │ImageProc. │ 内容&图像 │
|
|
│ └─────────────┘ └─────────────┘ │
|
|
│ │
|
|
│ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │GalleryProc. │ │HtmlProc. │ 图库&HTML │
|
|
│ └─────────────┘ └─────────────┘ │
|
|
└─────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 1.2 完整系统分层
|
|
```
|
|
┌─────────────────────────────────────────────┐
|
|
│ UI/Interaction Layer │
|
|
│ preview-view.ts - Obsidian视图容器 │
|
|
│ preview-manager.ts - 业务逻辑调度器 │
|
|
└──────────────┬──────────────────────────────┘
|
|
│ 支撑
|
|
↓
|
|
┌─────────────────────────────────────────────┐
|
|
│ Core System Layer - 新增核心模块系统 │
|
|
│ 统一错误处理、进度反馈、配置管理、发布抽象 │
|
|
└──────────────┬──────────────────────────────┘
|
|
│ 支撑
|
|
↓
|
|
┌─────────────────────────────────────────────┐
|
|
│ Business Logic Layer │
|
|
│ article-render.ts - 内容渲染（重构中） │
|
|
│ platform-chooser.ts - 平台选择器 │
|
|
└──────────────┬──────────────────────────────┘
|
|
│ 管理
|
|
┌───────┼───────┐
|
|
↓ ↓ ↓
|
|
┌──────────┐ ┌──────────┐ ┌──────────┐
|
|
│Wechat │ │Xiaohong- │ │Future │
|
|
│Platform │ │shu │ │Platforms │
|
|
│ │ │Platform │ │... │
|
|
└──────────┘ └──────────┘ └──────────┘
|
|
│ 依赖
|
|
↓
|
|
┌─────────────────────────────────────────────┐
|
|
│ Infrastructure Layer │
|
|
│ Assets, Settings, Utils, External APIs │
|
|
└─────────────────────────────────────────────┘
|
|
```
|
|
|
|
## 2. 核心模块详解
|
|
|
|
### 2.1 ErrorHandler - 统一错误处理
|
|
```typescript
|
|
// src/core/error-handler.ts
|
|
class ErrorHandler {
|
|
static handle(error: Error, context: string): void
|
|
static log(level: LogLevel, message: string, data?: any): void
|
|
static getUserFriendlyMessage(error: Error): string
|
|
}
|
|
```
|
|
|
|
**职责**:
|
|
- 全局错误捕获和处理
|
|
- 用户友好的错误提示
|
|
- 错误日志记录和分类
|
|
- 错误恢复策略
|
|
|
|
**集成点**:
|
|
- 所有模块的try-catch块
|
|
- 异步操作的错误边界
|
|
- 用户操作的失败回调
|
|
|
|
### 2.2 ProgressIndicator - 进度反馈系统
|
|
```typescript
|
|
// src/core/progress-indicator.ts
|
|
class ProgressIndicator {
|
|
start(message: string): void
|
|
update(message: string, progress?: number): void
|
|
finish(message: string): void
|
|
error(message: string): void
|
|
}
|
|
```
|
|
|
|
**职责**:
|
|
- 长时间操作的进度反馈
|
|
- 统一的用户状态提示
|
|
- 可视化进度显示
|
|
- 操作状态管理
|
|
|
|
**应用场景**:
|
|
- 插件初始化
|
|
- 图片上传进度
|
|
- 内容渲染过程
|
|
- 批量操作状态
|
|
|
|
### 2.3 ConfigManager - 配置管理中心
|
|
```typescript
|
|
// src/core/config-manager.ts
|
|
class ConfigManager {
|
|
static initialize(settings: NMPSettings): void
|
|
static getInstance(): ConfigManager
|
|
get<T>(key: string): T
|
|
set<T>(key: string, value: T): void
|
|
validate(): ValidationResult
|
|
onUpdate(callback: (config: any) => void): void
|
|
}
|
|
```
|
|
|
|
**职责**:
|
|
- 中心化配置管理
|
|
- 运行时配置验证
|
|
- 配置变更通知
|
|
- 类型安全的配置访问
|
|
|
|
**配置分类**:
|
|
- 用户界面设置
|
|
- 平台认证信息
|
|
- 渲染参数配置
|
|
- 功能开关控制
|
|
|
|
### 2.4 PublisherInterface & PublisherManager - 发布平台抽象
|
|
```typescript
|
|
// src/core/publisher-interface.ts
|
|
interface IPlatformPublisher {
|
|
id: string
|
|
name: string
|
|
initialize(config: PlatformConfig): Promise<void>
|
|
publish(content: PublishContent): Promise<PublishResult>
|
|
uploadImage(image: ImageData): Promise<string>
|
|
validateConfig(): ValidationResult
|
|
}
|
|
|
|
// src/core/publisher-manager.ts
|
|
class PublisherManager {
|
|
registerPublisher(publisher: IPlatformPublisher): void
|
|
getPublisher(id: string): IPlatformPublisher
|
|
listAvailablePublishers(): IPlatformPublisher[]
|
|
publishTo(platformId: string, content: PublishContent): Promise<PublishResult>
|
|
}
|
|
```
|
|
|
|
**职责**:
|
|
- 统一的平台发布接口
|
|
- 平台无关的业务逻辑
|
|
- 可扩展的平台架构
|
|
- 发布流程标准化
|
|
|
|
**支持平台**:
|
|
- 微信公众号 (已实现)
|
|
- 小红书 (已实现)
|
|
- 未来平台扩展
|
|
|
|
### 2.5 ContentProcessor - 内容处理流水线
|
|
```typescript
|
|
// src/core/content-processor.ts
|
|
class ContentProcessor {
|
|
addProcessor(processor: IContentProcessor): void
|
|
process(content: string, options: ProcessOptions): Promise<ProcessResult>
|
|
removeProcessor(id: string): void
|
|
getProcessors(): IContentProcessor[]
|
|
}
|
|
|
|
interface IContentProcessor {
|
|
id: string
|
|
process(content: string, context: ProcessContext): Promise<string>
|
|
priority: number
|
|
}
|
|
```
|
|
|
|
**职责**:
|
|
- 模块化内容处理
|
|
- 可配置的处理管道
|
|
- 处理器生命周期管理
|
|
- 支持自定义扩展
|
|
|
|
**内置处理器**:
|
|
- FrontmatterProcessor: 元数据解析
|
|
- GalleryProcessor: 图库短代码
|
|
- ImageProcessor: 图片处理
|
|
- MathProcessor: 数学公式
|
|
- SyntaxProcessor: 语法扩展
|
|
|
|
### 2.6 专业化处理模块
|
|
|
|
#### ImageProcessor - 图像处理引擎
|
|
```typescript
|
|
// src/core/image-processor.ts
|
|
class ImageProcessor {
|
|
initialize(): Promise<void>
|
|
convertWebpToJpg(data: ArrayBuffer): Promise<ArrayBuffer>
|
|
uploadToWechat(data: ArrayBuffer, filename: string, token: string): Promise<string>
|
|
processImage(data: ArrayBuffer, filename: string, options: ImageProcessOptions): Promise<ArrayBuffer>
|
|
htmlToPng(element: HTMLElement, options?: any): Promise<Blob>
|
|
isReady(): boolean
|
|
}
|
|
```
|
|
|
|
#### GalleryProcessor - 图库处理器
|
|
```typescript
|
|
// src/core/gallery-processor.ts
|
|
class GalleryProcessor {
|
|
processGalleryShortcodes(content: string): Promise<string>
|
|
private processDirectoryGalleries(content: string): Promise<string>
|
|
private processBlockGalleries(content: string): Promise<string>
|
|
}
|
|
```
|
|
|
|
#### HtmlProcessor - HTML生成器
|
|
```typescript
|
|
// src/core/html-processor.ts
|
|
class HtmlProcessor {
|
|
generateFullHtml(content: string, options: HtmlProcessOptions): string
|
|
processInlineCSS(html: string): Promise<string>
|
|
sanitizeHtml(html: string): DocumentFragment
|
|
applyStylesToElement(html: string, css: string): string
|
|
optimizeForMobile(html: string): string
|
|
}
|
|
```
|
|
|
|
## 3. 架构升级对比
|
|
|
|
### 3.1 升级前 (v1.3.x)
|
|
```
|
|
❌ 问题点:
|
|
- 单体式大文件 (article-render.ts 864行)
|
|
- 分散的错误处理
|
|
- 缺乏进度反馈
|
|
- 配置管理混乱
|
|
- 平台耦合严重
|
|
- 代码复用度低
|
|
```
|
|
|
|
### 3.2 升级后 (v1.4.0)
|
|
```
|
|
✅ 改进点:
|
|
- 模块化设计 (9个核心模块)
|
|
- 统一错误处理系统
|
|
- 实时进度反馈
|
|
- 中心化配置管理
|
|
- 标准化平台接口
|
|
- 高代码复用率
|
|
```
|
|
|
|
## 4. 数据流与交互
|
|
|
|
### 4.1 插件初始化流程
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Main as main.ts
|
|
participant Progress as ProgressIndicator
|
|
participant Config as ConfigManager
|
|
participant Assets as AssetsManager
|
|
participant Error as ErrorHandler
|
|
|
|
Main->>Progress: start('初始化插件')
|
|
Main->>Config: initialize(settings)
|
|
Config->>Config: validate configuration
|
|
Main->>Assets: loadAssets()
|
|
Assets-->>Error: handle errors if any
|
|
Main->>Progress: finish('插件初始化完成')
|
|
```
|
|
|
|
### 4.2 内容发布流程
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant UI as PreviewView
|
|
participant Progress as ProgressIndicator
|
|
participant Content as ContentProcessor
|
|
participant Publisher as PublisherManager
|
|
participant Platform as IPlatformPublisher
|
|
|
|
UI->>Progress: start('处理内容')
|
|
UI->>Content: process(markdown)
|
|
Content->>Progress: update('处理图片')
|
|
Content->>Content: processImages()
|
|
UI->>Publisher: publishTo(platformId, content)
|
|
Publisher->>Platform: publish(content)
|
|
Platform-->>Publisher: PublishResult
|
|
Publisher-->>UI: PublishResult
|
|
UI->>Progress: finish('发布完成')
|
|
```
|
|
|
|
## 5. 性能优化
|
|
|
|
### 5.1 模块化加载
|
|
- **懒加载**: 按需初始化核心模块
|
|
- **依赖注入**: 减少模块间耦合
|
|
- **单例模式**: 避免重复实例化
|
|
|
|
### 5.2 异步处理优化
|
|
- **并发处理**: 图片处理并行化
|
|
- **队列管理**: 批量操作队列化
|
|
- **错误恢复**: 优雅的失败处理
|
|
|
|
### 5.3 缓存机制
|
|
- **配置缓存**: 避免重复读取
|
|
- **资源缓存**: CSS和主题缓存
|
|
- **结果缓存**: 处理结果缓存
|
|
|
|
## 6. 扩展性设计
|
|
|
|
### 6.1 平台扩展
|
|
```typescript
|
|
// 新平台接入示例
|
|
class MyPlatformPublisher implements IPlatformPublisher {
|
|
id = 'my-platform'
|
|
name = 'My Platform'
|
|
|
|
async initialize(config: PlatformConfig): Promise<void> {
|
|
// 平台初始化逻辑
|
|
}
|
|
|
|
async publish(content: PublishContent): Promise<PublishResult> {
|
|
// 发布逻辑实现
|
|
}
|
|
|
|
async uploadImage(image: ImageData): Promise<string> {
|
|
// 图片上传逻辑
|
|
}
|
|
|
|
validateConfig(): ValidationResult {
|
|
// 配置验证逻辑
|
|
}
|
|
}
|
|
|
|
// 注册新平台
|
|
publisherManager.registerPublisher(new MyPlatformPublisher())
|
|
```
|
|
|
|
### 6.2 处理器扩展
|
|
```typescript
|
|
// 自定义内容处理器
|
|
class MyContentProcessor implements IContentProcessor {
|
|
id = 'my-processor'
|
|
priority = 100
|
|
|
|
async process(content: string, context: ProcessContext): Promise<string> {
|
|
// 自定义处理逻辑
|
|
return processedContent
|
|
}
|
|
}
|
|
|
|
// 注册处理器
|
|
contentProcessor.addProcessor(new MyContentProcessor())
|
|
```
|
|
|
|
## 7. 错误处理策略
|
|
|
|
### 7.1 错误分类
|
|
```typescript
|
|
enum ErrorType {
|
|
CONFIG_ERROR = 'config',
|
|
NETWORK_ERROR = 'network',
|
|
PROCESSING_ERROR = 'processing',
|
|
PLATFORM_ERROR = 'platform',
|
|
USER_ERROR = 'user'
|
|
}
|
|
```
|
|
|
|
### 7.2 错误处理流程
|
|
```mermaid
|
|
flowchart TD
|
|
A[Error Occurs] --> B[ErrorHandler.handle()]
|
|
B --> C{Error Type}
|
|
C -->|Config| D[Show Config Help]
|
|
C -->|Network| E[Retry Strategy]
|
|
C -->|Processing| F[Fallback Processing]
|
|
C -->|Platform| G[Platform Error Guide]
|
|
C -->|User| H[User Action Guide]
|
|
D --> I[Log Error]
|
|
E --> I
|
|
F --> I
|
|
G --> I
|
|
H --> I
|
|
I --> J[User Notification]
|
|
```
|
|
|
|
## 8. 测试策略
|
|
|
|
### 8.1 单元测试覆盖
|
|
- ✅ 核心模块单元测试
|
|
- ✅ 错误处理测试
|
|
- ✅ 配置管理测试
|
|
- ✅ 内容处理器测试
|
|
|
|
### 8.2 集成测试
|
|
- ✅ 平台发布流程测试
|
|
- ✅ 端到端功能测试
|
|
- ✅ 性能基准测试
|
|
|
|
## 9. 未来路线图
|
|
|
|
### 9.1 短期目标 (v1.4.x)
|
|
- [ ] 完成article-render.ts重构
|
|
- [ ] 实现更多内容处理器
|
|
- [ ] 优化性能和稳定性
|
|
- [ ] 完善错误处理覆盖
|
|
|
|
### 9.2 中期目标 (v1.5.x)
|
|
- [ ] 新平台支持 (知乎、CSDN等)
|
|
- [ ] 插件化处理器市场
|
|
- [ ] AI内容优化集成
|
|
- [ ] 批量操作增强
|
|
|
|
### 9.3 长期目标 (v1.6+)
|
|
- [ ] 云端内容同步
|
|
- [ ] 协作编辑功能
|
|
- [ ] 智能内容推荐
|
|
- [ ] 多媒体内容支持
|
|
|
|
## 10. 技术债务清理
|
|
|
|
### 10.1 已解决
|
|
- ✅ 大文件拆分为模块
|
|
- ✅ 统一错误处理机制
|
|
- ✅ 配置管理标准化
|
|
- ✅ 平台抽象层建立
|
|
|
|
### 10.2 进行中
|
|
- 🔄 article-render.ts模块化
|
|
- 🔄 图片处理管道优化
|
|
- 🔄 测试覆盖率提升
|
|
|
|
### 10.3 待处理
|
|
- ⏳ 旧代码兼容性清理
|
|
- ⏳ 性能监控集成
|
|
- ⏳ 文档完善
|
|
|
|
---
|
|
|
|
## 附录: 核心模块API参考
|
|
|
|
### A.1 ErrorHandler API
|
|
```typescript
|
|
ErrorHandler.handle(error: Error, context: string): void
|
|
ErrorHandler.log(level: LogLevel, message: string, data?: any): void
|
|
ErrorHandler.getUserFriendlyMessage(error: Error): string
|
|
ErrorHandler.registerErrorType(type: string, handler: ErrorTypeHandler): void
|
|
```
|
|
|
|
### A.2 ProgressIndicator API
|
|
```typescript
|
|
progress.start(message: string): void
|
|
progress.update(message: string, progress?: number): void
|
|
progress.finish(message: string): void
|
|
progress.error(message: string): void
|
|
progress.setTotal(total: number): void
|
|
progress.increment(message?: string): void
|
|
```
|
|
|
|
### A.3 ConfigManager API
|
|
```typescript
|
|
ConfigManager.initialize(settings: NMPSettings): void
|
|
ConfigManager.getInstance(): ConfigManager
|
|
config.get<T>(key: string): T
|
|
config.set<T>(key: string, value: T): void
|
|
config.validate(): ValidationResult
|
|
config.onUpdate(callback: (config: any) => void): void
|
|
```
|
|
|
|
---
|
|
> **维护说明**: 本文档随v1.4.0架构升级而创建，后续架构变更需同步更新。
|
|
>
|
|
> **相关文档**:
|
|
> - [发布接口规范](./publisher-interface-spec.md)
|
|
> - [模块开发指南](./module-development-guide.md)
|
|
> - [扩展开发文档](./extension-development.md) |