Skip to main content

yang_base/
datasource.rs

1//! 逻辑数据源标识。
2//!
3//! 模块只声明逻辑数据源名(如 `default`、`project_a_pg`),具体后端、URL 与连接池
4//! 由部署配置绑定;这样同一模块可以在 MySQL 与 PostgreSQL 之间切换,而不需要改
5//! 声明代码。
6
7use crate::error::BaseError;
8use std::fmt;
9use std::str::FromStr;
10use std::sync::Arc;
11
12/// 逻辑数据源名称。
13///
14/// 允许小写 ASCII 字母开头,后接小写字母、数字或下划线,长度 1..=32。
15/// `default` 是保留名,表示应用的默认数据源。
16#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
17pub struct DatasourceId(Arc<str>);
18
19impl DatasourceId {
20    /// 默认数据源的保留名。
21    pub const DEFAULT_NAME: &'static str = "default";
22
23    /// 校验并创建逻辑数据源名。
24    pub fn new(value: impl Into<String>) -> Result<Self, BaseError> {
25        let value = value.into();
26        let bytes = value.as_bytes();
27        let valid = !bytes.is_empty()
28            && bytes.len() <= 32
29            && bytes[0].is_ascii_lowercase()
30            && bytes
31                .iter()
32                .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || *byte == b'_');
33        if !valid {
34            return Err(BaseError::ConfigError(format!(
35                "非法数据源名称 {value:?}:必须是小写字母开头、仅含小写字母/数字/下划线,长度 1..=32"
36            )));
37        }
38        Ok(Self(Arc::from(value.as_str())))
39    }
40
41    /// 返回 `default` 数据源名。
42    pub fn default_source() -> Self {
43        Self(Arc::from(Self::DEFAULT_NAME))
44    }
45
46    /// 是否为默认数据源。
47    pub fn is_default(&self) -> bool {
48        self.as_str() == Self::DEFAULT_NAME
49    }
50
51    /// 返回名称字符串。
52    pub fn as_str(&self) -> &str {
53        &self.0
54    }
55}
56
57impl fmt::Display for DatasourceId {
58    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
59        formatter.write_str(self.as_str())
60    }
61}
62
63impl Default for DatasourceId {
64    fn default() -> Self {
65        Self::default_source()
66    }
67}
68
69impl FromStr for DatasourceId {
70    type Err = BaseError;
71
72    fn from_str(value: &str) -> Result<Self, Self::Err> {
73        Self::new(value)
74    }
75}
76
77#[cfg(test)]
78mod tests {
79    use super::*;
80
81    #[test]
82    fn accepts_lowercase_names_and_default() {
83        for name in ["default", "pg_main", "project_a_pg", "a1"] {
84            DatasourceId::new(name).expect("合法数据源名应通过");
85        }
86        assert!(DatasourceId::default_source().is_default());
87    }
88
89    #[test]
90    fn rejects_invalid_names() {
91        for name in ["", "Default", "1pg", "pg-main", "pg main", "数据源"] {
92            assert!(
93                DatasourceId::new(name).is_err(),
94                "非法数据源名 {name:?} 应被拒绝"
95            );
96        }
97        assert!(DatasourceId::new("a".repeat(33)).is_err());
98    }
99}