期货量化合约代码写错：天勤 symbol 格式与 silent 订阅坑

前言

国内期货量化程序里，每一个订阅、每一笔报单都要写「合约代码」字符串，天勤 TqSdk 里叫 symbol。例如螺纹钢 2025 年 10 月合约写作 SHFE.rb2510（上期所 SHFE + 品种 rb + 月份 2510）。程序用 api.get_quote(symbol) 订行情、用 get_kline_serial(symbol, 300) 订 5 分钟 K 线算均线信号、用 TargetPosTask(api, symbol) 在该合约上调仓。代码写错时，Python 往往不报错------get_quote 仍能返回对象，但可能是另一张合约、或长期无成交的冷门月份，均线信号在白算，下单则挂在错误的盘上。

常见错误：大小写写反、漏交易所前缀、郑商所月份位数搞错。下面说明天勤标准格式、启动时怎么校验、如何用 query_quotes 减少手写月份失误。

一、标准 symbol 格式

交易所	exchange_id	示例
上期所	SHFE	SHFE.cu2510
大商所	DCE	DCE.i2509
郑商所	CZCE	CZCE.TA509
中金所	CFFEX	CFFEX.IF2509
能源中心	INE	INE.sc2510

主连示例：KQ.m@SHFE.rb（以官方文档为准）。组合：DCE.SP m2509&m2511 等。

大小写：品种代码通常小写（rb、cu），与 query_quotes 返回一致。

二、常见错误模式

只有 rb2510 没有交易所前缀。
郑商所年份位数错：SR2509 vs SR509。
把模拟盘月份抄成已交割旧月。
信号用主连 KQ.m@，下单忘记映射到具体月份。
复制粘贴带空格或全角字符。

三、启动时校验清单

python 复制代码

def validate_symbol(api, symbol):
    q = api.get_quote(symbol)
    for _ in range(10):
        api.wait_update()
        if q.datetime == q.datetime:
            break
    if q.ins_class != "FUTURE":  # 或你期望的类型
        raise ValueError(f"unexpected ins_class {q.ins_class} for {symbol}")
    if q.volume == 0 and q.open_interest == 0:
        log.warning("zero volume and oi, check symbol %s", symbol)
    return q

对比 quote.instrument_id、quote.exchange_id 与配置是否一致。下单前打印 symbol、last_price、expire_rest_days 到日志，首日人工扫一眼。

四、与 get_position 的一致性

get_position("SHFE.rb2510") 的 key 必须与 TargetPosTask 创建时 symbol 完全一致，否则读到空持仓。多策略配置文件建议集中 SYMBOL 常量，禁止在代码里散落字符串。

五、query_quotes 辅助纠错

若只记得品种，可先：

python 复制代码

api.query_quotes(ins_class="FUTURE", product_id="rb", expired=False)

从返回列表里选持仓量最大月份作为主力，减少手写月份错误。

六、配置中心化

python 复制代码

# config.py
SYMBOLS = {
    "rb_trade": "SHFE.rb2510",
    "rb_signal": "KQ.m@SHFE.rb",
}

全项目只 import 这一处，禁止在五个文件里各写一遍字符串。

七、下单前双人复核字段

首日实盘或换月日，日志打印 instrument_id、exchange_id、expire_rest_days、last_price，人工扫一眼再放开自动交易开关。

八、郑商所三位年份坑

CZCE.SR509 表示 2025 年 9 月，不是 SR2509。从别的交易所习惯拷贝代码时最容易错。

九、事故复盘字段

一旦出现盈亏异常，第一时间日志应能回答：当时 symbol 字符串、instrument_id、exchange_id、last_price 与预期品种是否一致。很多「策略突然不行」其实是换月后配置文件没改一行字。

总结

合约代码写错不会总在启动时报错，但会在成交、持仓、盈亏上悄悄偏离。天勤要求 交易所.合约 统一格式，郑商所月份位数、主连与具体月分工尤其容易踩坑。启动时用 get_quote 校验 ins_class、成交量持仓量，用 query_quotes 生成候选列表，并把 symbol 收敛到配置常量，能避免绝大多数 silent wrong symbol 事故。代码正确性优先于参数优化，这是期货程序化里成本最低的保险。

FAQ

1）行情有但下单拒单？

查是否交易非可下单合约类型（指数、连续仅行情）。

2）TqAccount 与 symbol 交易所要一致吗？

账户需有该交易所交易权限。

3）组合合约 symbol 怎么写？

见官方组合代码说明，与单腿不同。

4）能否从主力自动解析？

可用 quote.underlying_symbol 或主连服务，但要显式映射到下单月。

本文基于天勤 TqSdk 公开 API 整理，不构成投资建议。