一个前端股票行情 SDK 的开源进化：从周刊收录到 v1.10.0

从一条 GitHub issue 开始

最早让我意识到 stock-sdk 可能真的能帮到一些人的，是 GitHub 上的一条 issue。

有用户建议我把项目投稿到「阮一峰的科技爱好者周刊」。当时我并没有抱太大期待，毕竟它只是一个刚开源不久的小工具，目标也很朴素：让前端开发者不必绕到 Python 生态里，才能拿到股票行情数据。

没想到几周后，我真的在阮一峰的科技爱好者周刊 397 期里看到了它。

那种感觉和 GitHub star 增长不太一样。star 是一个数字，而被周刊收录更像是一种确认：这个工具确实解决了某些人的真实问题，也被更多有类似需求的开发者看见了。

之后项目也开始进入更快的迭代节奏：

版本已经推进到 v1.10.0
GitHub 获得了 940+ stars
累计处理了 10+ 个 issues
从板块、基金、搜索类型区分，到请求限流和并发安全，很多能力都来自社区反馈

所以这篇文章想重新系统介绍一下：现在的 stock-sdk 到底能做什么，适合哪些人用，以及它为什么对前端开发者比较友好。

如果你是前端工程师、独立开发者、行情看板作者、量化爱好者，或者正在尝试用 AI 工具搭一个金融数据小应用，这个 SDK 可能能帮你省掉不少重复工作。

为什么要做 stock-sdk？

前端想获取股票行情数据，过去经常会遇到几个很典型的问题。

一方面，成熟的数据工具大多集中在 Python 生态，比如 akshare、tushare、efinance 等。它们能力很强，但天然不是为浏览器或前端工程准备的。

另一方面，如果只是想做一个行情看板、个股监控 demo、基金展示页，专门再维护一个 Node 或 Python 后端，成本又显得有点重。

更麻烦的是，不同财经数据源返回的数据格式并不统一：有的接口返回 ~ 分隔字符串，有的需要处理 GBK 编码，有的还套着 jsonp。真正写起来，很多时间都花在了解析和兼容上。

stock-sdk 想解决的就是这个问题：

让前端开发者可以直接用 JavaScript / TypeScript 获取常用金融行情数据。

它的几个核心特点是：

零依赖
支持浏览器和 Node.js 18+
内置完整 TypeScript 类型
安装后即可调用
对常见财经接口做了统一封装

一个最简单的调用示例：

ts 复制代码

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

这段代码既可以跑在现代 Node 环境里，也可以直接跑在浏览器里。

当前能力概览

经过多个版本迭代后，stock-sdk 已经不只是一个简单的股票报价工具，而是逐渐扩展成了一个面向前端的行情数据工具箱。

下面按数据类型拆开介绍。

1. 覆盖 A 股、港股、美股和基金的实时行情

目前 SDK 已经支持多个市场的实时行情获取：

方法	主要用途
`getFullQuotes` / `getSimpleQuotes`	获取 A 股、指数的完整或简要行情
`getHKQuotes`	获取港股行情
`getUSQuotes`	获取美股行情
`getFundQuotes`	获取公募基金行情

如果需要一次性拉取全市场 A 股数据，也可以直接使用内置的批量接口：

ts 复制代码

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

它会自动按批次并发请求，适合做市场总览、行情看板、涨跌分布统计等场景。

2. 历史 K 线与盘中分时

除了实时行情，K 线和分时数据也是金融应用里最常用的基础数据。

stock-sdk 目前支持：

A 股、港股、美股的日线 / 周线 / 月线
1 / 5 / 15 / 30 / 60 分钟级别 K 线
当日分时走势

对应方法包括：

getHistoryKline
getHKHistoryKline
getUSHistoryKline
getMinuteKline
getTodayTimeline

从 v1.9.1 开始，港股和美股 K 线类型被拆分为独立的 HKHistoryKline 与 USHistoryKline。这样做的好处是，返回结果里可以带上更明确的货币和时区信息，调用方不需要再额外猜测这条数据属于哪个市场、使用什么交易时区。

3. 常见技术指标内置

拿到 K 线之后，很多应用的下一步就是计算技术指标。

为了减少重复实现，SDK 内置了常见指标计算能力，包括：

txt 复制代码

MA / EMA / WMA / MACD / BOLL / KDJ / RSI / WR
BIAS / CCI / ATR / OBV / ROC / DMI / SAR / KC

如果你不想自己先取 K 线、再单独计算指标，可以直接使用：

ts 复制代码

const data = await sdk.getKlineWithIndicators({
  code: 'sh600519',
  period: 'day',
  indicators: ['MA(5)', 'MA(20)', 'MACD', 'BOLL'],
});

这个方法会一次返回 K 线数据和指定指标结果，比较适合做图表、策略 demo 或 AI 分析输入。

4. 行业板块与概念板块

对于 A 股应用来说，只看个股往往不够，板块数据也很重要。

SDK 对行业板块提供了比较完整的一组方法：

getIndustryList
getIndustrySpot
getIndustryConstituents
getIndustryKline
getIndustryMinuteKline

概念板块也提供了对应的 getConcept* 系列方法。

这意味着你可以比较方便地拿到板块列表、板块行情、成分股、K 线和分时数据。对于做板块轮动、热点追踪、市场情绪分析的应用来说，这一层封装能节省不少接口适配工作。

5. 期货和期权数据

除了股票和基金，stock-sdk 也覆盖了一部分衍生品数据。

期货方面包括：

国内期货 K 线
全球期货实时行情
全球期货 K 线
期货库存数据
COMEX 黄金、白银库存

期权方面包括：

中金所股指期权 T 型报价
ETF 期权当日分钟数据
ETF 期权历史日 K
ETF 期权 5 日分钟数据
商品期权报价和 K 线
期权龙虎榜

这些能力相对小众，但对于做衍生品研究、策略验证或数据探索的开发者来说，会很实用。

6. 资金流向与北向资金

资金面数据是很多 A 股用户非常关注的一类数据。

SDK 目前支持个股、大盘、行业和北向资金相关接口，例如：

getIndividualFundFlow：个股资金流历史
getMarketFundFlow：大盘资金流历史
getFundFlowRank：个股资金流排名
getSectorFundFlowRank：板块资金流排名
getNorthboundMinute：北向资金分时
getNorthboundHoldingRank：北向持股排行
getNorthboundHistory：北向资金历史
getNorthboundIndividual：个股北向持仓

这些数据可以用在市场复盘、资金流监控、个股热度判断等场景里。

7. 龙虎榜、大宗交易、融资融券

A 股市场里还有一些非常本土化的数据，比如龙虎榜、大宗交易和融资融券。

stock-sdk 也对这些数据做了封装：

龙虎榜详情
个股龙虎榜统计
机构买卖数据
营业部排行
席位明细
大宗交易市场总览
大宗交易明细
个股每日大宗交易统计
融资融券账户统计
融资融券标的明细

如果你想做游资跟踪、机构动向分析或杠杆资金观察，这部分接口会比较有用。

8. 涨停板池与盘口异动

短线交易相关的数据也有覆盖。

getZTPool 支持获取多类股池，包括：

涨停
昨日涨停
强势股
次新股
炸板股
跌停股

getStockChanges 则覆盖 22 种盘口异动，比如火箭发射、大笔买入、封涨停等。

另外，getBoardChanges 可以获取当日板块异动详情。

这类数据适合用来做实时监控、短线情绪看板或热点扫描。

9. v1.10.0 重点增强：基金数据

v1.10.0 对基金能力做了一次比较大的扩展。

基金相关 issue 是项目被更多人看到之后经常出现的需求之一，所以这一版重点补齐了几类常用数据：

方法	能力说明
`getFundNavHistory`	获取基金历史净值，包括单位净值和累计净值
`getFundEstimate`	获取当日实时估值，包括 T-1 单位净值和盘中估算
`getFundRankHistory`	获取同类排名走势，包括近三月每日排名和百分位
`getFundDividendList`	获取基金或 ETF 分红明细，支持全市场按年份分页

如果你想做基金看板、ETF 展示页、定投辅助工具，这部分能力基本可以直接拿来用。

10. 搜索、交易日历、分红和外链生成

除了核心行情数据，SDK 里还有一些看起来不大但很省心的工具能力。

比如：

search：支持按代码、名称、拼音搜索
搜索结果中区分股票、ETF 等类型
getTradingCalendar：获取 A 股交易日历
isTradingDay()：判断某天是否为交易日
getDividendDetail：获取个股分红派送数据
generateSearchExternalLinks(result)：根据搜索结果生成东方财富、雪球等外部链接

这些能力在实际做产品或 demo 时经常会用到，可以减少不少边角逻辑。

11. 请求治理：重试、限流、熔断和错误码

如果只是写 demo，能请求成功就够了。但如果要在真实应用里使用，接口稳定性就很重要。

stock-sdk 对请求层做了一些治理能力：

ts 复制代码

const sdk = new StockSDK({
  retry: { maxRetries: 2, baseDelay: 500 },
  providerPolicies: {
    eastmoney: {
      timeout: 12000,
      rateLimit: { requestsPerSecond: 3, maxBurst: 3 },
    },
  },
});

try {
  await sdk.getSimpleQuotes(['sh600519']);
} catch (error) {
  if (error instanceof HttpError) {
    console.log(error.status, error.statusText);
  }

  console.log(getSdkErrorCode(error));
}

目前支持：

全局重试配置
退避延迟
按数据源配置 timeout
按数据源配置限流策略
标准化错误码
保留原始错误类型
浏览器环境下的全局 mutex，避免并发请求踩同一数据源

其中并发安全这一块，也来自社区真实反馈：有用户提到使用一段时间后可能触发数据源限制，因此 SDK 在请求治理上做了更保守的处理。

12. 面向 AI 工具的 MCP Server

最近一年，很多开发者开始让 AI 工具参与数据分析、选股辅助和看板生成。

为了让 stock-sdk 可以被 AI 工具直接调用，我也配套发布了 stock-sdk-mcp，它是一个标准 MCP Server，可接入 Cursor、Claude Desktop、Codex CLI、Gemini CLI 等工具。

配置示例：

json 复制代码

{
  "mcpServers": {
    "stock-sdk": {
      "command": "npx",
      "args": ["-y", "stock-sdk-mcp"]
    }
  }
}

接入之后，你可以直接让 AI 调用行情数据，例如：

帮我看一下贵州茅台最近的 MACD 走势。

今天涨停板有哪些？

北向资金最近 5 天加仓最多的 10 只股票是什么？

目前 MCP 侧内置了 4 类专业 AI Skills：

技术分析
智能选股
市场概览
实时监控

这部分会继续扩展，因为 AI + 金融数据确实是一个很适合工具化的方向。

项目现在的一些数据

截至目前，stock-sdk 的几个阶段性数据如下：

940+ GitHub stars
68 forks
最新版本推进到 v1.10.0
已关闭 10+ issues
被阮一峰科技爱好者周刊 issue-397 收录

开源项目当然不能只看数字，但这些反馈确实给了我继续维护的动力。

尤其是看到用户在 issue 里提出具体需求，比如支持基金、补充分红、区分 ETF 类型、处理并发限制等，会明显感觉到：这个项目不是一个人关起门来写的工具，而是在被真实场景不断推动着往前走。

接下来计划做什么

后续我会继续围绕几个方向迭代：

继续补强基金数据，比如盘中估值多源对比、定投回测等
增强 RequestClient 的可观测性，开放 per-provider metrics
扩展 MCP Skills，让 AI 更自然地使用金融数据
根据社区 issue 继续补齐高频需求

如果你正在做前端行情页、金融数据看板、量化 demo，或者只是想用 TypeScript 快速拿到一些常用行情数据，欢迎试试这个项目。

一个前端股票行情 SDK 的开源进化：从周刊收录到 v1.10.0

从一条 GitHub issue 开始

为什么要做 stock-sdk？

当前能力概览

1. 覆盖 A 股、港股、美股和基金的实时行情

2. 历史 K 线与盘中分时

3. 常见技术指标内置

4. 行业板块与概念板块

5. 期货和期权数据

6. 资金流向与北向资金

7. 龙虎榜、大宗交易、融资融券

8. 涨停板池与盘口异动

9. v1.10.0 重点增强：基金数据

10. 搜索、交易日历、分红和外链生成

11. 请求治理：重试、限流、熔断和错误码

12. 面向 AI 工具的 MCP Server

项目现在的一些数据

接下来计划做什么

相关链接