Skip to main content

financial_api/fund/
performance.rs

1use crate::endpoints;
2use crate::{
3    Client, Error, FundDrawdownsData, FundIndicatorHistoryData, FundNavData, FundNavType,
4    FundRange, FundReturnsData, FundType, Response, Thscode, UnixMillis,
5};
6
7use super::{FundTarget, validate_history_range};
8
9impl Client {
10    /// 获取基金净值序列。
11    ///
12    /// # 示例
13    #[doc = concat!(
14        "```no_run\n",
15        include_str!("../../examples/fund_performance_nav.rs"),
16        "\n```"
17    )]
18    pub async fn fund_performance_nav(
19        &self,
20        fund_type: FundType,
21        thscode: &Thscode,
22        range: Option<FundRange>,
23        nav_type: FundNavType,
24    ) -> Result<Response<FundNavData>, Error> {
25        let mut query = FundTarget::new(fund_type, thscode)?.query();
26        if let Some(range) = range {
27            query.push(("range", range.to_string()));
28        }
29        query.push(("nav_type", nav_type.to_string()));
30        self.get(endpoints::FUND_NAV, &query).await
31    }
32
33    /// 获取基金多个区间的收益率及同类排名。
34    ///
35    /// # 示例
36    #[doc = concat!(
37        "```no_run\n",
38        include_str!("../../examples/fund_performance_returns.rs"),
39        "\n```"
40    )]
41    pub async fn fund_performance_returns(
42        &self,
43        fund_type: FundType,
44        thscode: &Thscode,
45    ) -> Result<Response<FundReturnsData>, Error> {
46        self.fund_detail(endpoints::FUND_RETURNS, fund_type, thscode)
47            .await
48    }
49
50    /// 获取基金历史业绩指标。
51    ///
52    /// # 示例
53    #[doc = concat!(
54        "```no_run\n",
55        include_str!("../../examples/fund_performance_indicators_historical.rs"),
56        "\n```"
57    )]
58    pub async fn fund_performance_indicators_historical(
59        &self,
60        fund_type: FundType,
61        thscode: &Thscode,
62        start: UnixMillis,
63        end: UnixMillis,
64    ) -> Result<Response<FundIndicatorHistoryData>, Error> {
65        let target = FundTarget::new(fund_type, thscode)?;
66        validate_history_range(start, end)?;
67        let mut query = target.query();
68        query.push(("start", start.to_string()));
69        query.push(("end", end.to_string()));
70        self.get(endpoints::FUND_INDICATORS_HISTORICAL, &query)
71            .await
72    }
73
74    /// 获取标准区间的最大回撤。
75    ///
76    /// # 示例
77    #[doc = concat!(
78        "```no_run\n",
79        include_str!("../../examples/fund_performance_drawdowns.rs"),
80        "\n```"
81    )]
82    pub async fn fund_performance_drawdowns(
83        &self,
84        fund_type: FundType,
85        thscode: &Thscode,
86    ) -> Result<Response<FundDrawdownsData>, Error> {
87        self.fund_detail(endpoints::FUND_DRAWDOWNS, fund_type, thscode)
88            .await
89    }
90}
91
92#[cfg(test)]
93mod tests {
94    use super::*;
95    use crate::ApiKey;
96
97    #[tokio::test]
98    async fn historical_indicators_keeps_range_validation_on_its_call_edge() {
99        let client = Client::builder(ApiKey::new("test-api-key").unwrap())
100            .base_url("http://127.0.0.1:9")
101            .build()
102            .unwrap();
103        let fund = Thscode::new("025480.OF").unwrap();
104
105        let error = client
106            .fund_performance_indicators_historical(
107                FundType::Otc,
108                &fund,
109                UnixMillis::new(1_577_836_800_000).unwrap(),
110                UnixMillis::new(1_735_776_000_000).unwrap(),
111            )
112            .await
113            .unwrap_err();
114
115        assert!(matches!(error, Error::InvalidInput(_)));
116    }
117}