如果你也做过股票行情相关的小工具或 Demo，大概率踩过类似的坑：想在前端搞个行情看板、做 TradingView 或 ECharts 的数据源，或者在 Node 里定时抓取数据验证策略，结果发现生态全在 Python，接口返回格式混乱，再加上编码（GBK）、批量、并发、跨域等现实问题，开发体验极差。
因此开发了 stock-sdk。目标很简单：让前端工程师用最熟悉的 JavaScript / TypeScript，直接在浏览器或 Node.js 里优雅地拿到行情和 K 线数据。
以下将介绍其核心特性与使用场景。
核心特性
stock-sdk 是一个 TypeScript SDK，主要特点如下：
- 零依赖：纯 TS 实现，不靠第三方运行时包
- 双端运行：浏览器 + Node.js 18+ 均可直接使用（同时提供 ESM / CJS）
- 轻量：压缩后体积很小（< 20KB）
- 类型友好：接口类型完整，TS 开发体验流畅
数据能力覆盖了常用的'看盘/做图/做小策略验证'需求：
- 实时行情：A 股/指数、港股、美股、基金
- K 线：日/周/月历史 K 线；分钟 K 线（1/5/15/30/60）；当日分时走势
- 板块：行业板块/概念板块（列表、实时、成分股、K 线、分时）
- 扩展数据：资金流向、盘口大单占比、交易日历
- 批量能力：代码列表、全市场批量行情（带并发控制）
- 技术指标：MA、MACD、BOLL、KDJ、RSI、WR、BIAS、CCI、ATR（支持'只算指标'或'拿到 K 线顺便把指标算好'）
快速上手示例
import { StockSDK } from 'stock-sdk';
const sdk = new StockSDK();
const quotes = await sdk.getSimpleQuotes(['sh000001', 'sz000858', 'sh600519']);
quotes.forEach((q) => {
console.log(`${q.name}: ${q.price} (${q.changePercent}%)`);
});
该 SDK 不强制要求搭建后端。很多时候只需快速跑通行情、查看页面效果或验证交互，无需专门上服务。
常用场景
1. 前端直接构建行情看板
拿行情 + 画图，本质是把数据源稳定地喂给 UI。SDK 已封装了编码、解析、类型、批量等脏活，前端只需关注渲染。
const sdk = new StockSDK({ timeout: 8000 });
2. Node 定时任务：抓全市场行情
全市场（5000+）行情抓取若无批量和并发控制，体验会很难受。
const allQuotes = await sdk.getAllAShareQuotes({
batchSize: 300,
concurrency: 5,
onProgress: (completed, total) => {
console.log(`进度：${completed}/${total}`);
},
});
console.log(`共获取 ${allQuotes.length} 只股票`);
建议根据网络情况调整 batchSize 和 concurrency：并发过高可能触发限制或增加失败率。
技术指标自动补全
计算指标时，若需查看 2024-01-01 之后的数据，但指标计算需要更早的'前置 K 线'来预热，手写容易遗漏导致头段数据不准。
getKlineWithIndicators 会根据所选指标自动计算所需最大前置天数，扩展请求范围，算完后再按指定日期过滤返回。
const data = await sdk.getKlineWithIndicators('sz000858', {
startDate: '20240101',
endDate: '20241231',
indicators: {
ma: { periods: [5, 10, 20, 60] },
macd: true,
boll: true,
kdj: true,
},
});
console.log(data[0].date, data[0].ma?.ma5, data[0].macd?.dif);
此外，它还能自动识别市场（A/HK/US），减少分支逻辑。
工程化原则
- 不用依赖就不用依赖：减少不确定性
- 用原生能力填坑：如 GBK 编码使用
TextDecoder，超时使用AbortController - 批量可控并发：全市场数据需求必备
- TS 体验优先：IDE 中提供清晰字段提示而非
any
浏览器集成
可直接通过 CDN 引入静态页 Demo：
<script type="module">
import { StockSDK } from 'https://unpkg.com/stock-sdk/dist/index.js';
const sdk = new StockSDK();
const quotes = await sdk.getFullQuotes(['sz000858', 'sh600519']);
console.log(quotes);
</script>
主要 API 接口
- 行情：
getSimpleQuotes/getFullQuotes/getHKQuotes/getUSQuotes/getFundQuotes - K 线：
getHistoryKline/getMinuteKline/getTodayTimeline/getHKHistoryKline/getUSHistoryKline - 指标：
getKlineWithIndicators+ 独立calcXX函数 - 板块：
getIndustryList/getIndustrySpot/getIndustryConstituents/getConceptList - 批量：
getAShareCodeList/getAllAShareQuotes/getAllHKShareQuotes/getAllUSShareQuotes
详细文档及源码可参考：
贡献与反馈
目标是先把'前端拿行情这件事'做得干净、轻巧、可复用。如果遇到字段缺失、接口变动或想要更多市场/数据源，可在 GitHub 提 Issue 跟进。