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, ValidationError,
5};
6
7use super::{fund_target_query, 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: impl TryInto<Thscode, Error: Into<ValidationError>>,
22        range: Option<FundRange>,
23        nav_type: FundNavType,
24    ) -> Result<Response<FundNavData>, Error> {
25        let mut query = fund_target_query(fund_type, thscode)?;
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: impl TryInto<Thscode, Error: Into<ValidationError>>,
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: impl TryInto<Thscode, Error: Into<ValidationError>>,
62        start: impl TryInto<UnixMillis, Error: Into<ValidationError>>,
63        end: impl TryInto<UnixMillis, Error: Into<ValidationError>>,
64    ) -> Result<Response<FundIndicatorHistoryData>, Error> {
65        let mut query = fund_target_query(fund_type, thscode)?;
66        let start: UnixMillis = start.try_into().map_err(Into::into)?;
67        let end: UnixMillis = end.try_into().map_err(Into::into)?;
68        validate_history_range(start, end)?;
69        query.push(("start", start.to_string()));
70        query.push(("end", end.to_string()));
71        self.get(endpoints::FUND_INDICATORS_HISTORICAL, &query)
72            .await
73    }
74
75    /// 获取标准区间的最大回撤。
76    ///
77    /// # 示例
78    #[doc = concat!(
79        "```no_run\n",
80        include_str!("../../examples/fund_performance_drawdowns.rs"),
81        "\n```"
82    )]
83    pub async fn fund_performance_drawdowns(
84        &self,
85        fund_type: FundType,
86        thscode: impl TryInto<Thscode, Error: Into<ValidationError>>,
87    ) -> Result<Response<FundDrawdownsData>, Error> {
88        self.fund_detail(endpoints::FUND_DRAWDOWNS, fund_type, thscode)
89            .await
90    }
91}
92
93#[cfg(test)]
94mod tests {
95    use super::*;
96    use crate::ApiKey;
97
98    #[tokio::test]
99    async fn historical_indicators_keeps_range_validation_on_its_call_edge() {
100        let client = Client::builder(ApiKey::new("test-api-key").unwrap())
101            .base_url("http://127.0.0.1:9")
102            .build()
103            .unwrap();
104        let error = client
105            .fund_performance_indicators_historical(
106                FundType::Otc,
107                "025480.OF",
108                1_577_836_800_000,
109                1_735_776_000_000,
110            )
111            .await
112            .unwrap_err();
113
114        assert!(matches!(error, Error::InvalidInput(_)));
115    }
116}