15.自定义插件开发
本文将详细介绍如何在 Freqtrade 中开发自定义插件,包括插件的基本结构、钩子函数的使用方法、功能扩展技巧以及插件分享的最佳实践。通过本章的学习,我们将能够根据自己的交易需求,开发出符合个人策略的插件,从而增强 Freqtrade 的功能。
插件结构
Freqtrade 的插件系统设计灵活,允许开发者通过继承特定的基类来实现自定义功能。所有插件都需要遵循一定的结构规范,以确保能够被系统正确加载和运行。
基类继承
在开发插件时,首先需要选择合适的基类。对于 Pairlist 插件,需要继承 IPairList 类;对于 Protections 插件,则需要继承 IProtection 类。这些基类定义了插件必须实现的方法,确保插件能够与 Freqtrade 核心系统无缝集成。
以下是一个 Pairlist 插件的基本结构示例:
from freqtrade.plugins.pairlist.IPairList import IPairList
from typing import List, Dict
class CustomPairList(IPairList):
def __init__(self, exchange, pairlistmanager, config, pairlistconfig, pairlist_pos):
super().__init__(exchange, pairlistmanager, config, pairlistconfig, pairlist_pos)
# 初始化插件参数
self._number_assets = self._pairlistconfig.get('number_assets', 20)
@property
def needstickers(self) -> bool:
# 是否需要 ticker 数据
return True
def short_desc(self) -> str:
# 插件简短描述
return f"CustomPairList - top {self._number_assets} pairs"
def gen_pairlist(self, tickers: Dict) -> List[str]:
# 生成初始交易对列表
pairs = self._exchange.get_markets().keys()
# 自定义筛选逻辑
filtered_pairs = self._filter_pairs(pairs, tickers)
return filtered_pairs[:self._number_assets]
def _filter_pairs(self, pairs: List[str], tickers: Dict) -> List[str]:
# 实现自定义筛选逻辑
filtered = []
for pair in pairs:
# 例如:筛选出价格大于 0.001 的交易对
if tickers[pair]['last'] > 0.001:
filtered.append(pair)
return filtered
配置参数
插件的配置参数需要在构造函数中进行初始化,并可以通过配置文件进行自定义。建议使用 _pairlistconfig 或 _config 来获取用户配置的参数,以保持与 Freqtrade 配置系统的一致性。
例如,在上述示例中,number_assets 参数通过 self._pairlistconfig.get('number_assets', 20) 获取,允许用户在配置文件中自定义该值。
钩子函数
钩子函数是插件与 Freqtrade 核心系统交互的关键。通过重写基类中的钩子函数,插件可以在特定事件发生时执行自定义逻辑。
Pairlist 插件钩子
对于 Pairlist 插件,主要的钩子函数包括:
gen_pairlist(tickers: Dict) -> List[str]: 生成初始交易对列表,当插件作为链中的第一个处理器时调用。filter_pairlist(pairlist: List[str], tickers: Dict) -> List[str]: 过滤交易对列表,当插件作为链中的后续处理器时调用。
以下是 filter_pairlist 方法的实现示例,用于根据交易量过滤交易对:
def filter_pairlist(self, pairlist: List[str], tickers: Dict) -> List[str]:
# 按交易量排序并筛选
sorted_pairs = sorted(pairlist, key=lambda x: tickers[x]['quoteVolume'], reverse=True)
return sorted_pairs[:self._number_assets]
Protections 插件钩子
对于 Protections 插件,主要的钩子函数包括:
global_stop(date_now: datetime) -> ProtectionReturn: 全局停止交易检查,返回是否需要停止所有交易对的交易。stop_per_pair(pair: str, date_now: datetime) -> ProtectionReturn: 单交易对停止检查,返回是否需要停止特定交易对的交易。
以下是 stop_per_pair 方法的实现示例,用于实现交易对的冷却期保护:
from freqtrade.plugins.protections.IProtection import IProtection, ProtectionReturn
from datetime import datetime, timedelta
class CustomCooldownProtection(IProtection):
def __init__(self, config, protection_config):
super().__init__(config, protection_config)
self._stop_duration = self._protection_config.get('stop_duration_candles', 2)
def short_desc(self) -> str:
return f"CustomCooldownProtection - {self._stop_duration} candles"
def stop_per_pair(self, pair: str, date_now: datetime) -> ProtectionReturn:
# 获取该交易对的最近交易
trades = self._db.get_trades(pair=pair, limit=1)
if trades:
last_trade = trades[0]
# 计算冷却期结束时间
lock_end = last_trade.close_date + timedelta(minutes=self._stop_duration * self._config['timeframe_minutes'])
if date_now < lock_end:
return ProtectionReturn(True, lock_end, f"Cooldown period active until {lock_end}")
return ProtectionReturn(False, None, "")
功能扩展
除了基本的插件结构和钩子函数,还可以通过以下方式扩展插件的功能:
注册插件
开发完成的插件需要注册到 Freqtrade 系统中,才能在配置文件中使用。对于 Pairlist 插件,需要将其添加到 constants.py 文件的 AVAILABLE_PAIRLISTS 列表中:
# freqtrade/constants.py
AVAILABLE_PAIRLISTS = {
# ...
'CustomPairList': 'freqtrade.plugins.pairlist.CustomPairList',
# ...
}
使用缓存
为了提高性能,对于计算密集型或网络请求频繁的插件,可以实现缓存机制。例如,在 gen_pairlist 方法中,可以检查缓存是否过期,避免重复计算:
def gen_pairlist(self, tickers: Dict) -> List[str]:
if self._cached_pairlist and not self._is_cache_expired():
return self._cached_pairlist
# 生成新的交易对列表
self._cached_pairlist = self._calculate_pairlist(tickers)
self._cache_expiry = datetime.now() + timedelta(seconds=self._refresh_period)
return self._cached_pairlist
集成外部数据
插件可以集成外部数据源来增强功能。例如,从外部 API 获取市场情绪数据,用于交易对筛选:
import requests
def _get_market_sentiment(self, pair: str) -> float:
# 调用外部 API 获取情绪分数
response = requests.get(f"https://api.example.com/sentiment/{pair}")
return response.json().get('score', 0.5)
def _filter_pairs(self, pairs: List[str], tickers: Dict) -> List[str]:
filtered = []
for pair in pairs:
sentiment = self._get_market_sentiment(pair)
if sentiment > 0.7:
filtered.append(pair)
return filtered
插件分享
开发完成的插件可以分享给其他 Freqtrade 用户,以下是一些分享的最佳实践:
文档编写
为插件编写清晰的文档,包括:
- 插件功能描述
- 配置参数说明
- 使用示例
- 依赖项列表
例如:
# CustomPairList 插件
## 功能
根据市场情绪和交易量筛选交易对。
## 配置参数
- `number_assets`: 保留的交易对数量,默认 20
- `sentiment_threshold`: 情绪分数阈值,默认 0.7
## 使用示例
"pairlists": [
{
"method": "CustomPairList",
"number_assets": 15,
"sentiment_threshold": 0.6
}
]
代码规范
遵循 Freqtrade 的代码规范,包括:
- 使用类型注解
- 编写单元测试
- 遵循 PEP 8 编码规范
例如,为插件编写单元测试:
# tests/plugins/test_custom_pairlist.py
import pytest
from freqtrade.plugins.pairlist.CustomPairList import CustomPairList
def test_gen_pairlist(mocker):
# 模拟交易所和 ticker 数据
exchange = mocker.Mock()
exchange.get_markets.return_value = {'BTC/USDT': {}, 'ETH/USDT': {}}
tickers = {
'BTC/USDT': {'last': 0.002, 'quoteVolume': 1000},
'ETH/USDT': {'last': 0.0015, 'quoteVolume': 800}
}
# 初始化插件
pairlist = CustomPairList(exchange, None, {}, {'number_assets': 1}, 0)
# 测试生成交易对列表
result = pairlist.gen_pairlist(tickers)
assert len(result) == 1
assert result[0] == 'BTC/USDT'
社区贡献
如果插件具有通用性,可以考虑通过 Pull Request 将其贡献给 Freqtrade 官方代码库。在提交之前,确保:
- 插件功能符合 Freqtrade 的设计理念
- 代码经过充分测试
- 文档完整且易于理解
通过社区贡献,不仅可以帮助其他用户,还能获得来自 Freqtrade 开发团队的反馈和改进建议。
总结
自定义插件开发是扩展 Freqtrade 功能的强大方式。通过继承适当的基类、实现钩子函数、合理配置参数,以及遵循最佳实践,我们可以开发出高效、可靠的插件。无论是用于交易对筛选、风险保护,还是集成外部数据,插件都能为我们的量化交易策略提供更多可能性。希望本章的内容能够帮助我们顺利开发出自己的第一个 Freqtrade 插件,并在社区中分享我们的成果。