financial-api-rs
面向同花顺官方金融数据服务的 Rust 客户端 crate,目标是以类型安全、可测试且符合 Rust 习惯的接口访问 A 股、指数、基金及同花顺特色 数据。
[!IMPORTANT] 本项目处于 pre-alpha 阶段。当前仓库仍是初始化骨架,尚未提供可用的金融数据客户端, 也尚未发布到 crates.io。请勿将下方规划能力理解为已经实现。
官方资源
官方项目与在线文档定义上游服务和数据契约;本仓库只负责 Rust 客户端实现。上游能力发生 变化时,以具体端点文档为准。
项目目标
- 提供清晰、稳定且符合 Rust API Guidelines 的客户端接口。
- 用领域类型区分完整标的代码、纯代码、自然日、交易日、报告期和复权口径。
- 统一处理 API Key 注入、HTTP 传输和响应信封,同时区分网络、解码与业务失败。
- 准确保留上游的缺失值、顺序、游标、时间单位和百分比口径。
- 使用离线 fixture 验证协议映射,让默认测试不依赖网络或真实账户。
- 将依赖、feature 与公共 API 控制在完成当前能力所需的最小范围。
规划范围
| 能力 | 目标范围 | crate 状态 |
|---|---|---|
| 客户端基础层 | 鉴权、传输、响应信封、错误分类 | 规划中 |
| 标的元信息 | 标的检索、代码表与跨市场消歧 | 规划中 |
| A 股数据 | 行情、K 线、交易日历、复权、财务与估值 | 规划中 |
| 指数数据 | 标准指数、同花顺指数、成分股与行情 | 规划中 |
| 基金数据 | 资料、持仓、业绩、经理、财务、资讯与场内行情 | 规划中 |
| 特色数据 | 集合竞价、涨跌停、热榜、异动与龙虎榜 | 规划中 |
该表是路线图,不是兼容性承诺。实际支持范围将在实现完成并具备可执行测试后逐项标记。
当前状态
src/lib.rs 目前只包含初始化占位代码,因此没有可靠的安装或调用示例。首个可用版本发布后,
本节将提供:
cargo add安装命令;- 最小可编译调用示例;
- API Key 配置方式;
- 错误恢复示例;
- 已实现端点与 feature 矩阵。
在此之前,如需立即访问数据,请使用官方项目 提供的 REST API、MCP、CLI 或 Python 工具。
设计原则
类型表达领域约束
完整标的代码、有限枚举和日期范围会在边界完成验证。内部代码不依赖裸字符串、布尔组合或 哨兵值表达关键状态。
业务成功不等于 HTTP 成功
上游业务结果通过统一响应信封的 code 表达。客户端会把 HTTP 传输成功与业务成功分开,
并按调用方可采取的恢复动作设计错误类别。
忠实保留数据语义
客户端不会将 null 补成零,不会改写不透明分页游标,也不会混淆自然日、交易日、数据时间
和报告期。端点未承诺的参数规范化不会由客户端擅自添加。
默认离线验证
单元和契约测试使用脱敏 fixture 或本地 mock。需要真实 API Key 和网络的契约测试必须显式 启用并默认忽略。
安全
API Key 与同花顺账户绑定。请将凭据保存在环境变量、系统凭据库或专用 secret manager 中; 不要把 Key 写入源码、提交记录、日志、错误信息、测试 fixture 或问题报告。
官方工具推荐使用 HITHINK_FINANCE_API_KEY。在本 crate 明确发布自己的配置契约前,这只是
上游工具约定,不代表当前 Rust 客户端已实现自动读取。
如发现本仓库存在可能泄露凭据或影响用户安全的问题,请通过维护者提供的私密安全渠道报告, 不要先公开完整复现数据。
贡献
项目尚处于搭建期,适合从一个边界清晰的端点开始贡献:
- 在官方 API 索引中定位一个已上线端点,并核对其完整请求、响应和错误契约。
- 检查仓库已有能力、Rust 标准库和成熟生态方案,说明选择与淘汰理由。
- 按 Red-Green-Refactor 添加离线契约测试和最小实现。
- 通过
mise.toml中定义的格式、静态检查、测试和文档任务。 - 在变更说明中列出已验证范围、未运行项和上游仍未保证的风险。
仓库尚未建立统一的 issue/PR 模板。提交贡献时,请至少说明目标端点、上游文档链接、公共 API 变化和可复现的验证命令。
项目边界
- 本 crate 不是行情数据源,不缓存或转售上游数据。
- 本 crate 不承诺上游服务的可用性、数据完整性、延迟或访问权限。
- 本项目提供的软件与示例不构成投资建议。
- 使用同花顺服务和数据时,仍需遵守官方项目及服务适用的条款。
许可证
本仓库的软件以 MIT License 开源。
MIT 许可证仅适用于本仓库的软件与文档,不授予同花顺服务、数据、商标或其他上游资产的权利。