快速开始

本指南将通过几个简单的示例帮助你快速上手 Tushare SDK。

获取 Tushare Token

在使用 SDK 之前,你需要先获取 Tushare API Token:

访问 Tushare Pro 官网
注册并登录账号
在个人中心获取 API Token
查看你的积分等级(影响请求频率限制)

创建客户端

使用你的 Token 创建 TushareClient 实例:

1import { TushareClient } from '@hestudy/tushare-sdk';
2
3const client = new TushareClient({
4  token: 'YOUR_TUSHARE_TOKEN'
5});

推荐使用环境变量管理 Token:

1import { TushareClient } from '@hestudy/tushare-sdk';
2
3const client = new TushareClient({
4  token: process.env.TUSHARE_TOKEN!
5});

第一个示例:获取股票列表

让我们从最简单的示例开始 - 获取所有上市股票的列表:

1import { TushareClient } from '@hestudy/tushare-sdk';
2
3async function main() {
4  // 创建客户端
5  const client = new TushareClient({
6    token: 'YOUR_TOKEN'
7  });
8
9  try {
10    // 获取所有上市股票
11    const stocks = await client.getStockBasic({
12      list_status: 'L'
13    });
14
15    console.log(`共有 ${stocks.length} 只上市股票`);
16    console.log('前 5 只股票:');
17
18    stocks.slice(0, 5).forEach(stock => {
19      console.log(`${stock.ts_code} - ${stock.name} (${stock.industry})`);
20    });
21  } catch (error) {
22    console.error('获取股票列表失败:', error);
23  }
24}
25
26main();

输出示例:

共有 5234 只上市股票
前 5 只股票:
000001.SZ - 平安银行 (银行)
000002.SZ - 万科A (房地产)
000004.SZ - 国华网安 (计算机)
000005.SZ - 世纪星源 (环保)
000006.SZ - 深振业A (房地产)

示例 2:获取股票日线数据

获取指定股票的历史日线数据:

1import { TushareClient } from '@hestudy/tushare-sdk';
2
3async function main() {
4  const client = new TushareClient({
5    token: 'YOUR_TOKEN'
6  });
7
8  try {
9    // 获取平安银行 2024 年 1 月的日线数据
10    const dailyData = await client.getDailyQuote({
11      ts_code: '000001.SZ',
12      start_date: '20240101',
13      end_date: '20240131'
14    });
15
16    console.log(`获取到 ${dailyData.length} 条数据`);
17    console.log('前 3 天的行情:');
18
19    dailyData.slice(0, 3).forEach(day => {
20      console.log(`${day.trade_date}: 开${day.open} 高${day.high} 低${day.low} 收${day.close} 涨跌幅${day.pct_chg}%`);
21    });
22  } catch (error) {
23    console.error('获取日线数据失败:', error);
24  }
25}
26
27main();

输出示例:

获取到 20 条数据
前 3 天的行情:
20240131: 开10.52 高10.66 低10.50 收10.64 涨跌幅1.14%
20240130: 开10.58 高10.65 低10.52 收10.52 涨跌幅-0.57%
20240129: 开10.48 高10.60 低10.46 收10.58 涨跌幅0.95%

示例 3:查询交易日历

查询指定日期范围内的交易日:

1import { TushareClient } from '@hestudy/tushare-sdk';
2
3async function main() {
4  const client = new TushareClient({
5    token: 'YOUR_TOKEN'
6  });
7
8  try {
9    // 查询 2024 年 1 月的交易日历
10    const calendar = await client.getTradeCalendar({
11      exchange: 'SSE',
12      start_date: '20240101',
13      end_date: '20240131',
14      is_open: '1'  // 只查询交易日
15    });
16
17    console.log(`2024 年 1 月共有 ${calendar.length} 个交易日:`);
18    calendar.forEach(day => {
19      console.log(day.cal_date);
20    });
21  } catch (error) {
22    console.error('获取交易日历失败:', error);
23  }
24}
25
26main();

示例 4:获取每日指标

获取股票的估值指标(需要至少 2000 积分):

1import { TushareClient } from '@hestudy/tushare-sdk';
2
3async function main() {
4  const client = new TushareClient({
5    token: 'YOUR_TOKEN'
6  });
7
8  try {
9    // 获取平安银行 2024-01-31 的每日指标
10    const basicData = await client.getDailyBasic({
11      ts_code: '000001.SZ',
12      trade_date: '20240131'
13    });
14
15    const data = basicData[0];
16    console.log('每日指标:');
17    console.log(`市盈率 PE: ${data.pe?.toFixed(2)}`);
18    console.log(`市净率 PB: ${data.pb?.toFixed(2)}`);
19    console.log(`市销率 PS: ${data.ps?.toFixed(2)}`);
20    console.log(`换手率: ${data.turnover_rate?.toFixed(2)}%`);
21    console.log(`总市值: ${(data.total_mv! / 10000).toFixed(2)} 亿元`);
22  } catch (error) {
23    console.error('获取每日指标失败:', error);
24  }
25}
26
27main();

完整示例

下面是一个完整的示例,展示如何组合使用多个 API:

1import { TushareClient } from '@hestudy/tushare-sdk';
2
3async function analyzeStock(tsCode: string, tradeDate: string) {
4  const client = new TushareClient({
5    token: process.env.TUSHARE_TOKEN!
6  });
7
8  try {
9    // 1. 获取股票基础信息
10    const stocks = await client.getStockBasic({
11      ts_code: tsCode
12    });
13    const stock = stocks[0];
14    console.log(`\n=== ${stock.name} (${stock.ts_code}) ===`);
15    console.log(`行业: ${stock.industry}`);
16    console.log(`上市日期: ${stock.list_date}`);
17
18    // 2. 获取最近的日线数据
19    const quotes = await client.getDailyQuote({
20      ts_code: tsCode,
21      trade_date: tradeDate
22    });
23    const quote = quotes[0];
24    console.log(`\n${tradeDate} 行情:`);
25    console.log(`收盘价: ${quote.close} 元`);
26    console.log(`涨跌幅: ${quote.pct_chg}%`);
27    console.log(`成交额: ${(quote.amount / 100000).toFixed(2)} 亿元`);
28
29    // 3. 获取每日指标
30    const basics = await client.getDailyBasic({
31      ts_code: tsCode,
32      trade_date: tradeDate
33    });
34    const basic = basics[0];
35    console.log(`\n估值指标:`);
36    console.log(`市盈率: ${basic.pe?.toFixed(2)}`);
37    console.log(`市净率: ${basic.pb?.toFixed(2)}`);
38    console.log(`总市值: ${(basic.total_mv! / 10000).toFixed(2)} 亿元`);
39
40  } catch (error) {
41    console.error('分析失败:', error);
42  }
43}
44
45// 分析平安银行
46analyzeStock('000001.SZ', '20240131');

错误处理

SDK 使用 ApiError 类来表示 API 调用错误。建议使用 try-catch 进行错误处理:

1import { TushareClient, ApiError, ApiErrorType } from '@hestudy/tushare-sdk';
2
3async function main() {
4  const client = new TushareClient({
5    token: 'YOUR_TOKEN'
6  });
7
8  try {
9    const stocks = await client.getStockBasic();
10    console.log(stocks);
11  } catch (error) {
12    if (error instanceof ApiError) {
13      console.error(`错误类型: ${error.type}`);
14      console.error(`错误消息: ${error.message}`);
15      console.error(`HTTP 状态码: ${error.code}`);
16
17      // 处理特定错误类型
18      if (error.type === ApiErrorType.AUTH_ERROR) {
19        console.error('Token 无效,请检查 API Token');
20      } else if (error.type === ApiErrorType.RATE_LIMIT) {
21        console.error(`请求频率超限,建议等待 ${error.retryAfter}ms 后重试`);
22      }
23    } else {
24      console.error('未知错误:', error);
25    }
26  }
27}
28
29main();

更多错误处理信息,请查看错误处理指南。

使用 async/await

所有 SDK 方法都返回 Promise,推荐使用 async/await 语法:

1// ✅ 推荐
2async function fetchData() {
3  const stocks = await client.getStockBasic();
4  return stocks;
5}
6
7// ❌ 不推荐
8function fetchData() {
9  return client.getStockBasic().then(stocks => {
10    return stocks;
11  });
12}

批量请求

如果需要批量获取多个股票的数据,可以使用 Promise.all:

1import { TushareClient } from '@hestudy/tushare-sdk';
2
3async function main() {
4  const client = new TushareClient({
5    token: 'YOUR_TOKEN'
6  });
7
8  const stockCodes = ['000001.SZ', '000002.SZ', '600000.SH'];
9
10  try {
11    // 并行请求多个股票的数据
12    const allData = await Promise.all(
13      stockCodes.map(code =>
14        client.getDailyQuote({
15          ts_code: code,
16          start_date: '20240101',
17          end_date: '20240131'
18        })
19      )
20    );
21
22    allData.forEach((data, index) => {
23      console.log(`${stockCodes[index]}: ${data.length} 条数据`);
24    });
25  } catch (error) {
26    console.error('批量请求失败:', error);
27  }
28}
29
30main();

注意: 批量请求时需要注意 Tushare 的频率限制,建议配置合适的并发控制。

性能优化技巧

1. 启用缓存减少重复请求

对于不常变化的数据(如股票基础信息),启用缓存可以显著提高性能:

1const client = new TushareClient({
2  token: 'YOUR_TOKEN',
3  cache: {
4    enabled: true,
5    ttl: 3600000  // 缓存 1 小时
6  }
7});

2. 合理配置并发限制

根据 Tushare 积分等级配置并发限制,避免触发限流:

1// 2000 积分等级配置
2const client = new TushareClient({
3  token: 'YOUR_TOKEN',
4  concurrency: {
5    maxConcurrent: 5,
6    minInterval: 200  // 5 次/秒
7  }
8});

更多配置选项,请查看配置指南。

3. 使用日期过滤减少数据量

避免一次性获取过多数据:

1// ✅ 推荐 - 指定日期范围
2const data = await client.getDailyQuote({
3  ts_code: '000001.SZ',
4  start_date: '20240101',
5  end_date: '20240131'
6});
7
8// ❌ 不推荐 - 获取所有历史数据
9const data = await client.getDailyQuote({
10  ts_code: '000001.SZ'
11});

4. 批量请求的注意事项

批量请求时,注意控制并发数量:

1// 分批处理大量请求
2async function batchProcess(stockCodes: string[], batchSize = 10) {
3  const results = [];
4
5  for (let i = 0; i < stockCodes.length; i += batchSize) {
6    const batch = stockCodes.slice(i, i + batchSize);
7    const batchResults = await Promise.all(
8      batch.map(code => client.getStockBasic({ ts_code: code }))
9    );
10    results.push(...batchResults);
11  }
12
13  return results;
14}

常见问题

Q: Token 错误怎么办?

A: 如果遇到认证错误,请检查:

Token 是否正确复制(无多余空格)
账号是否已激活
Token 是否已过期

Q: 限流错误怎么办?

A: Tushare Pro 根据积分等级限制请求频率:

200 积分: 1 次/秒
2000 积分: 5 次/秒
5000 积分: 20 次/秒

建议根据积分等级配置并发控制,参考配置指南。

Q: 某些 API 返回空数据?

A: 可能的原因:

部分 API 需要更高的积分等级(如 getDailyBasic 需要 2000 积分)
查询参数不正确(如日期格式应为 YYYYMMDD)
查询的数据不存在(如周末查询日线数据)

Q: 如何判断是否为交易日?

A: 使用交易日历 API:

1const calendar = await client.getTradeCalendar({
2  exchange: 'SSE',
3  start_date: '20240101',
4  end_date: '20240101'
5});
6
7const isOpen = calendar[0]?.is_open === '1';
8console.log(isOpen ? '交易日' : '休市');

下一步

现在你已经掌握了 Tushare SDK 的基本用法,接下来可以:

配置选项 - 了解更多高级配置
错误处理 - 学习错误处理机制
API 文档 - 查看所有可用的 API

快速开始#

获取 Tushare Token#

创建客户端#

第一个示例:获取股票列表#

示例 2:获取股票日线数据#

示例 3:查询交易日历#

示例 4:获取每日指标#

完整示例#

错误处理#

使用 async/await#

批量请求#

性能优化技巧#

1. 启用缓存减少重复请求#

2. 合理配置并发限制#

3. 使用日期过滤减少数据量#

4. 批量请求的注意事项#

常见问题#

Q: Token 错误怎么办?#

Q: 限流错误怎么办?#

Q: 某些 API 返回空数据?#

Q: 如何判断是否为交易日?#

下一步#