Проектирование библиотек в Rust: Data-Oriented API, разделение lib/main и бебаггинг (Bebugging)

 1// Шаг 1: Проектирование чистой библиотеки (src/lib.rs) без побочных эффектов
 2
 3#[derive(Debug, PartialEq)]
 4pub struct TelemetryReport {
 5    pub service_name: String,
 6    pub cpu_usage_pct: f64,
 7    pub active_connections: usize,
 8}
 9
10pub struct TelemetryAggregator {
11    service_name: String,
12}
13
14impl TelemetryAggregator {
15    pub fn new(service_name: impl Into<String>) -> Self {
16        Self {
17            service_name: service_name.into(),
18        }
19    }
20
21    // Главный принцип библиотеки: функция ВОЗВРАЩАЕТ структуру данных, а не выводит её в stdout через println!
22    pub fn generate_report(&self, cpu_raw: u64, connections: usize) -> TelemetryReport {
23        let cpu_usage_pct = (cpu_raw as f64) / 100.0;
24        TelemetryReport {
25            service_name: self.service_name.clone(),
26            cpu_usage_pct,
27            active_connections: connections,
28        }
29    }
30}
31
32fn main() {
33    let aggregator = TelemetryAggregator::new("auth-service");
34    let report = aggregator.generate_report(4550, 120);
35    println!("Библиотечный модуль сгенерировал данные: {report:?}");
36}
37

 1// Шаг 2: Точка входа приложения (src/main.rs) отвечает за отображение
 2
 3// ?hidden:start
 4#[derive(Debug, PartialEq)]
 5pub struct TelemetryReport {
 6    pub service_name: String,
 7    pub cpu_usage_pct: f64,
 8    pub active_connections: usize,
 9}
10
11pub struct TelemetryAggregator {
12    service_name: String,
13}
14
15impl TelemetryAggregator {
16    pub fn new(service_name: impl Into<String>) -> Self {
17        Self {
18            service_name: service_name.into(),
19        }
20    }
21
22    pub fn generate_report(&self, cpu_raw: u64, connections: usize) -> TelemetryReport {
23        TelemetryReport {
24            service_name: self.service_name.clone(),
25            cpu_usage_pct: (cpu_raw as f64) / 100.0,
26            active_connections: connections,
27        }
28    }
29}
30// ?hidden:end
31
32fn render_report_to_terminal(report: &TelemetryReport) {
33    println!("=== ТЕЛЕМЕТРИЯ СЕРВИСА: {} ===", report.service_name);
34    println!("Загрузка CPU: {:.2}%", report.cpu_usage_pct);
35    println!("Активных соединений: {}", report.active_connections);
36}
37
38fn main() {
39    // В src/main.rs логика вызова вынесена отдельно:
40    let aggregator = TelemetryAggregator::new("payment-gateway");
41    let report = aggregator.generate_report(8230, 450);
42
43    // Только main() принимает решение, КАК отобразить данные пользователю:
44    render_report_to_terminal(&report);
45}
46

 1// Шаг 1: Информативные утверждения в тесте с контекстными сообщениями
 2
 3pub fn calculate_health_index(load: f64, errors: usize) -> f64 {
 4    if load > 100.0 {
 5        return 0.0;
 6    }
 7    let error_penalty = (errors as f64) * 2.5;
 8    (100.0 - load - error_penalty).max(0.0)
 9}
10
11fn main() {
12    let index = calculate_health_index(20.0, 2);
13    println!("Вычисленный индекс здоровья системы: {index}");
14}
15
16#[cfg(test)]
17mod tests {
18    use super::*;
19
20    #[test]
21    fn health_index_calculates_correctly_under_normal_load() {
22        let load = 20.0;
23        let errors = 2;
24        let want = 75.0; // 100 - 20 - 5.0
25        let got = calculate_health_index(load, errors);
26
27        // Информативное сообщение с подробными данными о несовпадении:
28        assert_eq!(
29            got, want,
30            "Индекс здоровья рассчитан неверно для load={load}, errors={errors}: want '{want}', got '{got}'"
31        );
32    }
33}
34

 1// Шаг 2: Техника Bebugging и самодокументируемые тесты (cargo-testdox)
 2
 3// В рамках техники Bebugging разработчик намеренно вносит ошибку в формулу
 4// для проверки того, что тесты действительно падают с понятным отчетом:
 5pub fn calculate_discount_price(original_price: f64, discount_pct: f64) -> f64 {
 6    // Намеренный баг для Bebugging: умножение вместо вычитания скидки
 7    // original_price * (1.0 - discount_pct / 100.0)
 8    original_price // ОШИБКА: вернет исходную цену без скидки!
 9}
10
11fn main() {
12    let price = calculate_discount_price(200.0, 10.0);
13    println!("Итоговая цена: {price}");
14}
15
16#[cfg(test)]
17mod bebugging_tests {
18    use super::*;
19
20    // Именование функций в стиле самодокументируемых предложений для cargo-testdox:
21    #[test]
22    fn discount_price_applies_percentage_deduction_properly() {
23        let price = 200.0;
24        let discount = 10.0;
25        let want = 180.0;
26        let got = calculate_discount_price(price, discount);
27
28        assert_eq!(
29            got, want,
30            "Bebugging check: test successfully caught the error! want '{want}', got '{got}'"
31        );
32    }
33}
34