03-数据获取接口与映射

本文档记录本项目数据获取层使用的接口、对应本地表、参数说明与备用接口。当前主数据源为 akshare（聚合抓取工具，本身不是数据源，聚合了东方财富、新浪、同花顺、雪球、理杏仁等上游），但数据获取层设计为可扩展，未来可接入 Tushare、Wind API、手工 CSV 导入等其他来源。

设计原则

数据获取层不绑定单一数据源，遵循以下原则：

接口抽象：fetcher 层对上只暴露 fetch_xxx 标准函数，内部可切换 akshare / Tushare / 其他来源
主备接口：关键数据准备主备两个接口，主接口失败自动切备
本地库为可信源：所有分析基于本地 SQLite，不直接依赖外部接口实时调用
来源标注：每条数据可通过 source 字段追溯获取渠道（宏观表已含 source 字段，其他表通过 fetcher 日志记录）

认知前提：akshare 的局限

akshare 是当前主数据源，但需认知其局限：

接口稳定性依赖上游：akshare 调用的上游网站接口可能变更或限流，akshare 版本更新可能跟不上
接口命名无强规范：不同接口的参数风格、返回字段、数据格式差异较大
接口可能随时失效：需要为关键数据准备备用接口
版本锁定必要：requirements.txt 锁定 akshare 版本，避免接口签名变化导致脚本失效

基于以上认知，所有外部接口调用集中在 fetcher_*.py 层，业务层不直接调用任何外部库。接口失效时只需修改 fetcher 层，不影响查询接口。

接口分类与映射总览

本地表	akshare 接口	上游来源	频率	备用接口
dim_index	`index_stock_info`	东方财富	低频	`ak.index_stock_info_sina`
index_daily	`stock_zh_index_daily_em`	东方财富	日	`ak.stock_zh_index_daily`（新浪）
index_valuation	`index_value_hist_funddb`	理杏仁	日	自算（用成分股加权）
dim_fund	`fund_name_em`	东方财富	低频	-
fund_daily（ETF）	`fund_etf_hist_em`	东方财富	日	`ak.fund_etf_hist_sina`
fund_daily（场外）	`fund_open_fund_info_em`	东方财富	日	-
fund_holdings	`fund_portfolio_hold_em`	东方财富	季	-
dim_stock	`stock_info_a_code_name`	东方财富	低频	`ak.stock_info_sh_name_code` + `ak.stock_info_sz_name_code`
stock_daily	`stock_zh_a_hist`	东方财富	日	`ak.stock_zh_a_daily`（新浪）
stock_financial	`stock_financial_analysis_indicator`	新浪	季	`ak.stock_financial_report_sina`
dim_industry	`sw_index_first_info`	申万	低频	-
industry_daily	`sw_index_daily`	新浪	日	`ak.sw_index_daily_indicator`
macro_indicator	`macro_china_*` 系列	多源	按指标	见下文分指标列出
money_flow（北向）	`stock_hsgt_north_net_flow_in_em`	东方财富	日	`ak.stock_hsgt_hist_em`
money_flow（两融）	`stock_margin_underlying_info_sz_em`	东方财富	日	`ak.stock_margin_sse` / `ak.stock_margin_szse`

指数数据接口

dim_index 填充

import akshare as ak

# 获取中国股票指数信息
df = ak.index_stock_info()
# 字段：classify, index_name, index_code, publish_date, base_date, base_point

index_daily 填充

# 东方财富源（主用）
df = ak.stock_zh_index_daily_em(symbol="sh000300")
# 参数：symbol 格式为 "sh000300" / "sz399006" / "csi000905"
# 字段：date, open, close, high, low, volume, amount

# 新浪源（备用）
df = ak.stock_zh_index_daily(symbol="sh000300")
# 字段：date, open, high, low, close, volume

index_valuation 填充

# 理杏仁源（PE/PB/股息率历史）
df = ak.index_value_hist_funddb(symbol="沪深300", indicator="市盈率")
# 参数：symbol 为指数简称；indicator 为 "市盈率"/"市净率"/"股息率"
# 字段：trade_date, pe（或 pb/dividend_yield）

注意：理杏仁接口免费版可能有调用频率限制，高频更新需加 sleep。PE/PB 分位数由本地计算，不依赖 akshare。

基金数据接口

dim_fund 填充

# 东方财富全部基金列表
df = ak.fund_name_em()
# 字段：基金代码, 基金简称, 基金类型, 拼音缩写

fund_daily 填充（ETF）

df = ak.fund_etf_hist_em(symbol="510300", period="daily",
                         start_date="20200101", end_date="20251231",
                         adjust="")
# 参数：adjust 为 ""(不复权)/"qfq"(前复权)/"hfq"(后复权)
# 字段：日期, 开盘, 收盘, 最高, 最低, 成交量, 成交额, 振幅, 涨跌幅, 涨跌额, 换手率

fund_daily 填充（场外基金）

df = ak.fund_open_fund_info_em(symbol="110011", indicator="单位净值走势")
# 字段：净值日期, 单位净值, 日增长率

fund_holdings 填充

df = ak.fund_portfolio_hold_em(symbol="110011", date="2025")
# 字段：序号, 股票代码, 股票名称, 占净值比例, 持股数, 持仓市值, 季报披露

注意：持仓数据每季度披露，年度和半年度披露全部，季度披露前十大。date 参数传年份，返回该年所有季报数据。

股票数据接口

dim_stock 填充

df = ak.stock_info_a_code_name()
# 字段：code, name

stock_daily 填充

df = ak.stock_zh_a_hist(symbol="600519", period="daily",
                        start_date="20200101", end_date="20251231",
                        adjust="qfq")
# 字段：日期, 开盘, 收盘, 最高, 最低, 成交量, 成交额, 振幅, 涨跌幅, 涨跌额, 换手率
# 注意：akshare 的 stock_zh_a_hist 不含 PE/PB，需额外调用 stock_a_indicator_lg

PE/PB 补充：

df = ak.stock_a_indicator_lg(symbol="600519")
# 字段：trade_date, pe, pe_ttm, pb, ps, ps_ttm, dv_ratio, dv_ttm, total_mv

stock_financial 填充

df = ak.stock_financial_analysis_indicator(symbol="600519", start_year="2020")
# 字段：日期, 净资产收益率(%), 毛利率(%), 净利率(%), 等
# 注意：字段较多且部分为空，需按需筛选

行业数据接口

dim_industry 填充

# 申万一级行业
df = ak.sw_index_first_info()
# 字段：行业代码, 行业名称

# 申万二级行业
df = ak.sw_index_second_info()

industry_daily 填充

df = ak.sw_index_daily(symbol="801080")
# 参数：symbol 为申万行业代码
# 字段：date, open, close, high, low, volume, amount

宏观数据接口

宏观指标分散在多个 macro_china_* 接口，按指标单独调用：

# CPI
df_cpi = ak.macro_china_cpi_yearly()           # CPI 年率
df_cpi_m = ak.macro_china_cpi_monthly()        # CPI 月率

# PPI
df_ppi = ak.macro_china_ppi_yearly()           # PPI 年率

# PMI
df_pmi = ak.macro_china_pmi()                  # 制造业 PMI

# 货币供应
df_m2 = ak.macro_china_money_supply()          # M0/M1/M2

# 社融
df_sf = ak.macro_china_shrzgm()                # 社会融资规模增量

# GDP
df_gdp = ak.macro_china_gdp_yearly()           # GDP 年率

# 国债收益率
df_bond = ak.bond_zh_us_rate(start_date="20200101")
# 字段：日期, 中国国债收益率2年, 5年, 10年, 30年, 美国国债收益率...

# LPR
df_lpr = ak.macro_china_lpr()                  # LPR 历史

# Shibor
df_shibor = ak.macro_china_shibor_all()        # Shibor 各期限

注意：宏观接口的返回字段名和格式不统一，fetcher 层需做字段标准化，统一写入 macro_indicator 表的 indicator_code/value 结构。

资金流向接口

# 北向资金（按日）
df_north = ak.stock_hsgt_north_net_flow_in_em(symbol="北向资金")
df_sh = ak.stock_hsgt_north_net_flow_in_em(symbol="沪股通")
df_sz = ak.stock_hsgt_north_net_flow_in_em(symbol="深股通")

# 两融余额
df_margin = ak.stock_margin_underlying_info_sz_em()
# 或按市场分别查
df_margin_sh = ak.stock_margin_sse(start_date="20200101")
df_margin_sz = ak.stock_margin_szse(start_date="20200101")

接口版本锁定

requirements.txt 中锁定 akshare 版本：

akshare>=1.14.0,<2.0.0

升级 akshare 前必须跑一遍 update_all.py 的 dry-run 模式，验证接口签名未变化。接口失效时的应对见 04-数据更新与调度策略。

接口调用频率控制

akshare 调用上游网站接口，高频请求会触发限流。fetcher 层内置频率控制：

接口类型	建议 sleep	理由
批量列表（如 fund_name_em）	无需	单次调用返回全量
单标的按日期（如 stock_zh_a_hist）	0.5s	避免触发东财限流
估值接口（理杏仁）	1s	免费版限流严格
宏观接口	0.3s	上游来源分散，限流较松

频率控制在 fetcher_*.py 的 fetch_with_retry 工具函数中统一实现，见 02-数据脚本。

#03-数据获取接口与映射

#设计原则

#认知前提：akshare 的局限

#接口分类与映射总览

#指数数据接口

#dim_index 填充

#index_daily 填充

#index_valuation 填充

#基金数据接口

#dim_fund 填充

#fund_daily 填充（ETF）

#fund_daily 填充（场外基金）

#fund_holdings 填充

#股票数据接口

#dim_stock 填充

#stock_daily 填充

#stock_financial 填充

#行业数据接口

#dim_industry 填充

#industry_daily 填充

#宏观数据接口

#资金流向接口

#接口版本锁定

#接口调用频率控制