stock-sdk：为前端设计的股票行情 SDK

做过金融相关的前端（哪怕只是行情看板 Demo），大概率都会遇到一些工程层面的麻烦：

股票行情工具大多集中在 Python 生态，前端难以直接使用
为了拉数据，不得不自建一层后端中转
接口格式混乱、字段不友好，还要处理 GBK 编码
全市场批量拉取时，并发、限频、容错一堆细节要自己兜

stock-sdk 做的事很朴素：把这些公开数据源的“工程脏活”封装起来，提供一个 零依赖、TypeScript 友好、浏览器与 Node.js 都能用 的行情 SDK，让前端可以像调用普通 API 一样获取行情、K 线和分时数据。

一、stock-sdk 是什么？解决了什么问题

先说结论：stock-sdk 是一个为浏览器与 Node.js 设计的股票行情 SDK，支持 A 股 / 港股 / 美股 / 公募基金的实时行情与常用 K 线数据，并提供全市场批量拉取能力。

它主要针对的是“前端直连数据源”时常见的工程问题：

数据源接口陈旧：字段不友好、格式与分隔符不统一，需要自己拼参数、拆字段。
编码处理分散：不少接口返回 GBK，如果在业务代码里处理，很容易遗漏或写得很乱。
批量与并发控制：5000+ A 股全市场行情，不可能简单 for 循环逐个请求。
类型缺失：没有 TypeScript 类型，前端页面开发基本靠猜字段。

二、为什么它更适合前端使用

从设计之初，stock-sdk 就把“前端体验”作为第一优先级：

零依赖 & 体积小：压缩后 < 10KB。
双端运行：浏览器与 Node.js 18+ 均可运行（Node 18+ 原生 fetch + TextDecoder）。
ESM / CommonJS：适配不同构建与运行环境。
完整 TypeScript 类型：字段提示到位，IDE 体验友好。
覆盖常见需求：实时行情、历史 K 线、分钟 K 线 / 分时、当日分时、资金流向、盘口大单。
全市场批量能力：内置分批、并发控制与进度回调，适合做看板体验。

三、安装与 10 行快速开始

1）安装

npm install stock-sdk
# 或
yarn add stock-sdk
# 或
pnpm add stock-sdk

2）10 行 Demo：获取自选股简要行情

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}%)`);
});

**代码格式建议：**A 股/指数推荐统一使用带交易所前缀的代码（如 sz000858 / sh600519），可以减少解析分支与歧义。

四、核心能力与 API（按使用频率）

1）实时行情：列表页与详情页

getSimpleQuotes(codes)：简要行情，适合列表 / 自选股
getFullQuotes(codes)：全量行情，适合详情页与深度看板

1 2	const list = await sdk.getSimpleQuotes(['sh000001', 'sz000858']); const detail = await sdk.getFullQuotes(['sz000858']);

2）K 线与分时：图表场景

getHistoryKline：历史 K 线（日 / 周 / 月，支持复权）
getMinuteKline：分钟 K 线或分时数据
getTodayTimeline：当日分时走势

1
2
3

const daily = await sdk.getHistoryKline('000001');
const timeline = await sdk.getMinuteKline('sz000858', { period: '5' });
const today = await sdk.getTodayTimeline('sz000001');

3）全市场与批量能力

const allQuotes = await sdk.getAllAShareQuotes({
  batchSize: 300,
  concurrency: 5,
  onProgress: (completed, total) => {
    console.log(`进度: ${completed}/${total}`);
  },
});

全市场拉取如果遇到超时或失败，优先减小 batchSize（100～300），并将 concurrency 控制在 3～7，再配合进度提示，整体体验会更稳定。

五、浏览器里直接使用（无需安装）

如果只是做一个静态 Demo 页面，可以直接从 CDN 引入：

<script type="module">
  import { StockSDK } from 'https://unpkg.com/stock-sdk/dist/index.js';

  const sdk = new StockSDK();
  const quotes = await sdk.getFullQuotes(['sz000858']);
  console.log(quotes[0].name, quotes[0].price);
</script>

六、一些实现上的取舍

1）统一的数据源封装

SDK 内部对多个公开数据源做了统一封装，把参数拼接、字段解析和结构标准化都收敛在一处，让上层调用保持一致。

2）GBK 解码统一处理

财经接口常见 GBK 编码，如果分散在业务代码里处理，很容易遗漏。SDK 使用原生 TextDecoder('gbk') 统一解码，避免额外依赖。

运行环境提示：浏览器需支持 TextDecoder，Node.js 建议使用 18+。

3）分批 + 并发控制

全市场行情拉取的核心在于三点：分批请求、并发池控制，以及可视化进度反馈。这比“一次性拉完”更稳，也更符合前端看板的体验预期。

七、一个落地思路：如何做行情看板

列表 / 自选股：getSimpleQuotes 定时刷新
详情页：getFullQuotes 获取更完整字段
图表：getHistoryKline + getMinuteKline / getTodayTimeline
全市场：getAllAShareQuotes + 进度条 + 本地缓存

一个很实用的小技巧是：代码列表本地缓存，因为代码列表的变化频率远低于行情本身。

let codeListCache: string[] | null = null;

async function getCachedCodeList(sdk: StockSDK) {
  if (!codeListCache) codeListCache = await sdk.getAShareCodeList();
  return codeListCache;
}