简介：tushare这一开源财经数据接口库，其最新源代码包适合金融数据分析师、量化策略研究者以及有进阶需求的开发人员。研读源码可理解网络请求的封装、行情数据的解析、异常情况的处理，以及多线程和异步输入输出在性能优化上的运用。资源囊括四十四个文件，以二十五份脚本为主体，另有七份说明文档，以及配置、测试、许可证等辅助文件，整体压缩包仅二百六十九千字节，结构精炼，便于逐模块研读。目前已经有一千四百九十四人浏览学习。借助这套源码，读者能够掌握针对多种数据库的存储设计、异常值与缺失值的清洗方法、时间序列数据的处理策略，以及常用图表库的调用方式，这些经验能直接迁移到个人量化分析项目中，提升数据开发的稳健性与效率。
1. 从“调接口”到“读源码”：一份 Tushare 最新源代码能给你什么
我第一次用 Tushare 是拿它拉日线数据。当时文档写得很清楚：ts.pro_api(token).daily(...)三行搞定。直到某个凌晨，接口报了一个40002，我才发现文档没讲权限、重试和字段映射，真正回答这些问题的只有源码。这份 Tushare 最新源代码不是 PyPI 上那个安装包，而是把接口层、数据层、兼容层拆开给你看的东西。适合两类人：一类是把 Tushare 当数据源、想搞明白接口边界做量化数据管道的人；另一类是想把 Tushare 客户端改造成内部数据中台、却不想从零造轮子的人。如果你也经历过“文档看着能用，跑起来全是黑匣子”的翻车体验，这份源码值得你花一个晚上读一遍。
2. 项目定位与技术底座：从接口库到数据服务的分层设计
2.1 三种调用形态，对应三层代码
把源码拉下来，先不要急着找daily接口，先看它对外暴露的三种调用方式，因为每种方式对应完全不同的代码路径，读错入口会让你在旧代码里浪费大量时间。
第一种是旧版接口，类似ts.get_hist_data('000001')。它内部走的是http://api.tushare.com，返回直接是DataFrame，字段名短、中文注释少，数据频率和复权处理也默认了一套。新版源码里保留了它，但状态基本是冻结维护，不建议新项目再使用。
第二种是 Tushare Pro 的统一接口，ts.pro_api(token)拿到客户端对象，然后client.daily(ts_code='000001.SZ')。所有 Pro 接口都走同一条query管道，接口名、参数、返回字段全部由后端动态决定，前端不需要为每个接口写单独的数据解析逻辑，这也是源码里最值得读的部分。
第三种是ts.pro_bar，它是在daily基础上做了复权和频率拼接的高层封装，适用于拉取前复权日线数据。pro_bar的源码会调用pro_api的客户端，然后自己处理adj、fq这些参数，最终返回的 DataFrame 比原始daily多了复权因子信息。
从源码结构看，三种调用并不是平级关系：pro_bar依赖pro_api的客户端，旧版接口则是独立的模块。所以读源码的入口应该是pro/client.py，而不是stocks/下的那些数据函数。如果你一上来就翻stocks/reference.py，很容易被旧版接口的实现风格带偏，因为它和 Pro 的请求签名完全不是一个套路。
2.2 目录结构：先说清楚每个包在干什么
一份常见的 Tushare 源码包会按数据域拆分模块，而不是把所有代码堆在一个文件里。我刚打开时的第一反应是“为什么__init__.py里只有那么几行”，等顺着导入链走完，才发现每个数据域都是一个独立包，真正做网络请求的只有pro和util两个目录。大致布局是这样：
tushare/ ├── __init__.py # 用户 from tushare import * 时真正导出什么 ├── pro/ │ ├── __init__.py # pro_api 出口 │ ├── client.py # DataClient 与 ProApi 的核心请求逻辑 │ └── data.py # pro_bar、复权计算等高层封装 ├── util/ │ ├── __init__.py │ ├── dateu.py # 交易日历、日期转换 │ └── upass.py # token 写入与读取 ├── stocks/ │ ├── __init__.py │ └── reference.py # 旧版股票行情、财务数据 ├── fund/ │ ├── __init__.py │ └── reference.py # 基金净值、评级 ├── future/ │ ├── __init__.py │ └── reference.py # 期货合约、结算参数 └── trader/ ├── __init__.py └── reference.py # 交易员数据、业绩评价这里有个关键判断：pro/client.py是整份源码的核心，后面的stocks、fund等目录大多是旧版数据函数，和 Pro 接口没有直接依赖。util/upass.py不显眼，但它负责 token 的持久化，很多权限类问题都能在这里找到原因。__init__.py里的__all__决定了哪些函数能被from tushare import *导入，如果你二次开发时新写了一个模块，却忘了在__init__.py里导出，用户看到的表现就是“装上了但调不到”。
读目录结构时，我一般会刻意跳过大段的财务指标计算函数，先把导入链走一遍，记录哪个包属于 Pro 体系、哪个包属于旧版兼容体系。这份源码的划分比较清晰：pro管新接口，stocks、fund、future管旧接口的数据域函数，trader属于特定数据域，和核心请求无关。这样划分的好处是，当你想给某个数据域加接口时，只需要动对应的 reference 文件，不用碰核心 client。
2.3 依赖与版本：跑起来之前先对齐环境
源码包和安装包的区别在于，安装包已经把依赖声明好了，而源码包需要你自己看setup.py和requirements。Tushare 的底层依赖很轻，核心只有pandas、requests和bs4，lxml是用来解析部分旧版页面数据用的。也就是说，一个纯净的 Python 环境，只要装了这三四个库，源码就能跑起来。
Python 版本方面，新版 Pro 客户端大量使用requests的json参数、os.makedirs(exist_ok=True)，这些在 Python 3.6+ 都支持。实际踩坑点是 pandas 版本：旧代码里有些地方用了pd.DataFrame.from_dict的旧写法，在 pandas 2.0 之后行为有变化，所以跑源码前建议先固定pandas==1.5.3或 2.x 的某个稳定版本，不要在最新版上硬试。
依赖对齐之后，还需要做一件事：确认 token 是怎么传进去的。源码里pro_api(token='')的空字符串默认值很容易让人以为可以不传，但实际上它会去读环境变量TUSHARE_TOKEN，读不到才报错。这个设计让你在部署到服务器时可以直接用环境变量注入 token，也意味着本地调试时很容易出现“代码里明明没填 token 却能用”的错觉，一旦环境变量过期，问题就玄学了。所以我的习惯是，拿到源码先别跑测试，先执行下面这段，确定 token 的读取路径：
import os from tushare.util import upass token = upass.get_token() print(token[:6] + '...' if token else 'token is empty') print('env TUSHARE_TOKEN =', os.environ.get('TUSHARE_TOKEN', ''))upass.get_token()会先查本地 token 文件，再回退到环境变量；这段命令能帮你判断是环境问题还是代码问题。参数说明：get_token()不接受参数，它内部读取的是~/.tushare/token文件；如果你想临时指定 token，直接pro_api(token='你的token')是最明确的路径，优先级也最高。运行时如果看到token is empty，优先查环境变量，而不是反复执行set_token。
3. 核心模块拆解：一次接口调用从 token 校验到 DataFrame 的完整链路
3.1 入口构造：pro_api为什么返回一个ProApi对象
源码里pro_api是一个很薄的工厂函数，它不承担业务逻辑，只负责把 token 和 timeout 组装成对象。这层封装虽然简单，但是后续所有接口调用的入口，值得先看。
# tushare/pro/__init__.py from tushare.pro.client import DataClient, ProApi def pro_api(token='', timeout=30): api = ProApi(token=token, timeout=timeout) return api逻辑说明：DataClient是底层请求类，包含query方法；ProApi继承DataClient，并在初始化时把自己的方法注册表准备好。这样做的价值在于，调用方不需要关心“哪些接口存在”，所有接口都通过同一套 query 管道走，新增接口时只需要在后端注册，客户端不用发版。如果你要加自己的数据源，也可以直接继承DataClient，复用它的query和 DataFrame 转换能力。
参数说明：token是 Tushare Pro 的凭证，默认空字符串会触发环境变量和本地文件的回退查找；timeout是单个 HTTP 请求的超时时间，默认 30 秒。拉长数据时建议调到 60 秒以上，否则交易时段接口响应变慢会频繁抛超时，这个默认值只适合本地调试，不适合生产管道。
3.2 query 方法内部：请求签名与错误处理
query是整份源码里被调用最多的方法，它的处理流程值得逐行看。我读到的核心逻辑大致是这样：
# tushare/pro/client.py class DataClient: def __init__(self, token='', timeout=30): self.token = token self.timeout = timeout self.http_url = 'https://api.tushare.pro' def query(self, api_name, fields='', **kwargs): params = { 'token': self.token, 'api_name': api_name } if kwargs: params['params'] = kwargs if fields: params['fields'] = fields resp = requests.post( self.http_url, json=params, timeout=self.timeout ) data = resp.json() if data.get('code') and data['code'] != 0: raise Exception(f"[{data.get('code')}] {data.get('msg')}") return data.get('data') if data.get('data') else {}逻辑说明：所有参数都打包成一个 dict，通过requests.post的json=params发送，而不是用data=拼接表单，这保证了接口层对参数嵌套的支持。返回体里code代表业务状态码，0是成功，非 0 直接抛异常，异常消息里带code和msg，这样你在日志里看到的40002就是从这行raise来的。注意这里的空返回处理，data.get('data')在服务端返回空结果时是None，所以最后一行把它兜底成空字典，避免下游方法拿到None再报错。
参数说明：api_name是接口名，例如daily、stock_basic；fields是逗号分隔的字段字符串，不传时返回全部字段；kwargs里放的是查询参数，比如ts_code、trade_date。这套设计有个容易被忽略的点：fields不会做本地校验，你写错字段名并不会在客户端报错，而是等到服务端返回结果时缺列，所以要靠文档或stock_basic这类元数据接口确认字段名。另外，params里的键值对会被直接序列化成 JSON，所以日期参数传'20240101'还是'2024-01-01'完全取决于服务端定义，源码不帮你做格式转换，这个坑后面会专门说。
3.3 数据落地：从fields和items到 DataFrame
Tushare 服务端返回的数据体并不是直接给前端用的，它按fields和items两个键展开：
def _to_dataframe(self, data): if not data: return pd.DataFrame() columns = data.get('fields', []) rows = data.get('items', []) if not columns or not rows: return pd.DataFrame() df = pd.DataFrame(rows, columns=columns) return df逻辑说明：第一层判断挡住空返回，第二层判断挡住字段缺失的异常结构。这里有个常见的翻车点：fields的顺序由服务端决定，不保证和你传入的fields参数顺序一致，所以不能靠“我传了什么字段就按什么顺序取列”，而是必须用返回体的columns来建 DataFrame。这个方法本身不长，但它把 Tushare 的数据协议固定了下来，二次开发时接别的数据源，最好也按这个协议适配。
参数说明：_to_dataframe不需要外部传参，它处理的是query方法里已经解析好的data。如果你的二次开发要接入其他数据源，完全可以复用这个方法，只要把外部数据源的结果统一成{'fields': [...], 'items': [[...], ...]}的结构，就能无缝接到现有代码里。这里要留意items的值是二维列表，不做类型推断，所以日期列落到 DataFrame 后是字符串还是日期，取决于后续你自己加的转换，Tushare 源码默认不帮你转。
3.4 旧版兼容层：get_hist_data为什么还能用但不该用
stocks/reference.py里保留了旧版接口的封装，它的路径比 Pro 接口简单得多，直接拼 URL 请求老接口：
# tushare/stocks/reference.py def get_hist_data(code, start=None, end=None): url = 'http://api.tushare.com' params = {'code': code} if start: params['start'] = start if end: params['end'] = end resp = requests.get(url, params=params, timeout=10) obj = resp.json() df = pd.DataFrame(obj.get('data', [])) return df逻辑说明：这个封装的问题在于没有统一的错误码体系，老接口返回的数据结构也和 Pro 不同，所以新代码不应该再走这一层。源码保留它，更多是为了让依赖旧接口的项目还能平滑过渡，而不是推荐你继续用。注意它用的是requests.get，参数直接拼在 URL 上，和 Pro 的post风格完全不同，如果你在同一个项目里混用，很容易把请求参数格式搞混。
参数说明：code是六位股票代码，比如000001；start和end是区间参数，默认返回全部历史。把它和 Pro 的daily对比会发现，Pro 要求传入带交易所后缀的ts_code，并且要显式传start_date和end_date，两者字段风格完全不同。如果你正在从旧版迁移，最省事的办法是在自己的数据层做一层适配，把旧调用改成client.daily(ts_code=code + '.SZ', start_date=..., end_date=...)，而不是继续依赖旧接口。需要提醒的是，旧接口的code不带后缀，默认走深圳，和 Pro 按交易所区分的逻辑有差异，迁移时一定要补后缀。
4. 常见问题与避坑：读源码时最容易翻车的几个点
读源码和用接口是两回事，用接口只要看文档，读源码要面对的是文档没写的分支逻辑。这里我先说一个整体认知：Tushare 的报错分三层。第一层是网络异常，比如 requests 的 ConnectionError，这类问题要看代理、DNS 和防火墙；第二层是 HTTP 状态码异常，比如 500、502，这类问题通常是服务端波动；第三层是业务错误码，也就是返回体里的 code 字段非 0，这类问题要看积分、参数格式和权限。大多数文档没写清楚的坑都集中在第三层，而源码里只把 code 和 msg 原样抛出来，不帮你做归因。读源码时还要注意，client.py 并没有对参数做业务校验，相同的错误在不同接口上表现不同，比如日期格式错误在 daily 上可能返回空表，在 trade_cal 上可能报参数错误，所以排查时要结合接口文档判断。
排查这些问题的通用路径我一般分三步：第一步，用源码自带的 demo 脚本跑通一个最简接口，比如stock_basic，排除环境和认证问题；第二步，在query方法里临时打印请求参数和返回原始 JSON，确认客户端发送的内容；第三步，再用业务代码调用，如果业务代码出错而最小脚本正常，问题就在你自己的封装层。这套顺序能覆盖八成以上的读源码踩坑场景。下面五条是高频坑，每一条都按“现象 → 原因 → 解决”的顺序说。
4.1 token 设置失效：环境变量与全局配置的优先级
现象是执行了ts.set_token('xxx')之后再调用ts.pro_api()，依然报token is empty。我一开始以为是写入失败，反复执行了几次set_token都没用，直到读了util/upass.py才发现，set_token写的是本地文件~/.tushare/token，而pro_api(token='')传入空字符串时，ProApi的初始化逻辑会先读环境变量TUSHARE_TOKEN，环境变量存在时本地文件根本不参与读取。这个优先级设计在服务器部署时很合理，用环境变量注入 token 够方便，但本地开发时容易被历史 export 干扰；如果你用 IDE 调试，还要检查运行环境配置里是否也设置了TUSHARE_TOKEN。解决的办法很简单：调用前unset TUSHARE_TOKEN，或者显式传pro_api(token='新的token')。想验证当前到底读的是哪个 token，直接用第 2 章那段upass.get_token()脚本，看输出的前几位字符就能对上。
4.2 接口权限报 40002：错误码信息不够，要看源码里的判定
现象是调用trade_cal时客户端抛出[40002] 抱歉，您没有访问该接口的权限。很多开发者以为是 token 写错了，反复检查 token 甚至重新注册账号，绕了一圈才发现40002是服务端返回的业务错误码，表示当前账号积分不满足该接口的最低权限。Tushare Pro 的接口按积分分级，基础接口 120 积分可用，部分高频或敏感接口要 2000 积分。客户端源码只负责把code和msg抛出来，不会解析差多少积分，而且积分阈值不在源码里，全部由服务端动态控制，所以升级源码后接口权限可能变化。解决方式是先看接口文档的最低积分要求，再对照账号积分；如果只是本地拉日线，daily和stock_basic属于低分接口，一般够用。最血泪的经验是不要用except Exception: pass吞掉40002，否则程序会带着空 DataFrame 往下跑，最终算出一堆看起来正常的错误结果。至少要把异常重新抛出来或者记录到日志，再按错误码走告警。
4.3 返回数据缺列：fields 写对了，DataFrame 却少列
现象是调daily时传了fields='ts_code,trade_date,open,high,low,close'，返回的 DataFrame 只有前两列，后面几列全部为空，或者某一次调用少了一个字段。我排查过很多次，原因往往不是字段名拼错，而是服务端对某些日期区间没有数据时返回空结构；也有可能是接口文档更新后，字段被拆分或改名。源码的_to_dataframe在items为空时会直接返回空 DataFrame，不会帮你把列补齐，而query方法对fields参数又不做本地校验，写错字段名只会在返回结构里体现出来。解决方式是写一个通用校验函数，在拿到 DataFrame 后按预期字段列表检查set(df.columns) == set(expected_fields)，缺列就报警。有一次在某个内部项目里，文档把vol拆成了vol和amount，旧代码少传了amount，导致回测数据列对不上。用源码里的fields返回日志能很快看到实际返回了哪些字段，比对着文档猜快得多。
4.4 日期参数格式不统一：20240101 与 2024-01-01 并不是都能用
现象是同一个接口，手写日期传2024-01-01能返回数据，换成从数据库读出来的20240101字符串就返回空，或者反过来。原因是 Tushare Pro 的日期参数格式在服务端定义，源码没有做任何格式化。daily这类接口要求YYYYMMDD，而部分旧版接口或高层封装会接受带横线的写法。pro_bar内部会做一层转换，但DataClient.query不会，一旦你绕过pro_bar直接用query，格式就必须严格对齐接口文档。另外，日期格式化最容易出问题的场景是时区，如果你的服务器跑在 UTC，数据库里存的日期是本地日期，直接转字符串会差一天。解决方式是在调用层统一做日期格式化，把日期对象或任意字符串都转成YYYYMMDD再传进query。我在数据管道里加了一个normalize_date函数，在进入query之前统一处理，这样就算换数据源也不会因为日期格式翻车。还要记得start_date和end_date都要传，有些接口不传end_date会默认返回最近一段，容易误导调试。
4.5 循环调接口被限流：重试逻辑藏在哪里
现象是写了个循环拉取多只股票日线，跑了几十次后开始连续抛超时，再往后直接限流错误，停了十分钟又恢复正常。原因是 Tushare Pro 对每分钟访问次数有配额限制，源码里只做了单次请求的timeout控制，没有内置退避重试。很多人以为源码会有重试逻辑，读了client.py才发现根本找不到相关代码。这个限制是按账号维度计算的，同一个 token 下无论是几个进程共享，都会被一起计数，所以分布式管道里要做全局节流，不能只在单进程里 sleep。解决方式有两种：一种是把timeout调大，但这只解决响应慢，解决不了限流；另一种是在调用层加最小间隔，例如time.sleep(0.5)，或者用一个带重试的装饰器，在遇到限流类错误时按指数退避重试。调试限流问题时可以临时在query方法里打一行日志，打印api_name和请求时间戳，能直观看到请求间隔。这个黑匣子打开之后，你就明白为什么别人的批量任务不翻车，而你翻车。
5. 二次开发实战：把 Tushare 客户端改成自己的数据中台
5.1 给你的客户端加一个本地缓存
大多数数据管道不需要每次都向 Tushare 服务器请求，日线数据一天只变一次，完全可以在本地落一份。我会直接继承DataClient，覆盖它的query方法：
from tushare.pro.client import DataClient import pandas as pd import os class CachedClient(DataClient): def __init__(self, token, cache_dir='./cache', timeout=30): super().__init__(token, timeout=timeout) self.cache_dir = cache_dir os.makedirs(cache_dir, exist_ok=True) def query(self, api_name, fields='', **kwargs): cache_path = self._cache_path(api_name, kwargs) if os.path.exists(cache_path): return pd.read_pickle(cache_path) data = super().query(api_name, fields=fields, **kwargs) df = self._to_dataframe(data) df.to_pickle(cache_path) return df def _cache_path(self, api_name, params): key = api_name + '_' + '_'.join(f'{k}_{v}' for k, v in sorted(params.items())) return os.path.join(self.cache_dir, key + '.pkl')逻辑说明：这个缓存的粒度是“接口名 + 查询参数”，同一个参数组合只请求一次。to_pickle把 DataFrame 序列化到本地，下次直接读文件，既不占用网络请求，也避免了解析耗时的重复劳动。这里要做的是先调用父类query拿到原始 dict，再调_to_dataframe转换，顺序不要反，否则缓存里存的就是原始 JSON 而不是 DataFrame。
参数说明：cache_dir是缓存目录，建议按日期再分一层，避免数据过期；这个实现没有做失效时间，如果想每天刷新，可以把日期拼进缓存路径，例如daily_20240101_...pkl。注意kwargs的键顺序会影响缓存文件名，所以_cache_path里先sorted再拼接，避免相同查询生成两个不同缓存。
5.2 做一个统一的字段校验层
二次开发时最怕的不是接口报错，而是接口不报错但数据悄悄缺列。我会在缓存之上再加一个字段校验器，把服务端返回的实际字段和业务层期望字段做比对：
class FieldValidator: def __init__(self, expected_fields): self.expected = set(expected_fields) def validate(self, df, api_name): missing = self.expected - set(df.columns) if missing: raise ValueError(f'{api_name} missing fields: {missing}') return df逻辑说明：validate在每次数据落地后执行，把预期字段缺失直接变成显式异常，而不是让后续计算取到 NaN 再慢慢排查。实战里可以在原始列名和业务列名不一致时做映射，比如把trade_date统一成date、vol统一成volume，这一步建议放在校验层之后、业务层之前，保证下游代码只认一套字段名。
参数说明：expected_fields是一个可迭代对象，建议用列表或元组，内部会转成 set 做差集计算。这个校验器不依赖 Tushare，任何 DataFrame 都能用，所以也可以放到其他数据源的数据管道里。
5.3 验证改动与回归
改完客户端后，不要直接跑整个数据管道，先做三件小事：第一，用真实 token 调一次daily，确认返回 DataFrame 的dtypes是预期的，尤其是日期列别是 object；第二，把requests.postmock 掉，验证缓存层生效，也就是第二次调用不会真的发出 HTTP 请求；第三，跑一遍原有接口调用的最小测试集，确保继承没有破坏ProApi的方法注册。
验证缓存可以用一个简单的 pytest 用例，把requests.post替换成计数函数，连续调用两次CachedClient.query，断言 post 次数是 1。这个测试虽然简单，但能挡住“缓存没生效”这类回归，也能顺带验证_cache_path的 key 生成没有因为参数顺序不同而重复请求。跑测试的时候，记得给 mock 的 post 一个假的 JSON 响应，否则query里resp.json()会直接报错。
我从那以后每次改客户端都强制走一遍“先读 query 实现再动手”的流程，改完必须跑一次真实请求和一次 mock 请求，这两步能挡住大多数继承带来的隐藏问题。希望帮到你。
本文还有配套的精品资源，点击获取
