1. Что это и зачем нужна

Библиотека config (crate config в экосистеме Rust) — это мощный и гибкий инструмент для управления конфигурацией приложений. Она предоставляет единый интерфейс для загрузки настроек из различных источников: файлов (JSON, YAML, TOML, INI, HJSON), переменных окружения, аргументов командной строки и даже удалённых источников. Основная задача библиотеки — абстрагировать процесс чтения и объединения конфигураций, позволяя разработчику сосредоточиться на бизнес-логике, а не на парсинге форматов.

Зачем это нужно в реальных проектах? Современные приложения редко имеют один источник конфигурации. Типичный сценарий: базовые настройки хранятся в файле config.toml, чувствительные данные (пароли, API-ключи) подтягиваются из переменных окружения, а параметры для конкретного запуска передаются через аргументы командной строки. config позволяет объединить все эти источники в единое дерево настроек с чётким приоритетом (например, переменные окружения переопределяют файловые значения). Без такой библиотеки разработчику пришлось бы вручную писать код для каждого источника, обрабатывать ошибки парсинга и следить за порядком переопределения.

Ключевые преимущества config: полная типобезопасность (настройки десериализуются в структуры Rust), поддержка вложенных конфигураций, автоматическое отслеживание изменений файлов (watch), и расширяемость за счёт собственных источников данных. Библиотека широко используется в production-проектах, таких как веб-серверы, CLI-утилиты и микросервисы.

2. Установка

Для добавления библиотеки config в проект Rust необходимо использовать менеджер пакетов Cargo. Выполните в терминале в корневой директории вашего проекта:

cargo add config

Если вы предпочитаете ручное редактирование Cargo.toml, добавьте в секцию [dependencies]:

[dependencies]
config = "0.14"

Также вам понадобится крейт для сериализации/десериализации. Рекомендуется serde с derive-макросом:

cargo add serde --features derive

Для работы с конкретными форматами файлов необходимо добавить соответствующие feature-флаги. Например, для поддержки TOML, YAML и JSON:

cargo add config --features yaml,json,toml

Полный список доступных форматов: ini, json, toml, yaml, hjson. Если вы планируете использовать только один формат, укажите только его — это уменьшит время компиляции.

3. Быстрый старт — минимальный рабочий пример

Создайте файл Settings.toml в корне проекта:

# Settings.toml
[server]
host = "127.0.0.1"
port = 8080

[database]
url = "postgres://user:pass@localhost/db"
pool_size = 10

Теперь напишем код для чтения этой конфигурации:

use config::{Config, File, FileFormat};
use serde::Deserialize;
use std::env;

#[derive(Debug, Deserialize)]
struct ServerConfig {
    host: String,
    port: u16,
}

#[derive(Debug, Deserialize)]
struct DatabaseConfig {
    url: String,
    pool_size: u32,
}

#[derive(Debug, Deserialize)]
struct AppConfig {
    server: ServerConfig,
    database: DatabaseConfig,
}

fn main() -> Result<(), config::ConfigError> {
    // Создаём билдер конфигурации
    let builder = Config::builder()
        // Добавляем файл как источник
        .add_source(File::new("Settings", FileFormat::Toml))
        // Добавляем переменные окружения с префиксом APP
        .add_source(
            config::Environment::with_prefix("APP")
                .prefix_separator("_")
                .separator("_"),
        );

    // Собираем конфигурацию
    let config: Config = builder.build()?;

    // Десериализуем в нашу структуру
    let app_config: AppConfig = config.try_deserialize()?;

    println!("Конфигурация загружена: {:?}", app_config);
    println!("Сервер запущен на {}:{}", app_config.server.host, app_config.server.port);

    Ok(())
}

Запустите программу командой cargo run. Вы должны увидеть вывод с загруженными настройками. Чтобы проверить работу переменных окружения, выполните:

APP_SERVER_PORT=9090 cargo run

Порт изменится на 9090, так как переменные окружения имеют более высокий приоритет.

4. Основные методы и функции

Рассмотрим ключевые методы библиотеки config. Все примеры предполагают, что у вас есть структура AppConfig из предыдущего раздела.

4.1. Config::builder()

Сигнатура: pub fn builder() -> ConfigBuilder<Config, DefaultState>

Описание: Создаёт новый билдер для конфигурации. Это отправная точка для настройки источников данных.

let builder = Config::builder();

4.2. ConfigBuilder::add_source()

Сигнатура: pub fn add_source<S>(self, source: S) -> ConfigBuilder<Config, state> where S: Source + 'static

Описание: Добавляет источник данных (файл, переменные окружения и т.д.) в цепочку конфигурации. Источники обрабатываются в порядке добавления.

use config::{File, FileFormat};

let builder = Config::builder()
    .add_source(File::new("config", FileFormat::Yaml))
    .add_source(config::Environment::default());

4.3. ConfigBuilder::build()

Сигнатура: pub fn build(self) -> Result<Config, ConfigError>

Описание: Завершает сборку конфигурации, объединяя все источники в единое дерево значений. Возвращает Config или ошибку, если какой-либо источник не удалось прочитать.

let config = Config::builder()
    .add_source(File::new("Settings", FileFormat::Toml))
    .build()?;

4.4. Config::get()

Сигнатура: pub fn get<T: DeserializeOwned>(&self, key: &str) -> Result<T, ConfigError>

Описание: Извлекает значение по ключу (с поддержкой точечной нотации для вложенных полей) и десериализует его в указанный тип.

let port: u16 = config.get("server.port")?;
println!("Порт сервера: {}", port);

// Можно получать вложенные структуры
let db_url: String = config.get("database.url")?;

4.5. Config::try_deserialize()

Сигнатура: pub fn try_deserialize<'de, T: Deserialize<'de>>(&'de self) -> Result<T, ConfigError>

Описание: Десериализует всю конфигурацию в заданную структуру. Это предпочтительный способ, так как обеспечивает полную типобезопасность.

#[derive(Debug, Deserialize)]
struct AppConfig {
    debug: bool,
    database: DatabaseConfig,
}

let app_config: AppConfig = config.try_deserialize()?;
println!("Режим отладки: {}", app_config.debug);

4.6. Config::set_default()

Сигнатура: pub fn set_default<S: Into<String>, T: Into<Value>>(self, key: S, value: T) -> ConfigBuilder<Config, state>

Описание: Устанавливает значение по умолчанию для указанного ключа. Если значение не найдено в других источниках, будет использовано это значение.

let config = Config::builder()
    .set_default("server.port", 8080)?
    .set_default("debug", false)?
    .add_source(File::new("Settings", FileFormat::Toml))
    .build()?;

4.7. Config::set_override()

Сигнатура: pub fn set_override<S: Into<String>, T: Into<Value>>(self, key: S, value: T) -> ConfigBuilder<Config, state>

Описание: Принудительно устанавливает значение для ключа, игнорируя все другие источники. Полезно для тестирования или фиксации критических параметров.

let config = Config::builder()
    .add_source(File::new("Settings", FileFormat::Toml))
    .set_override("server.port", 3000)?
    .build()?;
// Значение port будет 3000, даже если в файле указано другое

4.8. File::new() и FileFormat

Сигнатура: pub fn new(name: &str, format: FileFormat) -> File

Описание: Создаёт источник-файл с указанным именем (без расширения) и форматом. Библиотека автоматически ищет файл с соответствующим расширением.

use config::{File, FileFormat};

// Поиск config.yaml или config.yml
let yaml_source = File::new("config", FileFormat::Yaml);

// Поиск settings.json
let json_source = File::new("settings", FileFormat::Json);

// Поиск app.toml
let toml_source = File::new("app", FileFormat::Toml);

4.9. Environment::with_prefix()

Сигнатура: pub fn with_prefix(prefix: &str) -> Environment

Описание: Создаёт источник из переменных окружения, которые начинаются с указанного префикса. Позволяет изолировать переменные конкретного приложения.

use config::Environment;

// Будут читаться только переменные, начинающиеся с MYAPP_
let env_source = Environment::with_prefix("MYAPP")
    .prefix_separator("_")
    .separator("__"); // Двойной подчёркивание для вложенности

// Пример: MYAPP_SERVER__PORT = 9090 установит server.port = 9090

4.10. Config::refresh()

Сигнатура: pub fn refresh(&mut self) -> Result<(), ConfigError>

Описание: Перезагружает конфигурацию из всех источников. Полезно для реализации "горячей" перезагрузки настроек без перезапуска приложения.

use std::{thread, time::Duration};

let mut config = Config::builder()
    .add_source(File::new("Settings", FileFormat::Toml))
    .build()?;

loop {
    // Проверяем изменения каждые 5 секунд
    thread::sleep(Duration::from_secs(5));
    if let Err(e) = config.refresh() {
        eprintln!("Ошибка перезагрузки: {}", e);
    } else {
        let port: u16 = config.get("server.port").unwrap_or(8080);
        println!("Текущий порт: {}", port);
    }
}

5. Реальный практический пример

Разработаем конфигурацию для веб-сервера с поддержкой нескольких источников, логированием и валидацией. Создадим файл production.yaml:

# production.yaml
server:
  host: "0.0.0.0"
  port: 8080
  workers: 4
  timeout_secs: 30

logging:
  level: "info"
  format: "json"
  output: "stdout"

database:
  host: "localhost"
  port: 5432
  name: "app_db"
  max_connections: 20

features:
  enable_metrics: true
  enable_tracing: false

Теперь напишем полный код приложения:

use config::{Config, ConfigError, Environment, File, FileFormat};
use serde::Deserialize;
use std::net::SocketAddr;

// Структуры для конфигурации
#[derive(Debug, Deserialize)]
struct ServerConfig {
    host: String,
    port: u16,
    workers: usize,
    timeout_secs: u64,
}

#[derive(Debug, Deserialize)]
struct LoggingConfig {
    level: String,
    format: String,
    output: String,
}

#[derive(Debug, Deserialize)]
struct DatabaseConfig {
    host: String,
    port: u16,
    name: String,
    #[serde(alias = "max_connections")]
    max_conn: u32,
}

#[derive(Debug, Deserialize)]
struct FeaturesConfig {
    enable_metrics: bool,
    enable_tracing: bool,
}

#[derive(Debug, Deserialize)]
struct AppConfig {
    server: ServerConfig,
    logging: LoggingConfig,
    database: DatabaseConfig,
    features: FeaturesConfig,
}

impl App