RQAlpha 项目研究站 · 策略 API

RQAlpha 策略 API：约定函数、取数接口与下单接口

官方文档把策略 API 分为约定函数、数据查询接口、交易接口三类：约定函数是框架回调你的入口（init、before_trading、handle_bar、after_trading），数据查询负责取历史与合约信息，交易接口负责下单。策略要做的，就是在这几个回调里把「取数 → 算信号 → 下单」串起来。

下一步：回测指标回到运行方式

API 手册：docs 的 base_api / extend_api示例策略：rqalpha examples -d ./依据官方 tutorial 与 API 文档（2026-09 核验）

init
初始化上下文

before_trading
盘前准备

handle_bar
取数·算信号·下单

after_trading
盘后处理

依据官方 API 文档整理的策略回调顺序示意；非官方流程图。

Callbacks

策略的四个约定函数

「约定函数」是策略与框架的接口：不实现就无法正确运行。

函数	触发时机	典型用途	注意点
`init(context)`	程序启动时执行一次	把标的、参数（如长短均线周期）挂到 `context` 上	不要在 init 里下单；参数用 `context.XXX` 保存以便调优
`before_trading(context)`	每个交易日开盘前一次	盘前筛选股票池、准备当日要用的数据	此时当日 Bar 还没有，取不到当日行情
`handle_bar(context, bar_dict)`	所订阅标的的 Bar 数据更新时	策略主体：读取历史数据、计算信号、调用下单接口	日频策略每天触发一次；分钟频由频率配置决定
`after_trading(context)`	每个交易日收盘后一次	盘后统计、记录当日状态	不要在此下当日单（交易日已结束）

额外回调：系统 Mod sys_scheduler 提供定时器能力（按周期执行指定逻辑）；Mod 还可以通过 Hook 挂到框架的其它阶段（见 Mod 扩展页）。官方示例策略用 rqalpha examples -d ./ 生成，建议先跑通 buy_and_hold.py 与 golden_cross.py 再写自己的。

Data API

数据查询接口

官方 tutorial 列出的常用接口；财务与更细的市场数据在 extend_api 中说明。

接口	作用	用法要点
`history_bars()`	取某合约的历史行情（含 close 等字段）	示例：`history_bars(标的, 长度, '1d', 'close')`；长度要足够算你需要的均线窗口
`all_instruments()` / `instruments()`	获取全部或指定合约的基础信息、详细数据	用于按类型筛选股票池（如只看股票或期货）
`current_snapshot()`	当前快照数据	需要更高频细节时使用；日频策略通常用 bar_dict 即可
`get_future_contracts()`	获取期货可交易合约列表	期货策略选合约必用；要注意主力合约切换
`get_trading_dates()`、`get_previous_trading_date()`、`get_next_trading_date()`	交易日历相关查询	做 T+N 逻辑、调仓日计算时用，避免自己造日历
`is_suspended()`、`is_st_stock()`	判断停牌、判断 ST	选股与下单前过滤，可显著减少无效订单
`get_yield_curve()`	获取收益率曲线	债券/利率相关研究使用
`bar_dict[标的]`	在 `handle_bar` 中取当前 Bar 数据	字典式访问，可拿 close、volume 等字段

数据不只是行情：官方的 Ricequant 金融、财务、合约历史数据接口在 extend_api 中说明（部分需要 RQData 权限）；开源版自带的数据范围见安装与数据页。

Trading API

交易接口

股票与期货的下单接口分开设计，命名上就能区分：股票用 order_*，期货用 buy_open/sell_close 等。

接口	适用	说明
`order_shares()`	股票	按股数下单（教程中用它按现金可买数量建仓）
`order_lots()`	股票	按手数下单（A 股一手 100 股的场景更直观）
`order_value()` / `order_percent()`	股票	按金额或按组合比例下单
`order_target_value()` / `order_target_percent()`	股票	按目标金额/目标比例调仓（`order_target_value(标的, 0)` 即清仓）
`buy_open()` / `sell_close()`	期货	买开仓、平买仓
`sell_open()` / `buy_close()`	期货	卖开仓、平卖仓
`cancel_order()` / `get_open_orders()`	通用	撤单与查询未成交订单
`get_position()`、`context.portfolio`	通用	查询持仓与组合（现金、市值等），是仓位控制的基础

下单前的三道过滤：先判断是否停牌（is_suspended）、是否 ST（is_st_stock）、资金是否够（context.portfolio.cash）——官方教程里的 shares = 现金 / 收盘价 就是这个思路的简化版。

Example

双均线策略：从空架子到可回测

官方 tutorial 用「金叉策略」演示完整链路，步骤可直接照搬。

1. 搭空架子

先写 init / before_trading / handle_bar / after_trading 四个函数，跑起来只打日志，确认框架能启动。

2. 取历史数据

在 handle_bar 里用 history_bars 取足够长的收盘价序列，交给 talib 等库算指标。

3. 写信号与下单

比较相邻两根 Bar 的均线关系：下穿且持仓则 order_target_value(标的, 0) 清仓；上穿则建仓。

4. 记录与验证

用 plot() 把指标写进结果文件，跑完回测看曲线与 summary 指标，再决定要不要调参。

运行官方示例的命令

rqalpha run -s 2014-01-01 -e 2016-01-01 -f rqalpha/examples/golden_cross.py --account stock 100000 -p -bm 000001.XSHE（官方 tutorial 给出的写法）。示例策略可通过 rqalpha examples -d ./ 生成到本地目录再改。

下一步：回测指标

Pitfalls

写策略时的常见坑

多数来自「回调时机」与「数据长度」两类问题。

坑	为什么发生	怎么避免
指标前几十根为 NaN	均线窗口没有足够历史数据	history_bars 的长度取「窗口 + 1」；回测起始日不要贴着数据起点
bar_dict 取不到某标的	该标的当日停牌 / 未订阅	用 `is_suspended` 过滤；在 init 里 `subscribe` 或 `update_universe` 声明关注标的
同一根 Bar 反复触发下单	信号条件在多个 Bar 上持续成立	用「前一根/当前根」的交叉判断，或在 context 里记录已触发标记
回测很快但没有交易	日期区间没有数据、账户类型写错、资金为 0	核对 `-s/-e`、`--account` 与 bundle 覆盖范围
talib 相关导入失败	本地未安装 TA-Lib	按官方示例安装 TA-Lib；不想装就用 numpy/pandas 自己实现均线
plot 的数据取不到	没有调用 plot，或输出文件里 keys 名称记错	在 handle_bar 里显式 `plot("名称", 值)`；结果读取见回测指标页

FAQ

常见问题

策略必须实现全部四个函数吗？

不必。官方说约定函数是「用户必须实现对应的约定函数才可以正确使用」，其中 init 与 handle_bar 是核心；before_trading / after_trading 按需实现（官方教程里的空实现 pass 也能跑）。

from rqalpha.api import * 会不会污染命名空间？

官方示例与教程都使用 from rqalpha.api import * 的写法（logger、history_bars、order_shares 等都来自这里）。工程化项目可以改为显式导入以提高可读性，但需逐一对照 API 文档，避免漏掉函数。

想用财务、因子等数据怎么办？

基础数据查询 API 之外，财务与更丰富的市场数据在 Ricequant 的扩展数据接口中（extend_api），部分需要 RQData 权限；也可以实现自有数据源接口把这些数据接进来。

能一次持有多个标的吗？

可以，策略里维护一个标的列表（写在 context 中）并逐个取数、下单即可；官方示例也演示了通过 update_universe 声明关注标的的写法。

策略写好了怎么验证它没有未来函数？

重点检查两点：handle_bar 里只能用到当前 Bar 及之前的数据（不要用全量 DataFrame 做 shift 反向对齐），以及不要用 after_trading 的数据回填当日交易决策。框架不会替你识别这类问题。

API 会随版本变化吗？

会。项目按 release/x.y.z 发布（最新 release/6.3.0，2026-07-23），API 细节请以你安装版本对应的官方文档为准；本页只做导航与要点归纳。