Skip to main content

financial_api/
index.rs

1use crate::endpoints;
2use crate::endpoints::join_thscodes;
3use crate::types::TEN_YEARS_MS;
4use crate::{
5    Client, Error, IndexCatalogData, IndexConstituentsData, IndexHistoricalData, IndexTag,
6    PriceSnapshotData, Response, Thscode, UnixMillis, ValidationError,
7};
8
9impl Client {
10    /// 按目录标签列出同花顺指数。
11    ///
12    /// # 示例
13    #[doc = concat!(
14        "```no_run\n",
15        include_str!("../examples/index_catalog_ths_index_list.rs"),
16        "\n```"
17    )]
18    pub async fn index_catalog_ths_index_list(
19        &self,
20        tag: IndexTag,
21    ) -> Result<Response<IndexCatalogData>, Error> {
22        self.get(endpoints::INDEX_CATALOG, &[("tag", tag.to_string())])
23            .await
24    }
25
26    /// 获取指定指数当前的成分股列表。
27    ///
28    /// # 示例
29    #[doc = concat!(
30        "```no_run\n",
31        include_str!("../examples/index_constituents_ths_stock_list.rs"),
32        "\n```"
33    )]
34    pub async fn index_constituents_ths_stock_list(
35        &self,
36        thscode: impl AsRef<str> + Send,
37    ) -> Result<Response<IndexConstituentsData>, Error> {
38        let thscode = Thscode::new(thscode)?;
39        self.get(
40            endpoints::INDEX_CONSTITUENTS,
41            &[("thscode", thscode.as_str())],
42        )
43        .await
44    }
45
46    /// 获取一个或多个交易所指数或同花顺指数的行情快照。
47    ///
48    /// # 示例
49    #[doc = concat!(
50        "```no_run\n",
51        include_str!("../examples/index_prices_snapshot.rs"),
52        "\n```"
53    )]
54    pub async fn index_prices_snapshot(
55        &self,
56        thscodes: &[impl AsRef<str> + Sync],
57    ) -> Result<Response<PriceSnapshotData>, Error> {
58        self.get(
59            endpoints::INDEX_SNAPSHOT,
60            &[("thscodes", join_thscodes(thscodes, None)?)],
61        )
62        .await
63    }
64
65    /// 获取指定指数的历史日 K 线。
66    ///
67    /// # 示例
68    #[doc = concat!(
69        "```no_run\n",
70        include_str!("../examples/index_prices_historical.rs"),
71        "\n```"
72    )]
73    pub async fn index_prices_historical(
74        &self,
75        thscode: impl AsRef<str> + Send,
76        start: i64,
77        end: i64,
78    ) -> Result<Response<IndexHistoricalData>, Error> {
79        let thscode = Thscode::new(thscode)?;
80        let start = UnixMillis::new(start)?;
81        let end = UnixMillis::new(end)?;
82        validate_history_window(start, end)?;
83        let query = [
84            ("thscode", thscode.into_string()),
85            ("interval", "1d".to_owned()),
86            ("start", start.to_string()),
87            ("end", end.to_string()),
88        ];
89        self.get(endpoints::INDEX_HISTORICAL, &query).await
90    }
91}
92
93fn validate_history_window(start: UnixMillis, end: UnixMillis) -> Result<(), ValidationError> {
94    if end < start {
95        return Err(ValidationError::new(
96            "end",
97            "must not be earlier than start",
98        ));
99    }
100    if end.get() - start.get() > TEN_YEARS_MS {
101        return Err(ValidationError::new(
102            "end",
103            "requested time window exceeds ten years",
104        ));
105    }
106    Ok(())
107}
108
109#[cfg(test)]
110mod tests {
111    use super::*;
112    use crate::ApiKey;
113
114    #[test]
115    fn historical_window_enforces_order_and_ten_year_limit() {
116        let start = UnixMillis::new(1_000_000_000_000).unwrap();
117        let before_start = UnixMillis::new(start.get() - 1).unwrap();
118        let limit = UnixMillis::new(start.get() + TEN_YEARS_MS).unwrap();
119        let after_limit = UnixMillis::new(limit.get() + 1).unwrap();
120
121        assert!(validate_history_window(start, before_start).is_err());
122        assert!(validate_history_window(start, limit).is_ok());
123        assert!(validate_history_window(start, after_limit).is_err());
124    }
125
126    #[tokio::test]
127    async fn historical_prices_keeps_window_validation_on_its_call_edge() {
128        let client = Client::builder(ApiKey::new("test-api-key").unwrap())
129            .base_url("http://127.0.0.1:9")
130            .build()
131            .unwrap();
132        let index = Thscode::new("000300.SH").unwrap();
133        let start = UnixMillis::new(1_000_000_000_000).unwrap();
134        let invalid_ends = [
135            UnixMillis::new(start.get() - 1).unwrap(),
136            UnixMillis::new(start.get() + TEN_YEARS_MS + 1).unwrap(),
137        ];
138
139        for end in invalid_ends {
140            let error = client
141                .index_prices_historical(&index, start.get(), end.get())
142                .await
143                .unwrap_err();
144            assert!(matches!(error, Error::InvalidInput(_)));
145        }
146    }
147}