API 概览

本页帮助你快速定位 Stock SDK 的功能模块和具体接口。

SDK 初始化

typescript

import { StockSDK } from 'stock-sdk';

const sdk = new StockSDK(options?);

配置参数

参数	类型	默认值	说明
`baseUrl`	`string`	`'https://qt.gtimg.cn'`	腾讯行情请求地址（可替换为代理）
`timeout`	`number`	`30000`	请求超时时间（毫秒）
`retry`	`RetryOptions`	见下表	重试配置
`headers`	`Record<string, string>`	-	自定义请求头
`userAgent`	`string`	-	自定义 User-Agent（浏览器环境可能会被忽略）
`rateLimit`	`RateLimiterOptions`	-	限流配置（防止请求过快被频控）
`rotateUserAgent`	`boolean`	`false`	是否启用 UA 轮换（仅 Node.js 有效）
`circuitBreaker`	`CircuitBreakerOptions`	-	熔断器配置（连续失败时暂停请求）
`providerPolicies`	`Partial<Record<ProviderName, ProviderRequestPolicy>>`	-	为不同数据源覆盖超时、重试、限流、熔断和请求头策略

重试配置 (RetryOptions)

参数	类型	默认值	说明
`maxRetries`	`number`	`3`	最大重试次数
`baseDelay`	`number`	`1000`	初始退避延迟（毫秒）
`maxDelay`	`number`	`30000`	最大退避延迟（毫秒）
`backoffMultiplier`	`number`	`2`	退避系数
`retryableStatusCodes`	`number[]`	`[408, 429, 500, 502, 503, 504]`	可重试的 HTTP 状态码
`retryOnNetworkError`	`boolean`	`true`	网络错误时是否重试
`retryOnTimeout`	`boolean`	`true`	超时时是否重试
`onRetry`	`function`	-	重试回调 `(attempt, error, delay) => void`

限流配置 (RateLimiterOptions)

参数	类型	默认值	说明
`requestsPerSecond`	`number`	`5`	每秒最大请求数
`maxBurst`	`number`	`= requestsPerSecond`	令牌桶容量（允许的突发请求数）

限流建议

建议配置 requestsPerSecond: 3~5，避免触发东方财富的频率限制。

Provider 策略覆盖 (ProviderRequestPolicy)

全局 timeout / retry / rateLimit / circuitBreaker 仍然是默认策略。
providerPolicies 只会在指定 provider 上覆盖这些默认值，不会影响旧代码的初始化方式。

typescript

interface ProviderRequestPolicy {
  timeout?: number;
  retry?: RetryOptions;
  headers?: Record<string, string>;
  userAgent?: string;
  rateLimit?: RateLimiterOptions;
  rotateUserAgent?: boolean;
  circuitBreaker?: CircuitBreakerOptions;
}

已内置的 provider 名称：

tencent
eastmoney
sina
linkdiary
unknown

熔断器配置 (CircuitBreakerOptions)

默认关闭

熔断器 默认关闭，需要显式配置才会启用。建议在生产环境中开启，防止连续失败导致雪崩效应。

参数	类型	默认值	说明
`failureThreshold`	`number`	`5`	连续失败多少次后触发熔断
`resetTimeout`	`number`	`30000`	熔断持续时间（毫秒），之后进入半开状态
`halfOpenRequests`	`number`	`1`	半开状态允许的探测请求数
`onStateChange`	`function`	-	状态变化回调 `(from, to) => void`

熔断器状态说明：

CLOSED：正常状态，允许所有请求
OPEN：熔断状态，拒绝所有请求，抛出 CircuitBreakerError
HALF_OPEN：半开状态，允许少量请求探测服务是否恢复

完整配置示例

typescript

const sdk = new StockSDK({
  timeout: 10000,
  headers: {
    'X-Request-Source': 'my-app',
  },
  userAgent: 'my-stock-app/1.0',
  
  // 重试配置
  retry: {
    maxRetries: 5,
    baseDelay: 500,
    onRetry: (attempt, error, delay) => {
      console.log(`第 ${attempt} 次重试，等待 ${delay}ms`);
    }
  },
  
  // 限流配置（推荐开启）
  rateLimit: {
    requestsPerSecond: 5,
    maxBurst: 10,
  },
  
  // UA 轮换（仅 Node.js 有效）
  rotateUserAgent: true,
  
  // 熔断器配置（可选，建议生产环境开启）
  circuitBreaker: {
    failureThreshold: 5,
    resetTimeout: 30000,
    onStateChange: (from, to) => {
      console.log(`熔断器状态: ${from} -> ${to}`);
    }
  },

  // 按 provider 覆盖策略
  providerPolicies: {
    eastmoney: {
      timeout: 12000,
      retry: {
        maxRetries: 5,
        baseDelay: 800,
      },
      rateLimit: {
        requestsPerSecond: 3,
        maxBurst: 3,
      },
      circuitBreaker: {
        failureThreshold: 3,
        resetTimeout: 30000,
      }
    }
  }
});

详细说明请参考错误处理与重试。

实时行情

K 线数据

技术指标

行业板块

行业板块

概念板块

概念板块

批量与扩展

代码列表
搜索
批量查询
扩展数据（资金流向、交易日历等）
分红派送

资金流向（深度）

盘口与龙虎榜

其他数据

大宗交易 / 融资融券

API 概览 ​

SDK 初始化 ​

配置参数 ​

重试配置 (RetryOptions) ​

限流配置 (RateLimiterOptions) ​

Provider 策略覆盖 (ProviderRequestPolicy) ​

熔断器配置 (CircuitBreakerOptions) ​

完整配置示例 ​

实时行情 ​

K 线数据 ​

技术指标 ​

行业板块 ​

概念板块 ​

批量与扩展 ​

资金流向（深度） ​

盘口与龙虎榜 ​

其他数据 ​

API 概览

SDK 初始化

配置参数

重试配置 (RetryOptions)

限流配置 (RateLimiterOptions)

Provider 策略覆盖 (ProviderRequestPolicy)

熔断器配置 (CircuitBreakerOptions)

完整配置示例

实时行情

K 线数据

技术指标

行业板块

概念板块

批量与扩展

资金流向（深度）

盘口与龙虎榜

其他数据