FQuant Document

Appearance

FQBase - 设计原则 ​

阅读路径 ​

🟠🔵 架构师+开发者：README → design → architecture → patterns → development

设计原则 ​

原则应用
SOLID贯穿整个设计
DRY提取共享工具
KISS简单专注的组件
单一职责每个模块职责明确
开闭原则对扩展开放，对修改封闭

设计决策记录 ​

决策 1: 分层架构 ​

日期： 2025-06-01 状态： 已通过

上下文： 需要为 FQuant 项目提供统一的基础设施

选项分析：

选项优点缺点适用场景
单一模块简单职责混淆小型项目
分层架构职责清晰、易维护增加复杂度中大型项目

决策： 采用分层架构

理由： FQuant 是量化交易框架，基础设施层和业务层需要清晰分离，便于维护和测试。

后果：

  • 正面：模块职责清晰，易于维护
  • 负面：增加了一定的学习成本

决策 2: 单例模式 vs 依赖注入 ​

日期： 2025-08-15 状态： 已通过

上下文： 需要管理全局共享资源（数据库连接、缓存等）

选项分析：

选项优点缺点适用场景
单例模式简单直接难以测试、隐式依赖资源管理
依赖注入可测试、显式依赖需要容器业务对象

决策： 两种模式并存

理由：

  • 基础设施层使用单例（数据库连接、缓存）
  • 业务对象使用依赖注入（便于测试）

后果：

  • 正面：兼顾简单性和可测试性
  • 负面：两种模式需要开发者理解

决策 3: 缓存后端选择 ​

日期： 2025-10-01 状态： 已通过

上下文： 需要提供多级缓存支持

选项分析：

选项优点缺点适用场景
仅 Redis简单分布式部署复杂小规模
多级缓存灵活增加复杂度中大规模

决策： 支持 LocalMemory + Redis + MongoDB 三级缓存

理由： 不同部署场景需要不同的缓存策略，开发环境用内存，生产环境用 Redis。

后果：

  • 正面：灵活适应各种场景
  • 负面：缓存一致性问题需要开发者注意

技术权衡 ​

权衡 1: 同步 vs 异步事件处理 ​

考量因素：

因素同步处理异步处理
性能低高
复杂度低高
可靠性高中
调试难度低高

决策： 默认同步，支持异步（Celery）

后果：

  • 正面：简单场景直接使用，复杂场景可扩展
  • 负面：需要开发者理解两种模式

权衡 2: 熔断器阈值 ​

考量因素：

因素低阈值（3次）高阈值（10次）
敏感性高，快速熔断低，可能积累失败
可用性可能过度熔断可能雪崩

决策： 默认 5 次，支持自定义

后果：

  • 正面：大多数场景适用
  • 负面：特定场景可能需要调优

选型决策树 ​

需要使用 FQBase 吗？
    │
    ├── 需要基础设施吗？
    │       ├── 是 ──▶ 需要什么？
    │       │           ├── 日志/异常 ──▶ Infrastructure
    │       │           ├── 事件通信 ──▶ Foundation
    │       │           ├── 配置管理 ──▶ Config
    │       │           ├── 缓存 ──▶ Cache
    │       │           ├── 数据库 ──▶ DataStore
    │       │           └── 爬虫 ──▶ Crawler
    │       └── 否 ──▶ 考虑其他方案
    │
    └── 需要组合使用多个模块吗？
            ├── 是 ──▶ 使用组合导入
            └── 否 ──▶ 按需单独导入

扩展点 ​

扩展点方法描述
自定义缓存后端register_cache_adapter注册新的缓存适配器
自定义通知渠道继承 NotificationHandler添加新的通知方式
自定义事件处理实现 EventHandler添加异步事件处理

反模式警示 ​

错误示例 ​

python
# 在业务层直接使用 pymongo
from pymongo import MongoClient
client = MongoClient("mongodb://...")
db = client["mydb"]

正确做法 ​

python
# 使用 DataStore 门面
from FQBase.DataStore import get_mongo_db
db = get_mongo_db()
db.insert_one("collection", {"data": "value"})

使用的模式 ​

模式位置用途
单例模式Infrastructure/singleton.py全局实例管理
门面模式DataStore/mongo_db.py简化 MongoDB 操作
适配器模式Cache/CacheAdapters.py统一缓存接口
装饰器模式Infrastructure/retry.py重试机制
观察者模式Foundation/event_bus.py事件通信
工厂模式Cache/init.py缓存创建

相关文档 ​