Expand description
§financial-api-rs
面向同花顺官方金融数据服务的异步 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, SearchQuery, TickerSearchRequest};
#[tokio::main]
async fn main() -> Result<(), Error> {
let client = Client::from_env()?;
let request = TickerSearchRequest::new(SearchQuery::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§
- AShare
Code - 限定在 A 股标的宇宙内的完整标的代码。
- Adjustment
Factor Item - Adjustment
Factors Data - 指定 A 股标的的复权事件。
- Anomaly
Item - ApiKey
- 以敏感 HTTP 请求头值保存的已校验 API Key。
- Auction
Benchmark Data - Auction
Benchmark Item - Auction
Snapshot Data - Auction
Snapshot Item - Balance
Sheet Item - Business
Error - 从响应信封中解码出的非零业务结果。
- Cash
Flow Statement Item - Client
- 可复用的异步 API 客户端。
- Client
Builder - 用于配置客户端级可选传输参数的构建器。
- Compact
Date - 在线路协议中编码为
YYYYMMDD的已校验公历自然日。 - Company
Id - 从基金资料数据中发现的不透明基金公司标识。
- Concept
Item - Cursor
- 游标分页端点返回的不透明分页游标。
- Dragon
Tiger Data - Dragon
Tiger Stock Item - Endpoint
Info - 一个已支持 REST 能力的稳定名称和路径。
- Financial
Ability - Financial
Indicator - Financial
Indicators Data - Financial
Report YYYY-[1-4]格式的财务报告期标识。- Financial
Statement Meta - 上市公司三类财务报表共用的字段。
- Fund
Asset Allocation Item - Fund
Balance Sheet Item - Fund
Category Code - 在诊断数据中观察到的不透明基金分类代码。
- Fund
Company Item - Fund
Diagnostics Item - Fund
Dividend Item - Fund
Dividends Data - Fund
Drawdowns Item - Fund
Financial Indicators Item - Fund
Holder Item - Fund
Holding Item - Fund
Holdings Data - Fund
Income Statement Item - Fund
Indicator History Item - Fund
Industry Allocation Item - Fund
Manager Detail Item - Fund
Manager Experience Item - Fund
Manager Performance Item - Fund
Manager Radar Comparison - 按类别和区间对齐的一项基金经理同类比较雷达节点。
- Fund
Manager Ref - Fund
Manager Style Item - Fund
Market Historical Data - Fund
Market Snapshot Data - Fund
Market Snapshot Item - Fund
NavItem - Fund
News Data - Fund
News Item - Fund
Offering Item - Fund
Portfolio History Item - Fund
Profile Item - Fund
Rate Info - Fund
Report Date Item - Fund
Returns Item - Fund
TopHolder Item - Fund
TopHolders Data - Fund
Trade Rule - Historical
Data - 历史日 K 线载荷。
- HotMoney
Item - HotStock
History Data - HotStock
History Item - HotStock
Item - HotStock
Trend Item - Income
Statement Item - Index
Catalog Item - Index
Constituent Item - Index
Historical Data - 指数历史行情包含固定为
null的复权字段。 - Ladder
Board Caps - Ladder
Boards - Ladder
Data - Ladder
Day - Ladder
Stock - Ladder
Window - Limit
Break Item - Limit
Down Item - Limit
UpItem - Manager
Id - 从基金资料数据中发现的不透明基金经理标识。
- Market
Dump Url - 短期有效的市场数据包下载授权。
- Natural
Date - 序列化为
YYYY-MM-DD的已校验公历自然日。 - Page
- 特色数据池使用的已校验分页参数。
- Pagination
- Pool
Data - Precise
Decimal - 保留源数字且不转换为二进制浮点数的 JSON 十进制数。
- Price
BarItem - 一条日开高低收量 K 线。
- Price
Snapshot Data - A 股或指数的行情快照载荷。
- Price
Snapshot Item - 一条最新行情记录。
- Report
Type - 从报告期端点中发现的基金披露报告类型。
- Response
- 通过通用业务信封校验后的成功响应。
- Search
Query - 用于跨市场标的检索的非空搜索文本。
- Secret
Url - 调试表示始终脱敏的短期预签名 URL。
- Shanghai
Date Millis - 以
Asia/Shanghai时区午夜 Unix 毫秒值表示的自然日。 - Thscode
- 包含市场后缀的完整标的代码。
- Ticker
Item - 一条规范化标的代码记录。
- Ticker
List Request - 用于浏览标的代码表的参数。
- Ticker
Search Request - 用于标的搜索和跨市场消歧的参数。
- Timestamped
Items - 将业务记录保存在
item中的带时间戳端点载荷。 - Trading
DayItem - Unix
Millis - 非负 Unix 毫秒时间戳。
- Validation
Error - 请求领域值或客户端配置值无效。
- Valuation
Item - Valuations
Data
Enums§
- Adjustment
- 历史行情复权口径。
- Anomaly
Tag - A 股异动标签。
- Asset
Type - 规范化的最细粒度资产类型。
- Auction
Phase - 集合竞价快照响应中的阶段。
- Auction
Stage - 集合竞价快照请求接受的阶段。
- Business
Error Kind - 上游非零业务结果对应的稳定恢复类别。
- Daily
Interval - 基金历史行情返回的固定日 K 线周期。
- Dragon
Tiger Board - 龙虎榜榜单筛选条件。
- Error
- 配置或调用 API 时产生的失败。
- Exchange
- 元数据 API 支持的交易所筛选条件。
- Financial
Ability Kind - 固定的财务分析能力分组。
- Financial
Indicator Id - 上游契约定义的财务指标标识。
- Financial
Period - 财务报表频率。
- Financial
Range - “最近报告期”和“时间戳区间”互斥的财务查询。
- Fiscal
Period - 上市公司财务报表返回的会计期间。
- Fund
NavType - 基金净值序列选择。
- Fund
Range - 基金历史净值区间。
- Fund
Type - 基金标的宇宙。
- Holder
Merge Scope - 持有人记录合并策略。
- Holder
Record Scope - 基金持有人记录返回的实际披露范围。
- HotList
Period - 排名聚合周期。
- Index
Tag - 同花顺指数目录标签。
- Json
Value - Represents any valid JSON value.
- Limit
Break Sort Field - 炸板池排序字段。
- Limit
Down Sort Field - 跌停池排序字段。
- Limit
UpSort Field - 涨停池排序字段。
- Manager
Performance Range - 基金经理业绩区间。
- Offering
Status - 新发基金认购状态。
- Portfolio
Asset Type - 基金持仓披露使用的资产类别。
- Price
Snapshot Selection - 显式指定的标的,或完整 A 股标的宇宙中的一页。
- Rank
Trend - 热榜排名变化方向。
- Sort
Direction - 特色数据分页池使用的排序方向。
Constants§
- SUPPORTED_
ENDPOINTS - 上游契约中当前所有可用的 REST 端点。
Type Aliases§
- Anomaly
Data - Balance
Sheets Data - Cash
Flow Statements Data - Fund
Asset Allocation Data - Fund
Balance Sheets Data - Fund
Company Data - Fund
Diagnostics Data - Fund
Drawdowns Data - Fund
Financial Indicators Data - Fund
Holders Data - Fund
Income Statements Data - Fund
Indicator History Data - Fund
Industry Allocation Data - Fund
Manager Detail Data - Fund
Manager Experience Data - Fund
Manager Performance Data - Fund
Manager Style Data - Fund
NavData - Fund
Offerings Data - Fund
Portfolio History Data - Fund
Profile Data - Fund
Report Dates Data - Fund
Returns Data - HotStock
Data - HotStock
Trend Data - Income
Statements Data - Index
Catalog Data - Index
Constituents Data - Limit
Break Data - Limit
Down Data - Limit
UpData - Ticker
Data - Trading
Days Data