Skip to main content

financial_api/
meta.rs

1use serde::Serialize;
2
3use crate::endpoints;
4use crate::{AssetType, Client, Error, Exchange, Response, SearchQuery, TickerData};
5
6/// 用于标的搜索和跨市场消歧的参数。
7#[derive(Debug, Clone, Serialize)]
8pub struct TickerSearchRequest {
9    q: SearchQuery,
10    #[serde(skip_serializing_if = "Option::is_none")]
11    exchange: Option<Exchange>,
12    #[serde(skip_serializing_if = "Option::is_none")]
13    asset_type: Option<String>,
14    limit: u8,
15}
16
17impl TickerSearchRequest {
18    #[must_use]
19    pub const fn new(q: SearchQuery) -> Self {
20        Self {
21            q,
22            exchange: None,
23            asset_type: None,
24            limit: 10,
25        }
26    }
27
28    #[must_use]
29    pub const fn exchange(mut self, exchange: Exchange) -> Self {
30        self.exchange = Some(exchange);
31        self
32    }
33
34    #[must_use]
35    pub fn asset_types(mut self, asset_types: impl IntoIterator<Item = AssetType>) -> Self {
36        self.asset_type = join_asset_types(asset_types);
37        self
38    }
39
40    pub fn limit(mut self, limit: u8) -> Result<Self, crate::ValidationError> {
41        if !(1..=50).contains(&limit) {
42            return Err(crate::ValidationError::new(
43                "limit",
44                "must be in the range 1..=50",
45            ));
46        }
47        self.limit = limit;
48        Ok(self)
49    }
50}
51
52impl Client {
53    /// 按完整标的代码、纯代码或名称搜索标的。
54    ///
55    /// # 示例
56    #[doc = concat!(
57        "```no_run\n",
58        include_str!("../examples/tickers_search.rs"),
59        "\n```"
60    )]
61    pub async fn tickers_search(
62        &self,
63        request: &TickerSearchRequest,
64    ) -> Result<Response<TickerData>, Error> {
65        self.get(endpoints::TICKERS_SEARCH, request).await
66    }
67}
68
69#[cfg(test)]
70mod tests {
71    use super::{TickerListRequest, TickerSearchRequest};
72    use crate::SearchQuery;
73
74    #[test]
75    fn request_builders_enforce_documented_page_bounds() {
76        let search = || TickerSearchRequest::new(SearchQuery::new("600519").unwrap());
77        assert!(search().limit(0).is_err());
78        assert!(search().limit(1).is_ok());
79        assert!(search().limit(50).is_ok());
80        assert!(search().limit(51).is_err());
81
82        assert!(TickerListRequest::new().page(0, 0).is_err());
83        assert!(TickerListRequest::new().page(1, 0).is_ok());
84        assert!(TickerListRequest::new().page(10_000, u32::MAX).is_ok());
85        assert!(TickerListRequest::new().page(10_001, 0).is_err());
86    }
87}
88
89/// 用于浏览标的代码表的参数。
90#[derive(Debug, Clone, Serialize)]
91pub struct TickerListRequest {
92    #[serde(skip_serializing_if = "Option::is_none")]
93    asset_type: Option<String>,
94    limit: u16,
95    offset: u32,
96}
97
98impl TickerListRequest {
99    #[must_use]
100    pub const fn new() -> Self {
101        Self {
102            asset_type: None,
103            limit: 1_000,
104            offset: 0,
105        }
106    }
107
108    #[must_use]
109    pub fn asset_types(mut self, asset_types: impl IntoIterator<Item = AssetType>) -> Self {
110        self.asset_type = join_asset_types(asset_types);
111        self
112    }
113
114    pub fn page(mut self, limit: u16, offset: u32) -> Result<Self, crate::ValidationError> {
115        if limit == 0 || limit > 10_000 {
116            return Err(crate::ValidationError::new(
117                "limit",
118                "must be in the range 1..=10000",
119            ));
120        }
121        self.limit = limit;
122        self.offset = offset;
123        Ok(self)
124    }
125}
126
127fn join_asset_types(asset_types: impl IntoIterator<Item = AssetType>) -> Option<String> {
128    let mut values = Vec::new();
129    for asset_type in asset_types {
130        let value = asset_type.as_str();
131        if !values.contains(&value) {
132            values.push(value);
133        }
134    }
135    (!values.is_empty()).then(|| values.join(","))
136}
137
138impl Default for TickerListRequest {
139    fn default() -> Self {
140        Self::new()
141    }
142}
143
144impl Client {
145    /// 分页浏览规范化的标的代码表。
146    ///
147    /// # 示例
148    #[doc = concat!(
149        "```no_run\n",
150        include_str!("../examples/tickers_list.rs"),
151        "\n```"
152    )]
153    pub async fn tickers_list(
154        &self,
155        request: &TickerListRequest,
156    ) -> Result<Response<TickerData>, Error> {
157        self.get(endpoints::TICKERS_LIST, request).await
158    }
159}