Skip to main content

financial_api/client/
configuration.rs

1use std::env;
2use std::time::Duration;
3
4use reqwest::header::{HeaderMap, HeaderName};
5
6use super::{ApiKey, Client, ClientBuilder};
7use crate::{Error, NaturalDate, ValidationError};
8
9const DEFAULT_BASE_URL: &str = "https://fuyao.aicubes.cn/";
10const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
11const API_KEY_HEADER: HeaderName = HeaderName::from_static("x-api-key");
12
13impl ClientBuilder {
14    /// 覆盖 API 根地址,主要用于私有部署和测试。
15    #[must_use]
16    pub fn base_url(mut self, base_url: impl Into<String>) -> Self {
17        self.base_url = base_url.into();
18        self
19    }
20
21    /// 设置完整请求的超时时间。
22    #[must_use]
23    pub const fn timeout(mut self, timeout: Duration) -> Self {
24        self.timeout = timeout;
25        self
26    }
27
28    /// 覆盖相对日期校验使用的上海自然日。
29    ///
30    /// 适用于确定性测试和历史请求重放。
31    #[must_use]
32    pub const fn reference_date(mut self, date: NaturalDate) -> Self {
33        self.reference_date = Some(date);
34        self
35    }
36
37    /// 校验配置并构造可复用客户端。
38    pub fn build(self) -> Result<Client, Error> {
39        let mut base_url = reqwest::Url::parse(&self.base_url).map_err(|_| {
40            ValidationError::new("base_url", "must be a valid absolute hierarchical URL")
41        })?;
42        if base_url.cannot_be_a_base()
43            || base_url.query().is_some()
44            || base_url.fragment().is_some()
45        {
46            return Err(ValidationError::new(
47                "base_url",
48                "must be an absolute hierarchical URL without query or fragment",
49            )
50            .into());
51        }
52        if !matches!(base_url.scheme(), "http" | "https") {
53            return Err(ValidationError::new("base_url", "scheme must be http or https").into());
54        }
55        if !base_url.username().is_empty() || base_url.password().is_some() {
56            return Err(
57                ValidationError::new("base_url", "must not contain userinfo credentials").into(),
58            );
59        }
60        if !base_url.path().ends_with('/') {
61            let path = format!("{}/", base_url.path());
62            base_url.set_path(&path);
63        }
64
65        let mut headers = HeaderMap::new();
66        headers.insert(API_KEY_HEADER, self.api_key.0);
67        let http = reqwest::Client::builder()
68            .default_headers(headers)
69            .timeout(self.timeout)
70            .redirect(reqwest::redirect::Policy::none())
71            .build()
72            .map_err(|source| Error::InvalidConfiguration { source })?;
73
74        Ok(Client {
75            http,
76            base_url,
77            reference_date: self.reference_date,
78        })
79    }
80}
81
82impl Client {
83    /// 使用显式 API Key 开始配置客户端。
84    #[must_use]
85    pub fn builder(api_key: ApiKey) -> ClientBuilder {
86        ClientBuilder {
87            api_key,
88            base_url: DEFAULT_BASE_URL.to_owned(),
89            timeout: DEFAULT_TIMEOUT,
90            reference_date: None,
91        }
92    }
93
94    /// 使用环境变量 `HITHINK_FINANCE_API_KEY` 构造客户端。
95    pub fn from_env() -> Result<Self, Error> {
96        let value = env::var("HITHINK_FINANCE_API_KEY").map_err(|_| Error::MissingApiKey)?;
97        Self::builder(ApiKey::new(value)?).build()
98    }
99}
100
101#[cfg(test)]
102mod tests {
103    use super::{ApiKey, Client};
104    use crate::Error;
105
106    #[test]
107    fn base_url_rejects_userinfo_credentials() {
108        let error = Client::builder(ApiKey::new("test-api-key").unwrap())
109            .base_url("https://user:secret@fuyao.aicubes.cn/")
110            .build()
111            .unwrap_err();
112
113        let Error::InvalidInput(error) = error else {
114            panic!("expected invalid base URL");
115        };
116        assert_eq!(error.field(), "base_url");
117    }
118}