前言
国内期货量化程序里，每一个订阅、每一笔报单都要写「合约代码」字符串，天勤 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没有交易所前缀。 - 郑商所年份位数错：
SR2509vsSR509。 - 把模拟盘月份抄成已交割旧月。
- 信号用主连
KQ.m@，下单忘记映射到具体月份。 - 复制粘贴带空格或全角字符。
三、启动时校验清单
defvalidate_symbol(api,symbol):q=api.get_quote(symbol)for_inrange(10):api.wait_update()ifq.datetime==q.datetime:breakifq.ins_class!="FUTURE":# 或你期望的类型raiseValueError(f"unexpected ins_class{q.ins_class}for{symbol}")ifq.volume==0andq.open_interest==0:log.warning("zero volume and oi, check symbol %s",symbol)returnq对比quote.instrument_id、quote.exchange_id与配置是否一致。下单前打印symbol、last_price、expire_rest_days到日志，首日人工扫一眼。
四、与 get_position 的一致性
get_position("SHFE.rb2510")的 key 必须与TargetPosTask创建时 symbol 完全一致，否则读到空持仓。多策略配置文件建议集中SYMBOL常量，禁止在代码里散落字符串。
五、query_quotes 辅助纠错
若只记得品种，可先：
api.query_quotes(ins_class="FUTURE",product_id="rb",expired=False)从返回列表里选持仓量最大月份作为主力，减少手写月份错误。
六、配置中心化
# config.pySYMBOLS={"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 整理，不构成投资建议。
