Skip to main content

Crate financial_api

Crate financial_api 

Source
Expand description

§financial-api-rs

License: MIT

面向同花顺官方金融数据服务的异步 Rust 客户端。当前版本覆盖 llms-full.txt 中已经上线的 59 个 REST 端点,统一完成 API Key 注入、HTTP 传输、响应信封解码和业务错误分类。

安装 crates.io 版本:

cargo add financial-api

源码与问题跟踪位于 Choi-Jungwoo/financial-api-rs。

§快速开始

设置上游官方约定的环境变量:

export HITHINK_FINANCE_API_KEY='<your-api-key>'

然后创建客户端并调用端点:

use financial_api::{Client, Error, TickerSearchRequest};

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = Client::from_env()?;
    let request = TickerSearchRequest::new("贵州茅台")?;
    let response = client.tickers_search(&request).await?;

    println!("request_id={}", response.request_id());
    println!("{:#?}", response.data());
    Ok(())
}

也可以显式提供 Key,并配置私有部署或测试服务:

use financial_api::{ApiKey, Client, Error};
use std::time::Duration;

fn client() -> Result<Client, Error> {
    Client::builder(ApiKey::new("<your-api-key>")?)
        .timeout(Duration::from_secs(20))
        .build()
}

ApiKey 的调试输出始终脱敏,底层 HTTP Header 也被标记为敏感。不要在业务日志中自行输出 原始凭据。

§端点示例

examples/ 为当前支持的 59 个端点分别提供了可运行示例。文件名与 SUPPORTED_ENDPOINTS 中的端点名称一致,例如:

cargo run --example tickers_search
cargo run --example prices_historical
cargo run --example fund_performance_nav
cargo run --example market_dump_daily_k

示例会先尝试从仓库根目录的 .env 加载凭证,也兼容已经由 shell 设置的环境变量:

HITHINK_FINANCE_API_KEY='<your-api-key>'

这些示例会访问真实上游服务,需要相应账号权限和网络连接。开发质量门中的 mise run check 会编译全部示例,但不会发送网络请求。

§响应与错误

所有端点先检查统一业务信封。HTTP 200 但 code != 0 会返回 Error::Business,不会被误当 作成功。BusinessError::kind() 提供认证、权限、未找到、数据未就绪、限流和上游不可用等 恢复类别;原始 code、message 与 request_id 仍可读取。

各端点返回 Response<端点数据类型>,例如标的检索返回 Response<TickerData>。响应 结构使用公开 DTO 表达;上游的 null 使用 Option 保留,数组顺序保持不变,不透明游标 使用 Cursor 原样回传:

use financial_api::{Error, TickerData, Response};

fn consume(response: Response<TickerData>) -> Result<(), Error> {
    for ticker in &response.data().item {
        println!("{} {}", ticker.thscode, ticker.name);
    }
    Ok(())
}

少数上游本身就是动态对象的字段仍使用 JsonValue,但不会把整个普通端点退化为无类型 JSON。全市场导出接口返回 MarketDumpUrl;其中预签名 URL 包装为 SecretUrl,调试输出 不会泄露签名,只有显式调用 expose() 才能取出。

估值端点的十进制数使用 PreciseDecimal 保留 JSON 源数字,不经过二进制浮点转换;可通过 Display 或 as_number() 读取其无损表示。

§0.2 API 调整

为保留实时上游的实际响应语义,AuctionSnapshotData::auction_phase 改用响应专用的 AuctionPhase;涨停天梯日期统一为 NaturalDate;基金费率保留为带单位的文本;诊断分类 改用 FundCategoryCode;资产配置报告日和经理雷达节点字段改为可选值。迁移时应同步调整 显式类型标注,并在读取可选字段前处理 None。

§领域类型

  • Thscode 表示带市场后缀的完整标的代码。
  • AShareCode 进一步限制为六位数字加 .SH、.SZ 或 .BJ。
  • NaturalDate 验证 YYYY-MM-DD 和真实公历日期。
  • UnixMillis 拒绝负时间戳。
  • FinancialRange 通过受控构造让“最近 N 期”和“起止时间”互斥。
  • 复权、报告频率、基金类型、排行榜周期、排序字段等有限集合均使用枚举。

端点方法直接接受标的代码、日期、报告类型和游标的字符串表示,并在方法边界完成规范化与 校验;调用者只在需要持久保存或复用已验证值时才需要显式构造领域类型。

无损转换实现 From;可能失败的外部文本转换实现 FromStr 或显式构造函数,避免绕过领域 校验。

§已支持范围

分组端点数能力
元信息2标的检索、标的列表
A 股22行情、复权、财报、交易日历、竞价、估值、异动、热榜、龙虎榜、涨跌停
A 股指数4同花顺指数目录、成分股、行情快照、历史日线
基金28资料、持仓、业绩、持有人、经理、公司、财务、诊断、募集、资讯、行情
全市场导出3十年日 K、近十日日 K、复权因子下载 URL

SUPPORTED_ENDPOINTS 提供当前编译版本的完整端点名称和路径,可用于能力展示或兼容性检查。

上游文档中明确标为“敬请期待”的 A 股基础信息、指数基础信息/权重,以及按个股反查同花顺 指数归属不在支持范围内。

§开发与验证

工具链和任务统一由 mise.toml 管理:

mise install
mise run fmt
mise run check
mise run clippy
mise run test
mise run doc
mise run doc-test

默认测试只使用本地 mock server,不需要网络、真实账号或 API Key。 配置 .env 后,可用 mise run test-examples-live 顺序执行全部 59 个实时示例;任务会在请求 之间留出间隔,并在结束时汇总成功和失败数量。

§契约与边界

  • 具体请求参数、字段和错误语义以完整聚合文档与 API 总览为准。
  • 本 crate 不缓存、拼接或改写金融数据,也不承诺上游服务的可用性、完整性、延迟和权限。
  • null 不补零;不透明游标原样回传;自然日不会被解释成交易日。
  • 本软件及示例不构成投资建议。使用上游服务和数据时仍需遵守适用条款。

§许可证

本仓库软件与文档使用 MIT License。该许可证不授予同花顺服务、数据、商标或 其他上游资产的权利。

Structs§

AShareCode
限定在 A 股标的宇宙内的完整标的代码。
AdjustmentFactorItem
AdjustmentFactorsData
指定 A 股标的的复权事件。
AnomalyItem
ApiKey
以敏感 HTTP 请求头值保存的已校验 API Key。
AuctionBenchmarkData
AuctionBenchmarkItem
AuctionSnapshotData
AuctionSnapshotItem
BalanceSheetItem
BusinessError
从响应信封中解码出的非零业务结果。
CashFlowStatementItem
Client
可复用的异步 API 客户端。
ClientBuilder
用于配置客户端级可选传输参数的构建器。
CompactDate
在线路协议中编码为 YYYYMMDD 的已校验公历自然日。
CompanyId
从基金资料数据中发现的不透明基金公司标识。
ConceptItem
Cursor
游标分页端点返回的不透明分页游标。
DragonTigerData
DragonTigerStockItem
EndpointInfo
一个已支持 REST 能力的稳定名称和路径。
FinancialAbility
FinancialIndicator
FinancialIndicatorsData
FinancialRange
“最近报告期”和“时间戳区间”互斥的财务查询。
FinancialReport
YYYY-[1-4] 格式的财务报告期标识。
FinancialStatementMeta
上市公司三类财务报表共用的字段。
FundAssetAllocationItem
FundBalanceSheetItem
FundCategoryCode
在诊断数据中观察到的不透明基金分类代码。
FundCompanyItem
FundDiagnosticsItem
FundDividendItem
FundDividendsData
FundDrawdownsItem
FundFinancialIndicatorsItem
FundHolderItem
FundHoldingItem
FundHoldingsData
FundIncomeStatementItem
FundIndicatorHistoryItem
FundIndustryAllocationItem
FundManagerDetailItem
FundManagerExperienceItem
FundManagerPerformanceItem
FundManagerRadarComparison
按类别和区间对齐的一项基金经理同类比较雷达节点。
FundManagerRef
FundManagerStyleItem
FundMarketHistoricalData
FundMarketSnapshotData
FundMarketSnapshotItem
FundNavItem
FundNewsData
FundNewsItem
FundOfferingItem
FundPortfolioHistoryItem
FundProfileItem
FundRateInfo
FundReportDateItem
FundReturnsItem
FundTopHolderItem
FundTopHoldersData
FundTradeRule
HistoricalData
历史日 K 线载荷。
HotMoneyItem
HotStockHistoryData
HotStockHistoryItem
HotStockItem
HotStockTrendItem
IncomeStatementItem
IndexCatalogItem
IndexConstituentItem
IndexHistoricalData
指数历史行情包含固定为 null 的复权字段。
LadderBoardCaps
LadderBoards
LadderData
LadderDay
LadderStock
LadderWindow
LimitBreakItem
LimitDownItem
LimitUpItem
ManagerId
从基金资料数据中发现的不透明基金经理标识。
MarketDumpUrl
短期有效的市场数据包下载授权。
NaturalDate
序列化为 YYYY-MM-DD 的已校验公历自然日。
Page
特色数据池使用的已校验分页参数。
Pagination
PoolData
PreciseDecimal
保留源数字且不转换为二进制浮点数的 JSON 十进制数。
PriceBarItem
一条日开高低收量 K 线。
PriceSnapshotData
A 股或指数的行情快照载荷。
PriceSnapshotItem
一条最新行情记录。
PriceSnapshotSelection
显式指定的标的,或完整 A 股标的宇宙中的一页。
ReportType
从报告期端点中发现的基金披露报告类型。
Response
通过通用业务信封校验后的成功响应。
SecretUrl
调试表示始终脱敏的短期预签名 URL。
ShanghaiDateMillis
以 Asia/Shanghai 时区午夜 Unix 毫秒值表示的自然日。
Thscode
包含市场后缀的完整标的代码。
TickerItem
一条规范化标的代码记录。
TickerListRequest
用于浏览标的代码表的参数。
TickerSearchRequest
用于标的搜索和跨市场消歧的参数。
TimestampedItems
将业务记录保存在 item 中的带时间戳端点载荷。
TradingDayItem
UnixMillis
非负 Unix 毫秒时间戳。
ValidationError
请求领域值或客户端配置值无效。
ValuationItem
ValuationsData

Enums§

Adjustment
历史行情复权口径。
AnomalyTag
A 股异动标签。
AssetType
规范化的最细粒度资产类型。
AuctionPhase
集合竞价快照响应中的阶段。
AuctionStage
集合竞价快照请求接受的阶段。
BusinessErrorKind
上游非零业务结果对应的稳定恢复类别。
DailyInterval
基金历史行情返回的固定日 K 线周期。
DragonTigerBoard
龙虎榜榜单筛选条件。
Error
配置或调用 API 时产生的失败。
Exchange
元数据 API 支持的交易所筛选条件。
FinancialAbilityKind
固定的财务分析能力分组。
FinancialIndicatorId
上游契约定义的财务指标标识。
FinancialPeriod
财务报表频率。
FiscalPeriod
上市公司财务报表返回的会计期间。
FundNavType
基金净值序列选择。
FundRange
基金历史净值区间。
FundType
基金标的宇宙。
HolderMergeScope
持有人记录合并策略。
HolderRecordScope
基金持有人记录返回的实际披露范围。
HotListPeriod
排名聚合周期。
IndexTag
同花顺指数目录标签。
JsonValue
Represents any valid JSON value.
LimitBreakSortField
炸板池排序字段。
LimitDownSortField
跌停池排序字段。
LimitUpSortField
涨停池排序字段。
ManagerPerformanceRange
基金经理业绩区间。
OfferingStatus
新发基金认购状态。
PortfolioAssetType
基金持仓披露使用的资产类别。
RankTrend
热榜排名变化方向。
SortDirection
特色数据分页池使用的排序方向。

Constants§

SUPPORTED_ENDPOINTS
上游契约中当前所有可用的 REST 端点。

Type Aliases§

AnomalyData
BalanceSheetsData
CashFlowStatementsData
FundAssetAllocationData
FundBalanceSheetsData
FundCompanyData
FundDiagnosticsData
FundDrawdownsData
FundFinancialIndicatorsData
FundHoldersData
FundIncomeStatementsData
FundIndicatorHistoryData
FundIndustryAllocationData
FundManagerDetailData
FundManagerExperienceData
FundManagerPerformanceData
FundManagerStyleData
FundNavData
FundOfferingsData
FundPortfolioHistoryData
FundProfileData
FundReportDatesData
FundReturnsData
HotStockData
HotStockTrendData
IncomeStatementsData
IndexCatalogData
IndexConstituentsData
LimitBreakData
LimitDownData
LimitUpData
TickerData
TradingDaysData