Skip to main content

financial_api/
meta.rs

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