JoinQuant 如何获取指定期货品种的可交易合约列表？

在 JoinQuant（聚宽）平台中，获取某个期货品种当前所有可交易合约代码，主要使用 get_future_contracts 函数。

以下是详细的使用说明和代码示例。

核心函数：get_future_contracts

该函数用于获取某期货品种在策略当前日期（或指定日期）的可交易合约标的列表。

函数签名：

get_future_contracts(security, date=None)

参数说明：

• security: 期货合约品种代码（字符串），例如 'AG' (白银)、'IF' (沪深300股指期货)、'RB' (螺纹钢)。注意这里不需要加交易所后缀（如 .XSGE）。
• date: 查询日期。
  • 在回测/模拟交易中：若不填，默认为当前回测日期。
  • 在研究模块中：若不填，默认为最新日期。
  • 也可以指定具体的日期字符串（如 '2023-01-01'）。

返回值：

• 返回一个包含合约代码字符串的列表（List）。

代码示例

1. 在研究环境（Notebook）中使用

如果您是在研究模块中查询，可以直接运行以下代码：

# 导入聚宽数据库
from jqdata import *

# 获取 螺纹钢 (RB) 当前所有可交易的合约
rb_contracts = get_future_contracts('RB')
print("螺纹钢当前可交易合约：")
print(rb_contracts)

# 获取 沪深300股指期货 (IF) 在指定日期 (2023-06-01) 的可交易合约
if_contracts_history = get_future_contracts('IF', date='2023-06-01')
print("\n2023-06-01 沪深300股指期货可交易合约：")
print(if_contracts_history)

2. 在策略回测/模拟交易中使用

如果您是在编写策略，通常在 initialize 或 handle_data 等函数中调用：

# -*- coding: utf-8 -*-
from jqdata import *

def initialize(context):
    # 设置基准
    set_benchmark('000300.XSHG')
    
    # 获取 黄金 (AU) 当前回测日期的所有可交易合约
    # 注意：这里传入的是品种代码 'AU'
    contracts = get_future_contracts('AU')
    
    log.info("当前日期: %s" % context.current_dt)
    log.info("黄金可交易合约列表: %s" % contracts)
    
    # 示例：选择列表中的第一个合约作为操作标的（仅作演示）
    if len(contracts) > 0:
        g.target_contract = contracts[0]
        log.info("选择操作合约: %s" % g.target_contract)

def handle_data(context, data):
    pass

注意事项

1. 品种代码格式：调用该函数时，传入的 security 参数仅需品种代码（如 'RB', 'AU', 'IF'），不要传入具体的合约代码（如 'RB2310.XSGE'）或主力合约代码（如 'RB9999.XSGE'）。
2. 交易所后缀：返回的合约列表中的代码是包含交易所后缀的完整代码（例如 ['RB2310.XSGE', 'RB2401.XSGE', ...]），可以直接用于下单函数 order 或获取行情函数 get_price。
3. 数据范围：该函数返回的是在该日期交易所挂牌交易的所有合约，包含主力合约、次主力合约以及远月合约。

Q&A

Q: 如何获取某个期货品种的主力合约代码？
A: 获取主力合约代码请使用 get_dominant_future(underlying_symbol, date=None) 函数。例如 get_dominant_future('RB') 会返回当前日期的螺纹钢主力合约（如 'RB2310.XSGE'）。

Q: get_future_contracts 返回的列表中包含主力连续合约（如 9999）吗？
A: 不包含。get_future_contracts 返回的是具体的、真实存在的交割月合约（如 RB2310.XSGE）。RB9999.XSGE 是聚宽为了方便回测拼接的虚拟合约，不属于交易所挂牌的可交易合约。

Q: 如果传入了错误的品种代码会怎样？
A: 如果传入了不存在的品种代码，函数通常会返回一个空列表 [] 或者抛出异常，建议确保传入标准的品种代码（大写字母）。