pansou/docs/1-项目总体架构设计.md

PanSou 项目总体架构设计

1. 项目概述

PanSou是一个高性能的网盘资源搜索API服务，支持Telegram搜索和多种网盘搜索引擎。系统设计以性能和可扩展性为核心，支持多频道并发搜索、结果智能排序和网盘类型分类。

1.1 核心功能

• 多源搜索：支持Telegram频道和多种网盘搜索引擎
• 高性能并发：通过工作池实现高效并发搜索
• 智能排序：基于时间和关键词权重的多级排序策略
• 网盘类型分类：自动识别多种网盘链接，按类型归类展示
• 两级缓存：内存+磁盘缓存机制，大幅提升重复查询速度
• 插件系统：支持通过插件扩展搜索来源
• 缓存键一致性：优化的缓存键生成算法，确保相同语义查询的缓存命中

1.2 技术栈

• 编程语言：Go
• Web框架：Gin
• 缓存：自定义两级缓存（内存+磁盘）
• JSON处理：sonic（高性能JSON库）
• 并发控制：工作池模式
• HTTP客户端：自定义优化的HTTP客户端

2. 系统架构

2.1 整体架构

PanSou采用模块化的分层架构设计，主要包括以下几个层次：

┌─────────────────────────┐
│        API 层           │
│  (路由、处理器、中间件)  │
└───────────┬─────────────┘
            │
┌───────────▼─────────────┐
│        服务层           │
│    (搜索服务、缓存)      │
└───────────┬─────────────┘
            │
┌───────────▼─────────────┐    ┌─────────────────┐
│       插件系统          │◄───┤  插件注册表     │
│ (搜索插件、插件管理器)   │    └─────────────────┘
└───────────┬─────────────┘
            │
┌───────────▼─────────────┐
│       工具层            │
│ (缓存、HTTP客户端、工作池)│
└─────────────────────────┘

2.2 模块职责

2.2.1 API层

• 路由管理：定义API端点和路由规则
• 请求处理：处理HTTP请求，参数解析和验证
• 响应生成：生成标准化的JSON响应
• 中间件：跨域处理、日志记录、压缩等
• 参数规范化：统一处理不同形式但语义相同的参数

2.2.2 服务层

• 搜索服务：整合插件和Telegram搜索结果
• 结果处理：过滤、排序和分类搜索结果
• 缓存管理：管理搜索结果的缓存策略
• 缓存键生成：基于所有影响结果的参数生成一致的缓存键

2.2.3 插件系统

• 插件接口：定义统一的搜索插件接口
• 插件管理：管理插件的注册、获取和调用
• 自动注册：通过init函数实现插件自动注册
• 高性能JSON处理：使用sonic库优化JSON序列化/反序列化

2.2.4 工具层

• 缓存工具：两级缓存实现（内存+磁盘）
• HTTP客户端：优化的HTTP客户端，支持代理
• 工作池：并发任务执行的工作池
• JSON工具：高性能JSON处理工具

2.3 数据流

1. 请求接收：API层接收搜索请求
2. 参数处理：解析、验证和规范化请求参数
3. 缓存键生成：基于所有影响结果的参数生成一致的缓存键
4. 缓存检查：检查是否有缓存结果
5. 并发搜索：如无缓存，并发执行搜索任务
6. 结果处理：过滤、排序和分类搜索结果
7. 缓存存储：将结果存入缓存
8. 响应返回：返回处理后的结果

3. 核心设计思想

3.1 高性能设计

• 并发搜索：使用工作池模式实现高效并发
• 两级缓存：内存缓存提供快速访问，磁盘缓存提供持久存储
• 异步操作：非关键路径使用异步处理
• 内存优化：预分配策略、对象池化、GC参数优化
• 高效JSON处理：使用sonic库替代标准库，提升序列化性能

3.2 可扩展性设计

• 插件系统：通过统一接口和自动注册机制实现可扩展
• 模块化：清晰的模块边界和职责划分
• 配置驱动：通过环境变量实现灵活配置

3.3 可靠性设计

• 超时控制：搜索操作有严格的超时限制
• 错误处理：全面的错误捕获和处理
• 优雅降级：单个搜索源失败不影响整体结果
• 缓存一致性：确保相同语义的查询使用相同的缓存键

4. 代码组织结构

pansou/
├── api/                # API层
│   ├── handler.go      # 请求处理器
│   ├── middleware.go   # 中间件
│   └── router.go       # 路由定义
├── cache/              # 缓存数据存储目录
├── config/             # 配置管理
│   └── config.go       # 配置定义和加载
├── docs/               # 文档
│   ├── 1-项目总体架构设计.md   # 总体架构文档
│   ├── 2-API层设计.md        # API层设计文档
│   ├── 3-服务层设计.md        # 服务层设计文档
│   ├── 4-插件系统设计.md       # 插件系统设计文档
│   ├── 5-缓存系统设计.md       # 缓存系统设计文档
│   └── 插件开发指南.md         # 插件开发指南
├── model/              # 数据模型
│   ├── request.go      # 请求模型
│   └── response.go     # 响应模型
├── plugin/             # 插件系统
│   ├── plugin.go       # 插件接口和管理
│   ├── jikepan/        # 即刻盘插件
│   ├── hunhepan/       # 混合盘插件
│   ├── pansearch/      # 盘搜插件
│   ├── qupansou/       # 趣盘搜插件
│   ├── pan666/         # 盘666插件
│   └── panta/          # PanTa插件
├── service/            # 服务层
│   └── search_service.go # 搜索服务
├── util/               # 工具层
│   ├── cache/          # 缓存工具
│   │   ├── cache_key.go     # 优化的缓存键生成
│   │   ├── cache_key_test.go # 缓存键生成测试
│   │   ├── disk_cache.go    # 磁盘缓存
│   │   ├── two_level_cache.go # 两级缓存
│   │   ├── utils.go         # 缓存工具函数
│   │   └── utils_test.go    # 缓存工具测试
│   ├── compression.go  # 压缩工具
│   ├── convert.go      # 类型转换工具
│   ├── http_util.go    # HTTP工具函数
│   ├── json/           # 高性能JSON工具
│   │   └── json.go     # 基于sonic的JSON处理封装
│   ├── parser_util.go  # 解析工具
│   ├── pool/           # 工作池
│   │   ├── object_pool.go # 对象池
│   │   └── worker_pool.go # 工作池实现
│   └── regex_util.go   # 正则表达式工具
├── go.mod              # Go模块定义
├── go.sum              # 依赖版本锁定
├── main.go             # 程序入口
└── README.md           # 项目说明