stock-sdk 这个库，从最早那版一路发到 v1.10.1，前前后后一共 18 个版本。要我用一句话总结这 18 个版本到底在忙活什么，那就是：一个劲儿地往里塞数据接口。A 股行情、港股、美股、基金、期货、期权、龙虎榜、北向资金、大宗交易……来一个新需求，我就在门面类上再钉一个 getXxx() 上去。
三层架构——provider 负责取数、service 负责编排、门面只做薄薄一层委托——这套骨架倒是一直立得住，没塌过，这点我心里还是有点得意的。可问题是，当我敲到第 105 个 getXxx() 的时候，连我自己写代码都得开编辑器的搜索框去捞方法名了。手一打 sdk.get，autocomplete 哗啦弹出一百多个候选，从 getAllAShareQuotes 能一路滚到 getZTPool。就那一下我突然就清醒了：这毛病不是再补几个接口能糊弄过去的，得刨地基。
v2 干的就是这件「刨地基」的事。它压根不是什么 v1.11 的小步迭代，而是整个架构层面的一次推倒重写。前提我先划清楚：这一版不接任何新数据源，也不碰实时订阅；在这个边界之内，把符号模型、数据契约、API 表面、请求层、错误体系——全部从头捋了一遍。下面我挑几个自己印象最深的点，跟你慢慢聊。
v1 那个门面类 sdk.ts，足足 1052 行，翻开来满屏都是这种货色：
sdk.getFullQuotes(codes)
sdk.getETFOptionDailyKline('10004336')
sdk.getIndividualFundFlow(...)
sdk.getDragonTigerInstitution(...)
// ……就这么一路排到第 105 个
难找还只是表面。你 import { StockSDK } 一进来，构造函数里咔咔 new 出十几个 service，哪怕你就想拿个行情，整坨东西也全被拽进来了，tree-shaking 在这种结构面前完全使不上劲。
到了 v2，这些全归拢进命名空间了：
sdk.quotes.cn(['sh600519']) // 原 getFullQuotes
sdk.kline.withIndicators(...) // 原 getKlineWithIndicators
sdk.options.etf.dailyKline('10004336') // 原 getETFOptionDailyKline
sdk.board.industry.constituents(s) // 原 getIndustryConstituents
按业务领域归好类之后，autocomplete 的体验一下就顺了——先 sdk. 挑领域，再 . 挑具体方法，两步走，跟脑子里想东西的路径基本对得上。门面类也从 1052 行缩到了 349 行，留下来的内容八九不离十就是把 service 方法挂到各自命名空间下的那层薄委托。
这儿有个我故意写得「啰嗦」的地方，想专门说说。命名空间是懒构建、构建完缓存住的，为的是保证 sdk.quotes === sdk.quotes 这种引用始终稳。我一开始图省事，顺手写成了 this._ns[key] ??= build()，结果踩了个大坑：tsup 那条 cjs + splitting + minify 的流水线，会把这个写法跟它注入的 helper 给熔在一起，搞出个坏掉的标识符 return_nullishCoalesce；后果就是 require 进来的产物，每个命名空间 getter 头一次访问就直接 ReferenceError 给你看。最让人窝火的是，单测只跑 src 的话这玩意儿根本暴露不出来——是后来我补了一套「对构建产物的冒烟测试」才把它揪出来的。所以你现在看到代码里那段笨笨的 if (cached === undefined)，真不是我不会写简写，纯粹是被坑怕了。
上一节那个 v1 的痛点其实还有后半段：import { StockSDK } 一句话就把十几个 service 全 new 出来，你明明只想算个 MACD，整个取数层、所有 provider 全给你打进 bundle 里了。这事儿放 Node 端无所谓，可一旦搬到浏览器，那就是实打实白白胖出来的体积。
v2 的做法是，凡是能独立出来的部分，统统切成 subpath，纯算的东西可以单拎：
import { calcMACD } from 'stock-sdk/indicators'; // 不再从主包拉
import { calcSignals } from 'stock-sdk/signals';
import { normalizeSymbol } from 'stock-sdk/symbols';
一共开了 indicators / symbols / signals / screener / cache / errors / mcp 这么几条子路径。它们有个共同的脾性——纯逻辑、不碰网络：指标算法、信号判定、选股回测、符号解析，这些东西本来就用不着取数层撑腰，完全能拎出来单用。比方说我做一个纯前端的指标计算页，只 import { calcMACD } from 'stock-sdk/indicators'，那请求层、provider、MCP 那一堆代码，一个字节都不会跟着溜进来。
不过话说回来，「路拆开了」跟「树真能摇掉」中间还差着好几步，得几样东西一起兜底，才不至于落得个「subpath 都分好了，结果还是全量打包」的尴尬：
"sideEffects": false：得在 package.json 里把「我没副作用」这事儿明明白白声明出来，bundler（webpack / Rollup / esbuild / Vite 都算）才肯放胆把你没 import 的那些导出整段铲掉。这一行是 tree-shaking 能不能真正生效的命门——多少库就是漏了它，白白把摇树能力给废了。dependencies 那一栏是空的。符号解析、指标、信号、回测、缓存，全是我自己手撸的纯逻辑，既没 lodash 也没 dayjs，一个传递依赖都没挂。所以你 import 进来的那点体积里，没有哪怕一克是「别人家的库」——装个 stock-sdk，不会顺手把半个 node_modules 也给你拖进项目。最后落到体感上就是：库整体能耐其实不小（A 股 / 港股 / 美股 / 基金 / 期货 / 期权 + 指标 + 信号 + 选股回测 + CLI + MCP 都在），可你只为「真正动用到的那块」掏钱。光用指标的人，bundle 里就不该冒出行情请求的代码；只在 Node 里取数的人，也犯不着把浏览器那一套扛在身上。这种「家底很厚、但按需结账」的舒服劲儿，v1 那个单入口全家桶是怎么都给不了的。
stock-sdk 主包本身就揣着命令行，装完即用（package.json 里的 bin 指向 dist/cli.js），一行代码都不用写，直接在终端就能取数：
npx stock-sdk quote 600519 000858 00700 # 一条命令混查 A 股 + 港股，自动识别市场
stock-sdk kline 600519 --period weekly --adjust hfq --limit 30
stock-sdk indicators 600519 --ma 5,10,20 --macd --kdj
它说白了就是一层薄壳：把 argv 解析掉 → new StockSDK() → 调命名空间方法 → 把结果格式化吐出来。也正因如此，库能干的活它一样都不少，数据口径更是逐字节对得上。入口我设计成了两层：
quote / kline / indicators / search / codes 这几个最常摸的操作，压成单个 token，顺带还塞了点 CLI 才有的小贴心（自动识别市场、按代码分组并发、--limit 截断）。sdk.board.industry.list() 对上的就是 stock-sdk board industry list，严丝合缝一一对应，不用再额外记什么新东西。全局选项也都是终端老炮儿熟悉的那套：--format json/table/csv、--pretty、--timeout、--quiet。有一点值得单拎出来讲——为了守住「运行时零依赖」这条线，argv parser 是我手写的一个极小实现，commander 没引，yargs 也没引。
MCP（Model Context Protocol）这一块是冲着 AI 工具去的。起 server 就一条命令：
stock-sdk mcp
服务起来之后，它走 stdio 跟 Cursor / Claude Desktop / Codex / Gemini 这些客户端对话，一个网络端口都不开；模型这边就能直接调用实时行情、K 线、搜索这类只读能力了。
同样是为了零依赖这条铁律，官方那个 @modelcontextprotocol/sdk 我没引，而是自己把 MCP 协议的最小子集手写了出来——本质上就是一套跑在「换行分隔的 stdin/stdout」之上的 JSON-RPC 2.0。范围我卡得死死的，只覆盖行情这个场景里真正会用到的那点东西：transport 只做 stdio，能力只做 tools，方法就处理 initialize / tools/list / tools/call 这么几个；至于 HTTP/SSE、OAuth、sampling、resources/prompts，统统不碰，真等到要用的那天再说。MCP 单独走 stock-sdk/mcp 这个入口，你 import { StockSDK } 的时候，它一个字节都进不了你的 bundle。
其实我最得意的，倒不是 CLI 也不是 MCP 本身，而是它们根本不是我另外手写的第二套、第三套映射。CLI 那些命令、MCP 那些工具，连同 SDK 的方法契约，全都从同一份 src/spec/methods.ts 里派生出来——枚举、默认值、参数形态，大家共用同一个事实源。这么一来，「文档里说支持这参数、CLI 却不认账」「MCP 工具的 schema 跟 SDK 真实签名对不上号」这种经典的漂移惨案，就从根上不会发生。再往后，连文档站那个 Playground 也接上了这份 spec——等于一份定义同时把 SDK、CLI、MCP、Playground 四张嘴都喂了，改一处，四处跟着变。
v1 处理错误的逻辑是「上游抛啥我原样透传啥」——所以你接到手的，可能是个光秃秃的 TypeError，也可能是 RangeError、HttpError，赶上超时那会儿，甚至给你扔个 DOMException 过来：
// v1：判个超时居然得写成这样
catch (e) {
if (e instanceof DOMException && e.name === 'AbortError') { /* 超时 */ }
}
v2 对外只认一种错，只抛 SdkError，而且全都带着统一的 code：
import { SdkError } from 'stock-sdk/errors';
try {
await sdk.quotes.cnSimple(['sh000001']);
} catch (e) {
if (e instanceof SdkError) {
switch (e.code) {
case 'TIMEOUT': break; // 真超时
case 'ABORTED': break; // 外部 signal 主动取消，跟超时区分开
case 'HTTP_ERROR': break; // 非 2xx
}
}
}
把 ABORTED（你自己主动取消的）和 TIMEOUT（是真的等到超时了）拆成两码事，是我被坑过之后做梦都想要的一个区分——这俩在 v1 里全糊成了同一个 AbortError，你根本没法判断到底是用户点了取消、还是网络是真的挂了。请求层这回也顺手做成了可组合的：自定义 fetch 能注入，外部 AbortSignal 能接，再配上限流、重试、熔断、host fallback 这一整套请求治理。
v1 大概攒了 85 个返回类型，里头藏着好几类设计，我现在回头看都有点替自己臊得慌：
raw: string[]——直接把上游返回的原始字段数组拍在数据对象上，当个「逃生舱口」用。实现细节就这么大喇喇地漏给了用户。timestamp: NaN 来表示「这时间没解析出来」。于是判空你得写成 Number.isNaN(q.timestamp)，头一回用的人没有不栽进去的。tz，跨市场的数据一掺和，时区就开始打架。amount 一会儿是万一会儿是元，volume 一会儿是手一会儿是股，FullQuote 里头甚至并排站着 volume 和 volume2 俩重复字段；命名还满地漂，marketCap 和 totalMarketCap 各活各的，mainNet 跟 mainNetInflow 也是俩都在。v2 在数据契约上动了三刀：
第一刀，raw 全砍。想要原始字段？去 provider 层的 getXxxRaw() 调试函数里拿，别再往正经数据对象里掺了。
第二刀，NaN 换成 null，判空也跟着从 Number.isNaN(...) 变成干净利落的 === null：
// v1
if (Number.isNaN(q.timestamp)) { /* 无效 */ }
// v2
if (q.timestamp === null) { /* 无效 */ }
第三刀，行情类型从「一个个各过各的独立接口」收拢成一个靠 assetType 来判别的可辨识联合 Quote，配 switch 收窄：
import type { Quote } from 'stock-sdk';
function render(q: Quote) {
switch (q.assetType) {
case 'stock':
console.log(q.price, q.changePercent); // 这里被收窄成股票 quote
break;
case 'fund':
console.log(q.nav, q.accNav); // 收窄成基金 quote
break;
}
}
不过这儿得跟你交个底，有个点我没做完：单位统一（手→股 ×100、万→元 ×10000 这种换算）这一版我先搁着没落地。倒不是偷懒——正确的换算倍率，得拿真实数据一源一源、一个字段一个字段去比对才能定死，光靠 mock 单测自己证自己，根本验不出来到底对不对，瞎改的风险太大。所以契约里 volume/amount 那几行单位注释，写的是「目标口径」，可实际跑出来的值，眼下还是各家源的原始口径。这事儿我留到能跑真实数据集成测试那天再统一校准。丑话我先撂这儿，免得真有人照着注释口径去做回测，然后对着对不上的数字干瞪眼。
string 走遍全场：normalizeSymbolv1 里最让我膈应的一笔隐性债，是符号格式各写各的、谁也不管谁。同样一只贵州茅台，搁不同方法里你得写成不同的模样：
sh600519，简版行情还得在前头再加个 s_；1.600519；00700，有时候又得 hk00700；105.AAPL。而把「用户随手敲的代码」翻译成「各家接口各自要的格式」这套逻辑，稀稀拉拉散在 15 处以上，连个统一入口都没有。每接一个新数据源，就得在某个犄角旮旯里把那套前缀判断再抄一遍。
v2 把这摊子收成了一个 normalizeSymbol()：对用户这一头，string 就是一等公民——你写 '600519' 也好、'sh600519' 也好、'00700' 也罢，它统统认；到了内部，再交给各 provider 自己的 adapter，把归一化后的结果翻译成它各自要的格式。要是你只想要个纯解析能力，还能单独 import { normalizeSymbol } from 'stock-sdk/symbols'，一个请求都不发。
顺带着，我把一堆陈年的歧义也一并理顺了：北向、港美股、北交所、期货品种这些最容易撞车的家伙，现在都有了明确的消歧规则——打个比方，你给的市场提示要是跟代码本身打架，它会当场抛错给你看，而不是像 v1 那样，默默给你取来错市场的数据，再撂下你一个人 debug 老半天。
v2 是不带兼容层的。没有 compat 入口，也没给 v1 那些旧方法留别名——sdk.getFullQuotes() 就这么直接没了，你只能改成 sdk.quotes.cn()。
这个决定我是真纠结过的。留一层 alias，对老用户显然要厚道得多。可 v2 动的是符号、是契约、是错误、是 API 表面——全都动了；要是每一处都顺手留条兼容路径，那不就等于把我一心想干掉的那锅粥又原封不动地重新供起来了么？地基重构的意义也就荡然无存了。所以最后我还是选了硬切，靠一份写得足够细的迁移指南来接住老用户——里头是一张完整的 sdk.getXxx() → sdk.<ns>.<method>() 映射表。代价当然有，老代码升级得动手改，可改完是真清爽。
与之对应，npm 上的 latest 现在指到 v2 了；老用户要是想把版本钉死在 v1，npm i stock-sdk@legacy 照样能装到 1.10.1，v1 的文档我也归档到了一个独立子域上，不至于让你断了粮。
v2 就这么从一个「方法多到得靠搜索框」的平铺式 SDK，长成了如今这副模样：命名空间清清楚楚、契约统一、错误能辨识、按需可裁剪，还顺带能接 CLI 和 AI。落到代码上，src/ 改了 92 个文件、净增 5000 多行；门面类倒是反着来，瘦掉了整整三分之二。
你要是手头还在用 v1，迁移指南我尽量写细了，照着改就行；你要是个新来的，那更省事，直接从 sdk.quotes.cn() 起手就成。
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。