接口重构审查报告¶
范围：v0.6 统一接口重构（
TdxData对外方法 51 → 63）的数据一致性与遗漏审查。 结论基于对旧实现（git show HEAD:src/pytdxdata/api.py）与新实现的逐字段 / 逐方法对照。
一、结论速览¶
| 维度 | 结论 |
|---|---|
| 数据一致性（旧接口 vs 统一接口） | ✅ 55 条断言全部通过，无字段差异 |
| 方法丢失 | ✅ 无。旧 53 个公开方法 100% 保留 |
| 文档覆盖 | ✅ scripts/check_docs.py 三条硬约束通过 |
| 标的写法 | ✅ 统一接口一律只接受字符串，已无元组软兼容 |
| 公开方法计数 | 28 统一 + 33 别名 + start/close = 63 |
二、数据一致性（旧接口 vs 新统一接口）¶
逐字段对照 24+ 组、55 条断言全部通过，覆盖：
- K 线（各周期 / 复权 / 日期区间）
- 实时报价（五档 bid/ask、买卖量、涨跌停价）
- 逐笔成交（含
trade_count） - 分时
- 除权除息
- 财务快照
- F10（目录 + 正文）
- 服务器文件（板块 / 行业 / 财报）
- 板块（列表 / 成员 / 归属 / 汇总 / 排行）
唯一 1 条「失败」经核实为 mock 假象：security_count 的 mock 返回固定值 100，而
get_universe 走真实分页逻辑，两者口径不同；并非真实数据差异，逐字段比较全部相等。
三、遗漏审查（方法级）¶
对旧 / 新 api.py 的公开方法集合做 AST 级 diff：
| 指标 | 数量 |
|---|---|
| 旧公开方法 | 53（51 数据 + start / close） |
| 新公开方法 | 63（61 数据 + start / close） |
| 旧有新无（丢失） | 0 |
| 新增 | 10（全部为统一入口） |
数值闭合：
28 统一 + 33 废弃别名 + start/close = 6318 旧名升级 + 33 转别名 = 51 旧数据方法51 旧 + 10 新入口 = 61 数据方法
四、统一接口清单（28 个数据接口）¶
标的写法："sz000001" / "hk00700" / "usAAPL" / "cffex:IFL0"；裸 6 位数字 = 沪市指数。
4.1 新入口（10，v0.6 新增）¶
| 方法 | 签名 | 返回 | 吸收的旧接口 |
|---|---|---|---|
get_universe |
(market=None) |
list[SecurityInfo] |
get_security_count / get_security_list / get_security_list_all / get_goods_list / get_goods_count |
get_bars |
(symbols, period=DAY, *, start=0, count=800, adjust=None, start_date=None, end_date=None, concurrency=6) |
list[SecurityBar] |
get_kline / get_kline_since / get_kline_batch / get_index_kline |
get_indicators |
(symbols, indicators, *, period=DAY, count=30, adjust=None, params=None) |
list[IndicatorSet] |
get_stock_kline_with_indicators |
get_ticks |
(symbols, *, date=None, start=0, count=None, concurrency=6) |
list[TransactionRecord] |
get_transactions / get_goods_transaction / get_goods_transaction_all |
get_minutes |
(symbols, *, date=None, sampling=False, concurrency=6) |
list[MinuteBar] |
get_minute / get_minute_batch / get_chart_sampling / get_goods_chart_sampling / get_goods_tick_chart |
get_snapshot |
(symbols) |
list[SymbolSnapshot] |
get_symbol_info |
get_f10 |
(symbol, section=None, *, offset=0, length=65535) |
list \| str |
get_company_info_category / get_company_info_content |
get_file |
(name) |
bytes |
get_block_info / get_report_file / get_file_meta / download_file / get_financial_file_list / get_financial_records |
get_boards |
(kind="all", *, count=10000) |
list[BoardInfo] |
get_board_list |
get_board_of |
(symbols) |
list[BelongBoard] |
get_belong_board |
4.2 旧名升级（18，同名泛化为统一接口）¶
| 方法 | 签名 | 返回 |
|---|---|---|
get_quotes |
(symbols, *, fields=None) |
list[SecurityQuote] |
get_auction |
(symbols) |
list[AuctionItem] |
get_capital_flow |
(symbols) |
list[CapitalFlow] |
get_xdxr |
(symbols) |
list[XdxrRecord] |
get_finance |
(symbols) |
list[FinanceRecord] |
get_price_limits |
(symbol, name=None, pre_close=None, listed_days=9999) |
tuple[float\|None, float\|None] |
get_market_stat |
() |
MarketStat |
get_unusual |
(market="all", *, start=0, count=600) |
list[UnusualItem] |
get_server_info |
() |
ServerInfo |
get_kline_offset |
(offset=0, count=1) |
tuple[int, int] |
get_board_members |
(board, count=100000, sort_type=0, *, fields=None) |
list[SecurityQuote] |
get_board_summary |
(board) |
dict |
get_board_ranking |
(kind="industry", *, top_n=20) |
list[dict] |
get_board_change_ranking |
(kind="industry", *, days=20, top_n=20) |
list[dict] |
get_block_parsed |
(filename) |
list[TdxBlock] |
get_industry_map |
() |
dict[str, IndustryInfo] |
get_financial_file_infos |
() |
list[FinancialFileInfo] |
get_financial_records_parsed |
(filename) |
list[FinancialRecord] |
另有生命周期方法
start()/close()，合计 30 个非别名公开方法。
五、废弃别名清单（33 个，1.0 移除）¶
别名运行时发出 DeprecationWarning；仍接受 (market, code) 写法（这是别名与统一接口的关键差异）。
| 目标统一接口 | 数量 | 废弃别名 |
|---|---|---|
get_bars |
4 | get_kline、get_kline_since、get_kline_batch、get_index_kline |
get_indicators |
1 | get_stock_kline_with_indicators |
get_quotes |
3 | get_stock_quotes、get_goods_quotes、get_goods_quotes_list |
get_board_members |
1 | get_stock_quotes_list |
get_ticks |
3 | get_transactions、get_goods_transaction、get_goods_transaction_all |
get_minutes |
3 | get_minute、get_minute_batch、get_goods_tick_chart |
get_minutes(sampling=True) |
2 | get_chart_sampling、get_goods_chart_sampling |
get_universe |
5 | get_security_count、get_security_list、get_security_list_all、get_goods_list、get_goods_count |
get_f10 |
2 | get_company_info_category、get_company_info_content |
get_file |
4 | get_block_info、get_report_file、get_file_meta、download_file |
get_financial_file_infos |
1 | get_financial_file_list |
get_financial_records_parsed |
1 | get_financial_records |
get_boards |
1 | get_board_list |
get_board_of |
1 | get_belong_board |
get_snapshot |
1 | get_symbol_info |
| 合计 | 33 |
六、标的写法统一（字符串化）¶
统一接口只接受字符串标的，已移除所有 (market, code) 元组软兼容：
- 删除模块级
_as_symbols()；get_quotes/get_xdxr/get_finance/get_auction/get_capital_flow去掉code位置参数，统一走parse_symbols()。 get_price_limits去掉(market, code, …)旧参形式检测。get_unusual去掉整数市场号检测。- 调用方（CLI、示例）同步改为字符串；
get_finance/get_capital_flow的返回类型改为list。
保留项
get_boards(kind) 仍接受数字板块类别（0/1/2/3）。这是板类别选择器、非标的，
文档已明示「也接受数字」，旧别名 get_board_list(board_type=0) 依赖它。
七、验证¶
pytest：127 passed（审查当时的快照；当前基线为 164 passed）。其中tests/test_all_interfaces.py为全接口回归：mock 连接逐个 调用 63 个公开方法，并以「覆盖哨兵」断言无遗漏（7 条告警为别名测试的预期DeprecationWarning）。scripts/check_docs.py：MUST_LIST_ALL+MUST_NOT_BE_STALE全部[OK]。- 签名核对：统一接口签名与返回类型与本文一致；全仓无
_as_symbols及元组式调用残留。