PanWatch marketdata 包拆解一个 Symbol 值对象如何统一 A股、港股、美股代码【免费下载链接】PanWatchPanWatch — AI stock monitoring for A-shares, HK US markets, powered by TradingAgents. Portfolio insights, real-time alerts automated reports.盯盘侠覆盖 A股/港股/美股的 AI 盯盘、持仓分析、实时提醒与自动报告。项目地址: https://gitcode.com/GitHub_Trending/pa/PanWatchPanWatch盯盘侠是一个覆盖 A股、港股、美股的 AI 盯盘项目其行情数据层独立在 packages/marketdata 包中。今天拆一个容易被忽略、却决定三市场统一成败的小文件——Symbol值对象它如何用一个不可变数据类替掉散落在各数据源里的腾讯前缀、东财 secid、yfinance 后缀等转换逻辑。为什么需要归一化同一只股票三种写法先看一个现实问题茅台、腾讯、苹果这三只股票在不同数据源里的身份证完全不同股票裸代码腾讯接口东财 secidyfinance贵州茅台600519sh6005191.600519不支持腾讯控股00700hk00700116.007000700.HK苹果AAPLusAAPL105.AAPLAAPL如果你同时接 3~4 家数据源做主备故障转移PanWatch 的 Engine 就是这么做的这些转换逻辑一旦散落在每个 vendor 里就会变成一排排if market HK的复制粘贴——改一处忘一处就是线上 bug。这正是Symbol要消灭的问题。模块开头的注释写得很直白跨市场股票代码值对象一处归一化替代散落各处的_to_market/前缀逻辑。完整定义在 symbol.py。Symbol 值对象一个 frozen dataclass 的解剖整个Symbol只有两个字段靠frozenTrue保证不可变——它是值对象不是实体dataclass(frozenTrue) class Symbol: market: Market # Market.CN / Market.HK / Market.US code: str # 裸代码如 600519不可变带来两个好处可以安全地做字典 key比如按市场分组、可以随手传参、不用担心被下游 vendor 悄悄改掉。自动识别市场三条正则 一个兜底Symbol.parse(600519)不传市场也能猜对靠的是三段规则symbol.py_CN_RE re.compile(r^[036]\d{5}$) # 6 位,0/3/6 开头 _HK_RE re.compile(r^\d{5}$) # 5 位数字 _US_RE re.compile(r^[A-Z.]{1,6}$) # 1-6 位字母(含指数 .DJI)600519→ 6 位、6开头 →A股00700→ 5 位数字 →港股AAPL→ 纯字母 →美股兜底6 位数字当 A股其余当美股当然猜测总有撞车的时候比如某些美股代码恰好是 6 位数字。所以parse支持显式传参Symbol.parse(00700, HK)显式市场优先级永远高于猜测。三个转换方法把方言翻译给各家数据源Symbol的三个转换方法就是给三家数据源说方言def to_tencent(self) - str: if self.market Market.HK: return fhk{self.code} if self.market Market.US: return fus{self.code} return _cn_exchange(self.code) self.code # sh/sz/bj 代码方法输入600519输入00700(HK)输入AAPLto_tencent()sh600519hk00700usAAPLto_eastmoney_secid()1.600519116.00700105.AAPLto_yfinance()不支持(被拦截)0700.HKAAPL注意港股在 yfinance 里的零填充细节00700→0700.HK。这类各家接口文档里不会主动提醒你的坑收敛在一个文件里最容易维护。A股的交易所前缀还有一套独立规则symbol.py920/83/87/88开头 → 北交所bj5/6开头或900→ 上交所sh其余 → 深交所sz。这套规则与宿主的 cn_symbol.py 保持一致避免两处漂移。谁在消费 Symbolvendor 层的单一入口Symbol不是摆设它是所有 vendor 的入参类型。以腾讯行情源为例tencent.pydef fetch(self, symbols: list[Symbol], config: dict) - list[Quote]: ... market symbols[0].market.value codes [s.to_tencent() for s in symbols]vendor 拿到的已经是解析好的值对象它只负责调to_tencent()翻译 → 发请求 → 解析成标准类型Quote。完全不需要关心代码长什么样。同样的模式贯穿各数据源东财资金流sym.to_eastmoney_secid()capital_flow.py东财报价/基本面sym.to_eastmoney_secid()eastmoney.py、fundamentals.pyYahoo K线sym.to_yfinance()kline.py跨市场自动分组quotes 的魔法来自这里marketdata 包最优雅的一个用法在 client.py 的quotes()md.quotes([600519, 00700, AAPL]) # 三个市场的代码混在一起传内部先Symbol.parse逐个识别市场再按市场分组每组各走一次 Engine 主备链groups: dict[str, list[Symbol]] {} for raw in symbols: sym raw if isinstance(raw, Symbol) else Symbol.parse(raw, market) groups.setdefault(sym.market.value, []).append(sym)调用方一行代码横跨三个市场识别、分组、路由全部自动完成。这套行为的回归保障在 test_symbol.py 里覆盖自动识别、显式市场、北交所前缀等场景assert Symbol.parse(00700).market Market.HK assert Symbol.parse(920001).to_tencent() bj920001 assert Symbol.parse(00700, HK).to_yfinance() 0700.HK值对象设计模式小文件里的大工程回头看Symbol不到 80 行代码却体现了几个经典的值对象实践单一事实来源市场识别规则只写一遍三个转换方法只写一遍全项目不再有第二份if market HK不可变 纯函数frozen dataclass保证转换方法幂等、可安全共享领域语言Symbol.parse(600519).to_eastmoney_secid()读起来就是自然语言新人五分钟能读懂整个文件可测试性不需要任何网络纯字符串断言就能锁定所有边界情况。小结packages/marketdata 包整体是可插拔数据源 主备故障转移的架构而Symbol是其中成本最低、收益最高的一块设计用一个不可变值对象把同一只股票在三家接口里的三种写法收敛到一处。如果你想给 PanWatch 加新数据源建议第一步就是读 symbol.py——它 20 分钟就能读完却能帮你避开所有市场前缀的坑。【免费下载链接】PanWatchPanWatch — AI stock monitoring for A-shares, HK US markets, powered by TradingAgents. Portfolio insights, real-time alerts automated reports.盯盘侠覆盖 A股/港股/美股的 AI 盯盘、持仓分析、实时提醒与自动报告。项目地址: https://gitcode.com/GitHub_Trending/pa/PanWatch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考