Skip to main content

yang_base/
config.rs

1//! 引擎配置(I4):从环境变量分层加载,遵循 12-factor。
2//!
3//! 本模块提供 [`EngineConfig::from_env`]:从 `YANG_` 前缀环境变量读取数据库/Redis
4//! 连接串与连接池参数,解析失败一律走 checked 错误([`BaseError::ConfigError`]),
5//! **不** panic(遵守禁新增生产 panic 约定)。
6//!
7//! 设计取轻量替代(纯 `std::env`,不引入 figment/config/dotenv 重依赖)。未来如需
8//! 「默认 < TOML 文件 < 环境变量」三层覆盖,可在可选 `config` feature 后增量补 TOML 层,
9//! 本类型的 `from_env` 即最高优先级层。
10//!
11//! # 识别的环境变量
12//!
13//! | 变量 | 含义 | 默认 |
14//! |------|------|------|
15//! | `YANG_MYSQL_URL` | MySQL 连接串 | 无(缺失则 `mysql_url` 为 `None`) |
16//! | `YANG_DATABASE_URL` | MySQL 连接串(deprecated,请改用 `YANG_MYSQL_URL`) | 同上 |
17//! | `YANG_REDIS_URL` | Redis 连接串 | 无 |
18//! | `YANG_DB_MAX_CONNECTIONS` | 最大连接数 | 由 `DatabaseConfig::default` 决定 |
19//! | `YANG_DB_MIN_CONNECTIONS` | 最小(保活)连接数 | 同上 |
20//! | `YANG_DB_CONNECT_TIMEOUT` | 连接超时(秒) | 同上 |
21//! | `YANG_DB_IDLE_TIMEOUT` | 空闲超时(秒) | 同上 |
22//! | `YANG_DB_MAX_LIFETIME` | 连接最大存活(秒,0/缺失=不限制) | 不限制 |
23//! | `YANG_DB_TEST_BEFORE_ACQUIRE` | 借出前探活(true/false/1/0) | false |
24//! | `YANG_DB_ENABLE_LOGGING` | SQL 日志(true/false/1/0) | false |
25
26use crate::error::BaseError;
27use std::env;
28
29/// 引擎级聚合配置,从环境变量加载(I4)。
30#[derive(Debug, Clone, Default)]
31#[non_exhaustive]
32pub struct EngineConfig {
33    /// MySQL 连接串(`YANG_MYSQL_URL`,兼容 deprecated `YANG_DATABASE_URL`,缺失为 `None`)。
34    pub mysql_url: Option<String>,
35    /// Redis 连接串(`YANG_REDIS_URL`,缺失为 `None`)。
36    pub redis_url: Option<String>,
37    /// 数据库连接池配置(由 `YANG_DB_*` 覆盖 `DatabaseConfig::default`)。
38    #[cfg(feature = "mysql")]
39    pub database: yang_db::DatabaseConfig,
40}
41
42/// 读取一个环境变量并按 `T` 解析;缺失返回 `Ok(None)`,存在但解析失败返回 ConfigError。
43#[cfg(feature = "mysql")]
44fn parse_env<T: std::str::FromStr>(key: &str) -> Result<Option<T>, BaseError>
45where
46    T::Err: std::fmt::Display,
47{
48    match env::var(key) {
49        Ok(raw) => raw
50            .trim()
51            .parse::<T>()
52            .map(Some)
53            .map_err(|e| BaseError::ConfigError(format!("环境变量 {key} 解析失败: {e}"))),
54        Err(env::VarError::NotPresent) => Ok(None),
55        Err(env::VarError::NotUnicode(_)) => Err(BaseError::ConfigError(format!(
56            "环境变量 {key} 含非法 UTF-8"
57        ))),
58    }
59}
60
61/// 解析布尔环境变量:接受 `true/false/1/0`(大小写不敏感),其余报 ConfigError。
62#[cfg(feature = "mysql")]
63fn parse_bool_env(key: &str) -> Result<Option<bool>, BaseError> {
64    match env::var(key) {
65        Ok(raw) => match raw.trim().to_ascii_lowercase().as_str() {
66            "true" | "1" => Ok(Some(true)),
67            "false" | "0" => Ok(Some(false)),
68            other => Err(BaseError::ConfigError(format!(
69                "环境变量 {key} 期望 true/false/1/0,实得 {other:?}"
70            ))),
71        },
72        Err(env::VarError::NotPresent) => Ok(None),
73        Err(env::VarError::NotUnicode(_)) => Err(BaseError::ConfigError(format!(
74            "环境变量 {key} 含非法 UTF-8"
75        ))),
76    }
77}
78
79impl EngineConfig {
80    /// 从 `YANG_` 前缀环境变量加载配置。
81    ///
82    /// 缺失的变量回退到默认值;存在但解析失败返回 [`BaseError::ConfigError`]。
83    pub fn from_env() -> Result<Self, BaseError> {
84        // 优先 YANG_MYSQL_URL;兼容 deprecated YANG_DATABASE_URL
85        let mysql_url = match env::var("YANG_MYSQL_URL") {
86            Ok(v) => Some(v),
87            Err(env::VarError::NotPresent) => match env::var("YANG_DATABASE_URL") {
88                Ok(v) => {
89                    eprintln!(
90                        "[yang-base] 环境变量 YANG_DATABASE_URL 已 deprecated,请改用 YANG_MYSQL_URL"
91                    );
92                    Some(v)
93                }
94                Err(env::VarError::NotPresent) => None,
95                Err(env::VarError::NotUnicode(_)) => {
96                    return Err(BaseError::ConfigError(
97                        "环境变量 YANG_DATABASE_URL 含非法 UTF-8".to_string(),
98                    ))
99                }
100            },
101            Err(env::VarError::NotUnicode(_)) => {
102                return Err(BaseError::ConfigError(
103                    "环境变量 YANG_MYSQL_URL 含非法 UTF-8".to_string(),
104                ))
105            }
106        };
107        let redis_url = match env::var("YANG_REDIS_URL") {
108            Ok(v) => Some(v),
109            Err(env::VarError::NotPresent) => None,
110            Err(env::VarError::NotUnicode(_)) => {
111                return Err(BaseError::ConfigError(
112                    "环境变量 YANG_REDIS_URL 含非法 UTF-8".to_string(),
113                ))
114            }
115        };
116
117        #[cfg(feature = "mysql")]
118        let database = {
119            let mut cfg = yang_db::DatabaseConfig::default();
120            if let Some(v) = parse_env::<u32>("YANG_DB_MAX_CONNECTIONS")? {
121                cfg.max_connections = v;
122            }
123            if let Some(v) = parse_env::<u32>("YANG_DB_MIN_CONNECTIONS")? {
124                cfg.min_connections = v;
125            }
126            if let Some(v) = parse_env::<u64>("YANG_DB_CONNECT_TIMEOUT")? {
127                cfg.connect_timeout = v;
128            }
129            if let Some(v) = parse_env::<u64>("YANG_DB_IDLE_TIMEOUT")? {
130                cfg.idle_timeout = v;
131            }
132            if let Some(v) = parse_env::<u64>("YANG_DB_MAX_LIFETIME")? {
133                // 0 视为不限制(与 None 同义),其余设具体秒数
134                cfg.max_lifetime = if v == 0 { None } else { Some(v) };
135            }
136            if let Some(v) = parse_bool_env("YANG_DB_TEST_BEFORE_ACQUIRE")? {
137                cfg.test_before_acquire = v;
138            }
139            if let Some(v) = parse_bool_env("YANG_DB_ENABLE_LOGGING")? {
140                cfg.enable_logging = v;
141            }
142            cfg
143        };
144
145        Ok(Self {
146            mysql_url,
147            redis_url,
148            #[cfg(feature = "mysql")]
149            database,
150        })
151    }
152}
153
154#[cfg(all(test, feature = "mysql"))]
155mod tests {
156    use super::*;
157
158    #[test]
159    fn parse_bool_env_accepts_forms() {
160        // 使用唯一 key 避免与其它测试串扰
161        std::env::set_var("YANG_TEST_BOOL_X", "TRUE");
162        assert_eq!(parse_bool_env("YANG_TEST_BOOL_X").unwrap(), Some(true));
163        std::env::set_var("YANG_TEST_BOOL_X", "0");
164        assert_eq!(parse_bool_env("YANG_TEST_BOOL_X").unwrap(), Some(false));
165        std::env::set_var("YANG_TEST_BOOL_X", "maybe");
166        assert!(parse_bool_env("YANG_TEST_BOOL_X").is_err());
167        std::env::remove_var("YANG_TEST_BOOL_X");
168        assert_eq!(parse_bool_env("YANG_TEST_BOOL_X").unwrap(), None);
169    }
170
171    #[test]
172    fn parse_env_rejects_bad_number() {
173        std::env::set_var("YANG_TEST_NUM_X", "not_a_number");
174        let r = parse_env::<u32>("YANG_TEST_NUM_X");
175        assert!(matches!(r, Err(BaseError::ConfigError(_))));
176        std::env::remove_var("YANG_TEST_NUM_X");
177        assert_eq!(parse_env::<u32>("YANG_TEST_NUM_X").unwrap(), None);
178    }
179}