joinquant 如何使用 get_trade_day 正确获取期货夜盘对应的真实交易日？

在期货量化交易中，夜盘（交易日开端）与自然日不一致是编写策略时最容易踩坑的点。例如，周五晚上 21:00 开始的夜盘，在自然日上是周五，但在期货交易所的规则中，它属于下一个交易日（即周一）。

JoinQuant（聚宽）提供了专用 API 函数 get_trade_day，专门用于根据具体时刻和标的代码准确获取其对应的交易所交易日。

一、get_trade_day 函数语法

get_trade_day 函数可传入指定的标的代码及具体时刻，返回该时刻在交易所逻辑下对应的交易日。如果传入多个标的，可同时返回各自对应的交易日。

函数定义：

get_trade_day(security, query_dt)

参数说明：

• security (str | list)：标的代码，如 'RB1901.XSGE' 或字符串列表 ['RB1901.XSGE', '000001.XSHE']。
• query_dt (str | datetime)：查询的具体时刻，如 '2019-01-04 22:00:00'。必须指定，无默认值。

返回值：

• 返回一个 dict，Key 为标的代码，Value 为 datetime.date 对象（如非交易时间或未上市/退市标的则返回 None）。

二、期货交易日划分规则

在 JoinQuant 引擎中，交易日定义如下：

1. 无夜盘品种/股票：以每日 00:00 作为交易日开始，至下一个交易日 00:00 结束。
2. 有夜盘品种：以夜盘集合竞价开始时作为一个交易日的开始，至下一个交易日夜盘集合竞价开始时结束。
3. 若传入时刻处于夜盘（如周五 21:30），则该时刻归属于下一个交易日（周一）。

三、使用示例与代码展示

1. 基础用法对比分析

from jqdata import *

# 示例 1：查询周五夜盘时段（2019-01-04 22:00:00 是周五晚上）
# 螺纹钢（RB）有夜盘，此时已进入 2019-01-07（周一）的交易日
# 平安银行（股票）无夜盘，仍属于 2019-01-04（周五）交易日
res = get_trade_day(["RB1901.XSGE", "000001.XSHE"], query_dt="2019-01-04 22:00:00")
print(res)
# 输出结果：
# {'RB1901.XSGE': datetime.date(2019, 1, 7), '000001.XSHE': datetime.date(2019, 1, 4)}

2. 在期货策略中动态获取当前真实交易日

在定时运行函数或 handle_tick 中，可以通过 context.current_dt 动态查询当前期货标的对应的真实交易日：

import jqdata

def initialize(context):
    set_option('use_real_price', True)
    # 订阅螺纹钢主力合约
    g.security = 'RB2405.XSGE'
    # 定时在夜盘开盘后执行
    run_daily(check_trading_day, time='21:05', reference_security=g.security)

def check_trading_day(context):
    current_time = context.current_dt
    # 查询当前时刻对应的真实期货交易日
    trade_day_dict = get_trade_day(g.security, current_time)
    real_trade_day = trade_day_dict.get(g.security)
    
    log.info(f"自然日时间: {current_time}, 期货所属真实交易日: {real_trade_day}")

四、常见注意事项

1. 参照标的（reference_security）设置：
   在使用 run_daily / run_weekly 等计划任务时，期货策略务必将 reference_security 设置为对应的期货品种/主力合约（如 'RB9999.XSGE'），否则开盘运行时间会按照默认的股票时间（09:30）执行，从而错过夜盘。
2. 非法/非交易时间查询：
   如果传入的 query_dt 位于两个交易日之间的非交易休市时段，get_trade_day 会返回上一个交易日；若传入不存在的标的代码，则会抛出异常。
3. 数据获取与历史回溯：
   获取期货行情数据（如使用 get_bars 或 get_price）时，时间区间应注意结合交易日进行筛选，避免将夜盘与日盘的数据归期搞错。