financial-api-rs
面向同花顺官方金融数据服务的异步 Rust
客户端。当前版本覆盖 llms-full.txt 中已经上线的 59 个 REST 端点,统一完成 API Key
注入、HTTP 传输、响应信封解码和业务错误分类。
安装 crates.io 上的 0.1.1 版本:
cargo add financial-api@0.1.1
源码与问题跟踪位于 Choi-Jungwoo/financial-api-rs。
快速开始
设置上游官方约定的环境变量:
export HITHINK_FINANCE_API_KEY='<your-api-key>'
然后创建客户端并调用端点:
use ;
async
也可以显式提供 Key,并配置私有部署或测试服务:
use ;
use Duration;
ApiKey 的调试输出始终脱敏,底层 HTTP Header 也被标记为敏感。不要在业务日志中自行输出
原始凭据。
响应与错误
所有端点先检查统一业务信封。HTTP 200 但 code != 0 会返回 Error::Business,不会被误当
作成功。BusinessError::kind() 提供认证、权限、未找到、数据未就绪、限流和上游不可用等
恢复类别;原始 code、message 与 request_id 仍可读取。
各端点返回 Response<端点数据类型>,例如标的检索返回 Response<TickerData>。响应
结构使用公开 DTO 表达;上游的 null 使用 Option 保留,数组顺序保持不变,不透明游标
使用 Cursor 原样回传:
use ;
少数上游本身就是动态对象的字段仍使用 JsonValue,但不会把整个普通端点退化为无类型
JSON。全市场导出接口返回 MarketDumpUrl;其中预签名 URL 包装为 SecretUrl,调试输出
不会泄露签名,只有显式调用 expose() 才能取出。
估值端点的十进制数使用 PreciseDecimal 保留 JSON 源数字,不经过二进制浮点转换;可通过
Display 或 as_number() 读取其无损表示。
领域类型
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。
契约与边界
- 具体请求参数、字段和错误语义以完整聚合文档与 API 总览为准。
- 本 crate 不缓存、拼接或改写金融数据,也不承诺上游服务的可用性、完整性、延迟和权限。
null不补零;不透明游标原样回传;自然日不会被解释成交易日。- 本软件及示例不构成投资建议。使用上游服务和数据时仍需遵守适用条款。
许可证
本仓库软件与文档使用 MIT License。该许可证不授予同花顺服务、数据、商标或 其他上游资产的权利。