rust-config-tree käyttöopas

English | 中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Svenska | Suomi | Nederlands

Tama on suomenkielinen rust-config-tree-kayttoopas.

Aloita sivuilta Johdanto, Pika-aloitus tai ajettavista Esimerkeista.

Johdanto

English | 中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Svenska | Suomi | Nederlands

rust-config-tree tarjoaa uudelleenkaytettavan konfiguraatiopuun latauksen ja CLI-apurit Rust-sovelluksille, jotka kayttavat kerrostettuja konfiguraatiotiedostoja.

Crate on suunniteltu pienen vastuunjaon ymparille:

• confique omistaa skeemamaaritykset, koodin oletusarvot, validoinnin ja konfiguraatiomallien luonnin.
• figment omistaa runtime-latauksen ja runtime-lahdemetadatan.
• rust-config-tree omistaa rekursiivisen include-lapikaynnin, include-polkujen ratkaisun, .env-latauksen, mallikohteiden tunnistuksen ja uudelleenkaytettavat clap-komennot.

Crate on hyodyllinen, kun sovellus haluaa luonnollisen konfiguraatiotiedostojen asettelun, kuten taman:

include:
  - config/server.yaml
  - config/database.yaml

log:
  level: info

Jokainen sisallytetty tiedosto voi kayttaa samaa skeemamuotoa, ja suhteelliset include-polut ratkaistaan ne maaritelleesta tiedostosta. Lopullinen konfiguraatio on silti tavallinen confique-skeema-arvo.

Paatoiminnot

• Rekursiivinen include-lapikaynti syklien tunnistuksella.
• Suhteelliset include-polut ratkaistaan maarittelevasta tiedostosta.
• .env ladataan ennen ymparistoprovidereiden arviointia.
• Skeemassa maaritellyt ymparistomuuttujat ilman erotinmerkkijakoa.
• Figment-metadata runtime-lahteen seurantaan.
• TRACE-tason lahteenseurannan tapahtumat tracing-kirjaston kautta.
• Draft 7 JSON Schema -luonti editorien taydennysta ja skeeman perustarkistuksia varten.
• Kentta-arvojen validointi sovelluskoodissa #[config(validate = Self::validate)]-attribuutilla, suoritettuna load_config- tai config-validate-polussa.
• YAML-, TOML-, JSON- ja JSON5-mallien luonti.
• TOML #:schema -direktiivit, YAML Language Server -skeemamallirivit ja JSON/JSON5 $schema -kentat luoduille malleille.
• Opt-in YAML-mallien jakaminen x-tree-split-merkityille osioille.
• Sisaanrakennetut clap-alikomennot konfiguraatiomalleille, JSON Schemalle ja shell-taydennyksille.
• Alemman tason puu-API kutsujille, jotka eivat kayta confique-kirjastoa.

Julkiset aloituspisteet

Kayta naita APIeja useimmissa sovelluksissa:

• load_config::<S>(path) lataa lopullisen skeeman.
• load_config_with_figment::<S>(path) lataa skeeman ja palauttaa lahteen seurantaan kaytetyn Figment-graafin.
• write_config_templates::<S>(config_path, output_path) kirjoittaa juurimallin ja rekursiivisesti loydetyt lapsimallit.
• write_config_schemas::<S>(output_path) kirjoittaa juuri- ja osio-Draft 7 JSON Schema -skeemat.
• handle_config_command::<Cli, S>(command, config_path) kasittelee sisaanrakennetut clap-konfiguraatiokomennot.

Kayta load_config_tree-funktiota, kun tarvitset lapikayntiprimitiivin ilman confique-kirjastoa.

Pika-aloitus

English | 中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Svenska | Suomi | Nederlands

Lisaa crate ja sovelluksen kayttamat skeema/runtime-kirjastot:

[dependencies]
rust-config-tree = "0.1"
confique = { version = "0.4", features = ["yaml", "toml", "json5"] }
figment = { version = "0.10", features = ["yaml", "toml", "json", "env"] }
schemars = { version = "1", features = ["derive"] }
serde = { version = "1", features = ["derive"] }
clap = { version = "4", features = ["derive"] }

Maarittele confique-skeema ja toteuta ConfigSchema juurityypille:

#![allow(unused)]
fn main() {
use std::path::PathBuf;

use confique::Config;
use rust_config_tree::ConfigSchema;

#[derive(Debug, Config)]
struct AppConfig {
    #[config(default = [])]
    include: Vec<PathBuf>,

    #[config(nested)]
    server: ServerConfig,
}

#[derive(Debug, Config)]
struct ServerConfig {
    #[config(default = "127.0.0.1")]
    #[config(env = "APP_SERVER_BIND")]
    bind: String,

    #[config(default = 8080)]
    #[config(env = "APP_SERVER_PORT")]
    port: u16,
}

impl ConfigSchema for AppConfig {
    fn include_paths(layer: &<Self as Config>::Layer) -> Vec<PathBuf> {
        layer.include.clone().unwrap_or_default()
    }
}
}

Lataa konfiguraatio:

#![allow(unused)]
fn main() {
use rust_config_tree::load_config;

let config = load_config::<AppConfig>("config.yaml")?;
println!("{config:#?}");
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Kayta juuritiedostoa, jossa on rekursiiviset includet:

# config.yaml
include:
  - config/server.yaml

# config/server.yaml
server:
  bind: 0.0.0.0
  port: 3000

load_config-funktion oletusetusijajarjestys on:

environment variables
  > config files, with later merged files overriding earlier files
    > confique code defaults

Kun includet ladataan korkean tason APIlla, juuritiedostolla on korkein tiedostoprioriteetti. Sisallytetyt tiedostot antavat matalamman prioriteetin arvoja ja voivat toimia oletuksina tai osiokohtaisina tiedostoina.

Komentoriviargumentit ovat sovelluskohtaisia, joten load_config ei lue niita automaattisesti. Yhdista CLI-ohitukset build_config_figment-funktion jalkeen, kun sovelluksella on konfiguraation ohituslippuja:

CLI-lippujen nimet valitsee sovellus. Ne eivat ole automaattisesti a.b.c-konfiguraatiopolkuja. Suosi tavallisia clap-lippuja, kuten --server-port, ja mapita ne sisakkaiseen ohitusrakenteeseen. Sisakkainen serialisoitu muoto maarittaa ohitettavan konfiguraatioavaimen.

Vain sovelluksen CliOverrides-providerissa esitetyt arvot ohittavat konfiguraation. Tama sopii parametreille, joita muutetaan usein yhden ajon ajaksi ilman konfiguraatiotiedoston muokkausta. Pysyvien arvojen tulisi pysya konfiguraatiotiedostoissa.

#![allow(unused)]
fn main() {
use figment::providers::Serialized;
use serde::Serialize;
use rust_config_tree::{build_config_figment, load_config_from_figment};

#[derive(Debug, Serialize)]
struct CliOverrides {
    #[serde(skip_serializing_if = "Option::is_none")]
    server: Option<CliServerOverrides>,
}

#[derive(Debug, Serialize)]
struct CliServerOverrides {
    #[serde(skip_serializing_if = "Option::is_none")]
    port: Option<u16>,
}

let cli_overrides = CliOverrides {
    server: Some(CliServerOverrides { port: Some(9000) }),
};

let figment = build_config_figment::<AppConfig>("config.yaml")?
    .merge(Serialized::defaults(cli_overrides));

let config = load_config_from_figment::<AppConfig>(&figment)?;
let _ = config;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Kun CLI-ohitukset yhdistetaan talla tavalla, koko etusijajarjestys on:

command-line overrides
  > environment variables
    > config files
      > confique code defaults

Konfiguraatioskeema

English | 中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Svenska | Suomi | Nederlands

Sovellusskeemat ovat tavallisia confique-konfiguraatiotyyppeja. Juuriskeeman taytyy toteuttaa ConfigSchema, jotta rust-config-tree voi loytaa rekursiiviset includet valiaikaisesta confique-kerroksesta.

#![allow(unused)]
fn main() {
use std::path::PathBuf;

use confique::Config;
use schemars::JsonSchema;
use rust_config_tree::ConfigSchema;

#[derive(Debug, Config, JsonSchema)]
struct AppConfig {
    #[config(default = [])]
    include: Vec<PathBuf>,

    #[config(nested)]
    #[schemars(extend("x-tree-split" = true))]
    database: DatabaseConfig,
}

#[derive(Debug, Config, JsonSchema)]
struct DatabaseConfig {
    #[config(env = "APP_DATABASE_URL")]
    url: String,

    #[config(default = 16)]
    #[config(env = "APP_DATABASE_POOL_SIZE")]
    pool_size: u32,
}

impl ConfigSchema for AppConfig {
    fn include_paths(layer: &<Self as Config>::Layer) -> Vec<PathBuf> {
        layer.include.clone().unwrap_or_default()
    }
}
}

Include-kentta

Include-kentalla voi olla mika tahansa nimi. rust-config-tree tuntee sen vain ConfigSchema::include_paths-funktion kautta.

Kentalla tulisi tavallisesti olla tyhja oletusarvo:

#![allow(unused)]
fn main() {
#[config(default = [])]
include: Vec<PathBuf>,
}

Lataaja saa jokaisesta tiedostosta osittain ladatun kerroksen. Sen avulla se voi loytaa lapsikonfiguraatiotiedostot ennen lopullisen skeeman yhdistamista ja validointia.

Sisakkaiset osiot

Kayta #[config(nested)]-attribuuttia rakenteisille osioille. Sisakkaisia osioita kaytetaan aina runtime-lataukseen. Lisaa #[schemars(extend("x-tree-split" = true))], kun nested-kentta tulee luoda myos omaksi *.yaml-malliksi ja <section>.schema.json-skeemaksi:

#![allow(unused)]
fn main() {
#[derive(Debug, Config, JsonSchema)]
struct AppConfig {
    #[config(nested)]
    #[schemars(extend("x-tree-split" = true))]
    server: ServerConfig,
}
}

Luonnollinen YAML-muoto on:

server:
  bind: 127.0.0.1
  port: 8080

Vain ymparistomuuttujista tulevat kentat

Merkitse lehtikentta #[schemars(extend("x-env-only" = true))], kun arvon tulee tulla vain ymparistomuuttujasta eika sen pidä nakya luoduissa konfiguraatiotiedostoissa. Luodut YAML-mallit ja JSON Schema -skeemat jattavat env-only-kentat pois, ja niiden takia tyhjiksi jaavat ylaobjektit poistetaan.

#![allow(unused)]
fn main() {
#[config(env = "APP_SECRET")]
#[schemars(extend("x-env-only" = true))]
secret: String,
}

Kentta-arvojen validointi

Luodut *.schema.json-tiedostot ovat vain IDE-taydennysta ja editorin perustarkistuksia varten. Ne eivat paata, onko konkreettinen kentan arvo sovellukselle kelvollinen.

Kentta-arvojen validointi toteutetaan koodissa #[config(validate = Self::validate)]-attribuutilla. Validaattori suoritetaan, kun lopullinen konfiguraatio ladataan load_config-funktiolla tai tarkistetaan config-validate-komennolla.

Malliosioiden ohitukset

Kun mallilahteella ei ole includeja, crate voi johtaa lapsimallitiedostot x-tree-split-merkityista sisakkaisista skeemaosioista. Oletuspolku ylatasolla on <section>.yaml.

Ohita polku template_path_for_section-funktiolla:

#![allow(unused)]
fn main() {
impl ConfigSchema for AppConfig {
    fn include_paths(layer: &<Self as Config>::Layer) -> Vec<PathBuf> {
        layer.include.clone().unwrap_or_default()
    }

    fn template_path_for_section(section_path: &[&str]) -> Option<PathBuf> {
        match section_path {
            ["database"] => Some(PathBuf::from("examples/database.yaml")),
            _ => None,
        }
    }
}
}

Runtime-lataus

English | 中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Svenska | Suomi | Nederlands

Runtime-lataus on tarkoituksella jaettu Figmentin ja confiquen valille:

figment:
  runtime file loading
  runtime environment loading
  runtime source metadata

confique:
  schema metadata
  defaults
  validation
  config templates

Paa-API on:

#![allow(unused)]
fn main() {
use rust_config_tree::load_config;

let config = load_config::<AppConfig>("config.yaml")?;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Kayta load_config_with_figment-funktiota, kun sovellus tarvitsee lahdemetadatan:

#![allow(unused)]
fn main() {
use rust_config_tree::load_config_with_figment;

let (config, figment) = load_config_with_figment::<AppConfig>("config.yaml")?;
let _ = (config, figment);
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Latausvaiheet

Korkean tason lataaja tekee nama vaiheet:

1. Ratkaise juurikonfiguraatiopolku leksikaalisesti.
2. Lataa ensimmainen .env-tiedosto, joka loytyy kulkemalla ylospain juurikonfiguraation hakemistosta.
3. Lataa jokainen konfiguraatiotiedosto osittaisena kerroksena includejen loytamiseksi.
4. Rakenna Figment-graafi loydetyista konfiguraatiotiedostoista.
5. Yhdista ConfiqueEnvProvider korkeammalla prioriteetilla kuin tiedostot.
6. Yhdista valinnaisesti sovelluskohtaiset CLI-ohitukset.
7. Poimi confique-kerros Figmentista.
8. Kayta confique-koodin oletusarvoja.
9. Validoi ja rakenna lopullinen skeema.

load_config ja load_config_with_figment suorittavat vaiheet 1-5 ja 7-9. Vaihe 6 on sovelluskohtainen, koska tama crate ei voi paatella, miten CLI-lippu mapataan skeemakenttaan.

Tiedostomuodot

Runtime-tiedostoprovider valitaan konfiguraatiopolun paatteesta:

• .yaml ja .yml kayttavat YAMLia.
• .toml kayttaa TOMLia.
• .json ja .json5 kayttavat JSONia.
• tuntemattomat tai puuttuvat paatteet kayttavat YAMLia.

Mallien luonti kayttaa yha confiquen mallirenderoijia YAML-, TOML- ja JSON5-yhteensopivalle tulosteelle.

Include-prioriteetti

Korkean tason lataaja yhdistaa tiedostoproviderit niin, etta sisallytetyt tiedostot ovat matalammalla prioriteetilla kuin ne sisallyttanyt tiedosto. Juurikonfiguraatiotiedostolla on korkein tiedostoprioriteetti.

Ymparistomuuttujilla on korkeampi prioriteetti kuin kaikilla konfiguraatiotiedostoilla. confique-oletuksia kaytetaan vain arvoille, joita runtime-providerit eivat anna.

Kun CLI-ohitukset yhdistetaan build_config_figment-funktion jalkeen, koko etusijajarjestys on:

command-line overrides
  > environment variables
    > config files
      > confique code defaults

Komentorivisyntaksia ei maarittele rust-config-tree. Lippu kuten --server-port voi ohittaa server.port-avaimen, jos sovellus mapittaa parsitun arvon sisakkaiseen serialisoituun provideriin. Pisteellinen --server.port- tai a.b.c-syntaksi on olemassa vain, jos sovellus toteuttaa sen.

Tama tarkoittaa, etta CLI-prioriteetti koskee vain avaimia, jotka ovat mukana sovelluksen ohitusproviderissa. Kayta sita operatiivisille arvoille, joita muutetaan usein yhden ajon ajaksi. Jata pysyva konfiguraatio tiedostoihin.

#![allow(unused)]
fn main() {
use figment::providers::Serialized;
use serde::Serialize;
use rust_config_tree::{build_config_figment, load_config_from_figment};

#[derive(Debug, Serialize)]
struct CliOverrides {
    #[serde(skip_serializing_if = "Option::is_none")]
    server: Option<CliServerOverrides>,
}

#[derive(Debug, Serialize)]
struct CliServerOverrides {
    #[serde(skip_serializing_if = "Option::is_none")]
    port: Option<u16>,
}

let cli_overrides = CliOverrides {
    server: Some(CliServerOverrides { port: Some(9000) }),
};

let figment = build_config_figment::<AppConfig>("config.yaml")?
    .merge(Serialized::defaults(cli_overrides));

let config = load_config_from_figment::<AppConfig>(&figment)?;
let _ = config;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Ymparistomuuttujat

English | 中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Svenska | Suomi | Nederlands

Ymparistomuuttujien nimet maaritellaan skeemassa confique-attribuuteilla:

#![allow(unused)]
fn main() {
#[derive(Debug, Config)]
struct DatabaseConfig {
    #[config(env = "APP_DATABASE_URL")]
    url: String,

    #[config(default = 16)]
    #[config(env = "APP_DATABASE_POOL_SIZE")]
    pool_size: u32,
}
}

rust-config-tree lukee nama nimet confique::Config::META-metadatasta ja rakentaa Figment-providerin, joka mapittaa jokaisen ymparistomuuttujan tarkkaan kenttapolkuunsa.

Ala kayta erotinmerkkeihin perustuvaa Figmentin ymparistomappausta taman craten kanssa:

#![allow(unused)]
fn main() {
// Do not use this pattern for rust-config-tree schemas.
Env::prefixed("APP_").split("_")
Env::prefixed("APP_").split("__")
}

split("_") tulkitsee alaviivat sisakkaisten avainten erottimiksi. Silloin APP_DATABASE_POOL_SIZE muuttuu poluksi kuten database.pool.size, joka on ristiriidassa Rust-kenttanimien kuten pool_size kanssa.

ConfiqueEnvProvider-providerilla mappaus on eksplisiittinen:

APP_DATABASE_POOL_SIZE -> database.pool_size

Yksittaiset alaviivat pysyvat osana ymparistomuuttujan nimea. Figment ei arvaa sisakkaisyyssaantoa.

Dotenv-lataus

Ennen runtime-providereiden arviointia lataaja etsii .env-tiedostoa kulkemalla ylospain juurikonfiguraatiotiedoston hakemistosta.

Prosessin olemassa olevat ymparistomuuttujat sailyvat. .env-arvot tayttavat vain puuttuvat ymparistomuuttujat.

Esimerkki:

APP_SERVER_PORT=9000
APP_DATABASE_POOL_SIZE=64

Nama muuttujat ohittavat konfiguraatiotiedoston arvot, kun skeema maarittelee vastaavat #[config(env = "...")]-attribuutit.

Arvojen jasantaminen

Siltaprovider antaa Figmentin jasantaa ymparistoarvot. Se ei kutsu confique-kirjaston parse_env-hookeja. Pida monimutkaiset arvot konfiguraatiotiedostoissa, ellei Figmentin ymparistoarvosyntaksi sovi tyypille hyvin.

Lahteen seuranta

English | 中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Svenska | Suomi | Nederlands

Kayta load_config_with_figment-funktiota sailyttaaksesi runtime-latauksessa kaytetyn Figment-graafin:

#![allow(unused)]
fn main() {
use rust_config_tree::load_config_with_figment;

let (config, figment) = load_config_with_figment::<AppConfig>("config.yaml")?;
let _ = config;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Palautettu Figment-arvo voi vastata runtime-arvojen lahdekysymyksiin:

#![allow(unused)]
fn main() {
if let Some(metadata) = figment.find_metadata("database.pool_size") {
    let source = metadata.interpolate(
        &figment::Profile::Default,
        &["database", "pool_size"],
    );

    println!("database.pool_size came from {source}");
}
}

ConfiqueEnvProvider-providerin antamille arvoille interpolointi palauttaa skeemassa maaritellyn natiivin ymparistomuuttujan nimen:

database.pool_size came from APP_DATABASE_POOL_SIZE

TRACE-tapahtumat

Lataaja lahettaa lahteenseurannan tapahtumia tracing::trace!-kutsulla. Se tekee taman vain, kun TRACE on kaytossa:

#![allow(unused)]
fn main() {
use rust_config_tree::{load_config_with_figment, trace_config_sources};

let (config, figment) = load_config_with_figment::<AppConfig>("config.yaml")?;

// If the tracing subscriber is initialized after config loading, emit the
// same source events again after installing the subscriber.
trace_config_sources::<AppConfig>(&figment);
let _ = config;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Jokainen tapahtuma kayttaa kohdetta rust_config_tree::config ja sisaltaa:

• config_key: pisteellinen konfiguraatioavain.
• source: renderoitu lahdemetadata.

Arvoilla, jotka tulevat vain confique-oletuksista, ei ole Figmentin runtime-metadatan lahdetta. Ne raportoidaan muodossa confique default or unset optional field.

Mallien luonti

English | 中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Svenska | Suomi | Nederlands

Mallit luodaan samasta confique-skeemasta, jota kaytetaan runtimessa. confique renderoi varsinaisen mallisisallon, mukaan lukien doc-kommentit, oletusarvot, pakolliset kentat ja maaritellyt ymparistomuuttujien nimet.

Kayta write_config_templates-funktiota:

#![allow(unused)]
fn main() {
use rust_config_tree::write_config_templates;

write_config_templates::<AppConfig>("config.yaml", "config.example.yaml")?;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Luo Draft 7 JSON Schema -skeemat juurikonfiguraatiolle ja jaetuille sisakkaisille osioille:

#![allow(unused)]
fn main() {
use rust_config_tree::write_config_schemas;

write_config_schemas::<AppConfig>("schemas/myapp.schema.json")?;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Merkitse sisakkainen kentta #[schemars(extend("x-tree-split" = true))]- attribuutilla, kun se tulee luoda omana *.yaml-mallina ja omana <section>.schema.json-skeemana. Merkitsemattomat sisakkaiset kentat pysyvat emomallissa ja emoskeemassa.

Merkitse lehtikentta #[schemars(extend("x-env-only" = true))], kun arvon tulee tulla vain ymparistomuuttujista. Luodut mallit ja JSON Schema -skeemat jattavat env-only-kentat pois, ja niiden takia tyhjiksi jaavat ylaobjektit poistetaan.

Luodut skeemat jattavat required-rajoitteet pois. IDEt voivat silti tarjota taydennysta, mutta osittaiset tiedostot kuten log.yaml eivat ilmoita puuttuvista juurikentista. Juuriskeema taydentaa vain juuritiedostoon kuuluvat kentat; sisakkaisten osioiden kentat jatetaan siella pois ja taydennetaan niiden omilla osioskeemoilla. Paikalla olevat kentat voivat yha saada editorin perustarkistuksia, kuten luodun skeeman tukemat tyyppi-, enum- ja tuntemattomien ominaisuuksien tarkistukset. Luodut *.schema.json-tiedostot eivat paata, onko konkreettinen kentan arvo sovellukselle kelvollinen. Kentta-arvojen validointi toteutetaan koodissa #[config(validate = Self::validate)]-attribuutilla; load_config ja config-validate suorittavat sen runtime-validoinnin.

Sido nama skeemat luoduista TOML-, YAML-, JSON- ja JSON5-malleista:

#![allow(unused)]
fn main() {
use rust_config_tree::write_config_templates_with_schema;

write_config_templates_with_schema::<AppConfig>(
    "config.toml",
    "config.example.toml",
    "schemas/myapp.schema.json",
)?;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

TOML- ja YAML-juurimallit sitovat juuriskeeman eivatka taydenna jaettujen lapsiosioiden kenttia. Jaetut osio-YAML-mallit sitovat oman osioskeemansa. JSON- ja JSON5-mallit saavat juuritason $schema-kentan, jonka VS Code tunnistaa. VS Coden json.schemas on edelleen vaihtoehtoinen sidontatapa.

Tulostemuoto paatellaan tulostepolusta:

• .yaml ja .yml tuottavat YAMLia.
• .toml tuottaa TOMLia.
• .json ja .json5 tuottavat JSON5-yhteensopivia malleja.
• tuntemattomat tai puuttuvat paatteet tuottavat YAMLia.

Skeemasidonnat

Skeemapolulla schemas/myapp.schema.json luodut juurimallit kayttavat:

#:schema ./schemas/myapp.schema.json

# yaml-language-server: $schema=./schemas/myapp.schema.json

Luodut osiomallit sitovat osioskeemat:

# log.yaml
# yaml-language-server: $schema=./schemas/log.schema.json

Luodut JSON- ja JSON5-mallit kirjoittavat juuritason $schema-kentan, jonka VS Code tunnistaa. Editoriasetukset ovat edelleen valinnaisia:

{
  "json.schemas": [
    {
      "fileMatch": [
        "/config.json",
        "/config.*.json"
      ],
      "url": "./schemas/myapp.schema.json"
    }
  ]
}

Mallilahteen valinta

Mallien luonti valitsee lahdepuunsa tassa jarjestyksessa:

1. Olemassa oleva konfiguraatiopolku.
2. Olemassa oleva tulostemallipolku.
3. Tulostepolku uutena tyhjana mallipuuna.

Tama antaa projektille mahdollisuuden paivittaa malleja nykyisista konfiguraatiotiedostoista, paivittaa olemassa olevan mallijoukon tai luoda uuden mallijoukon pelkasta skeemasta.

Peilatut include-puut

Jos lahdetiedosto maarittelee includet, luodut mallit peilaavat nama include-polut tulostehakemiston alle.

# config.yaml
include:
  - server.yaml

config.example.yaml-tiedoston luonti kirjoittaa:

config.example.yaml
server.yaml

Suhteelliset include-kohteet peilataan tulostetiedoston emohakemiston alle. Absoluuttiset include-kohteet pysyvat absoluuttisina.

Opt-in-osioiden jakaminen

Kun lahdetiedostolla ei ole includeja, crate voi johtaa include-kohteet x-tree-split-merkityista sisakkaisista skeemaosioista. Skeemalle, jossa on merkitty server-osio, tyhja juurimallilahde voi tuottaa:

config.example.yaml
server.yaml

Juurimalli saa include-lohkon, ja server.yaml sisaltaa vain server-osion. Sisakkaiset osiot jaetaan rekursiivisesti vain, kun myos niilla kentilla on x-tree-split.

IDE-taydennykset

English | 中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Svenska | Suomi | Nederlands

Luotuja JSON Schema -skeemoja voi kayttaa TOML-, YAML-, JSON- ja JSON5-konfiguraatiotiedostoissa. Ne luodaan samasta Rust-tyypista, jota confique kayttaa:

#![allow(unused)]
fn main() {
use confique::Config;
use schemars::JsonSchema;

#[derive(Debug, Config, JsonSchema)]
struct AppConfig {
    #[config(nested)]
    #[schemars(extend("x-tree-split" = true))]
    server: ServerConfig,
}
}

Luo ne nain:

#![allow(unused)]
fn main() {
use rust_config_tree::write_config_schemas;

write_config_schemas::<AppConfig>("schemas/myapp.schema.json")?;
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Tama kirjoittaa juuriskeeman ja osioskeemat, kuten schemas/server.schema.json. Luodut skeemat jattavat required-rajoitteet pois, jotta taydennys toimii osittaisille konfiguraatiotiedostoille ilman puuttuvien kenttien diagnostiikkaa. Juuriskeema jattaa jaettujen osioiden ominaisuudet pois, joten lapsiosioiden taydennys on saatavilla vain tiedostoissa, jotka sitovat vastaavan osioskeeman. Merkitsemattomat sisakkaiset osiot pysyvat juuriskeemassa.

x-env-only-merkityt kentat jatetaan pois luoduista skeemoista, joten IDEt eivat ehdota salaisuuksia tai muita arvoja, joiden tulee tulla vain ymparistomuuttujista.

IDE-skeemat ovat taydennysta ja editorin perustarkistuksia varten, kuten luodun skeeman tukemat tyyppi-, enum- ja tuntemattomien ominaisuuksien tarkistukset. Ne eivat paata, onko konkreettinen kentan arvo sovellukselle kelvollinen. Kentta-arvojen validointi toteutetaan koodissa #[config(validate = Self::validate)]-attribuutilla ja suoritetaan load_config- tai config-validate-polussa. Pakolliset kentat ja lopullisen yhdistetyn konfiguraation validointi kayttavat myos naita runtime-polkuja.

TOML

TOML-tiedostojen tulisi sitoa skeema tiedoston alun #:schema-direktiivilla:

#:schema ./schemas/myapp.schema.json

[server]
bind = "0.0.0.0"
port = 3000

Ala kayta juuritason $schema = "..." -kenttaa TOMLissa. Siita tulee oikeaa konfiguraatiodataa ja se voi vaikuttaa runtime-deserialisointiin. write_config_templates_with_schema lisaa #:schema-direktiivin automaattisesti TOML-malleihin.

YAML

YAML-tiedostojen tulisi kayttaa YAML Language Server -mallirivia:

# yaml-language-server: $schema=./schemas/myapp.schema.json

server:
  bind: 0.0.0.0
  port: 3000

write_config_templates_with_schema lisaa taman mallirivin automaattisesti YAML-malleihin. Jaetut YAML-mallit sitovat osioskeemansa; esimerkiksi log.yaml sitoo skeeman ./schemas/log.schema.json.

JSON

JSON- ja JSON5-tiedostot voivat sitoa skeeman juuritason $schema-kentalla. write_config_templates_with_schema lisaa sen automaattisesti luotuihin JSON- ja JSON5-malleihin:

{
  "$schema": "./schemas/myapp.schema.json"
}

Editoriasetukset ovat edelleen hyodyllisia, jos projekti ei halua sidontaa tiedostoon:

{
  "json.schemas": [
    {
      "fileMatch": [
        "/config.json",
        "/config.*.json",
        "/deploy/*.json"
      ],
      "url": "./schemas/myapp.schema.json"
    }
  ]
}

YAML voidaan sitoa myos VS Code -asetuksilla:

{
  "yaml.schemas": {
    "./schemas/myapp.schema.json": [
      "config.yaml",
      "config.*.yaml",
      "deploy/*.yaml"
    ]
  }
}

Lopullinen asettelu on:

schemas/myapp.schema.json:
  Vain juuritiedoston kentat

schemas/server.schema.json:
  server-osion skeema

config.toml:
  #:schema ./schemas/myapp.schema.json

config.yaml:
  # yaml-language-server: $schema=./schemas/myapp.schema.json

server.yaml:
  # yaml-language-server: $schema=./schemas/server.schema.json

config.json:
  "$schema": "./schemas/myapp.schema.json"

Viitteet:

• Tombi JSON Schema
• Taplo directives
• YAML Language Server
• VS Code JSON

CLI-integraatio

English | 中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Svenska | Suomi | Nederlands

ConfigCommand tarjoaa uudelleenkaytettavat clap-alikomennot:

• config-template
• config-schema
• config-validate
• completions
• install-completions
• uninstall-completions

Nama sisaanrakennetut alikomennot ovat erillaan sovelluskohtaisista konfiguraation ohituslipuista. Yhdista konfiguraation ohitusliput Figment-providereina runtime-latauspolussa.

Konfiguraation ohitusliput pysyvat kayttavan sovelluksen CLI:n osana. Niiden nimien ei tarvitse vastata pisteellisia konfiguraatiopolkuja. Sovellus voi esimerkiksi jasantaa --server-port-lipun ja mapittaa sen sisakkaiseen server.port-konfiguraatioavaimeen. Vain liput, jotka sovellus mapittaa CliOverrides-rakenteeseen, vaikuttavat konfiguraatioarvoihin.

Litista se sovelluksen komentoenumiin:

1. Sailyta sovelluksen oma Parser-tyyppi.
2. Sailyta sovelluksen oma Subcommand-enum.
3. Lisaa kyseiseen enumiin #[command(flatten)] Config(ConfigCommand).
4. Clap laajentaa litistetyt ConfigCommand-variantit samalle komentotasolle kuin sovelluksen omat variantit.
5. Tasmaa Config(command)-variantti ja valita se handle_config_command-funktiolle.

use std::path::PathBuf;

use clap::{Parser, Subcommand};
use confique::Config;
use schemars::JsonSchema;
use rust_config_tree::{ConfigCommand, ConfigSchema, handle_config_command, load_config};

#[derive(Debug, Config, JsonSchema)]
struct AppConfig {
    #[config(default = [])]
    include: Vec<PathBuf>,
}

impl ConfigSchema for AppConfig {
    fn include_paths(layer: &<Self as Config>::Layer) -> Vec<PathBuf> {
        layer.include.clone().unwrap_or_default()
    }
}

#[derive(Debug, Parser)]
#[command(name = "demo")]
struct Cli {
    #[arg(long, default_value = "config.yaml")]
    config: PathBuf,

    #[command(subcommand)]
    command: Command,
}

#[derive(Debug, Subcommand)]
enum Command {
    Run,

    #[command(flatten)]
    Config(ConfigCommand),
}

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let cli = Cli::parse();

    match cli.command {
        Command::Run => {
            let config = load_config::<AppConfig>(&cli.config)?;
            println!("{config:#?}");
        }
        Command::Config(command) => {
            handle_config_command::<Cli, AppConfig>(command, &cli.config)?;
        }
    }

    Ok(())
}

Konfiguraatiomallit

demo config-template

Komento kirjoittaa mallit hakemistoon config/<root_config_name>/. Jos --output saa polun, vain tiedostonimi kaytetaan. Jos tulostetiedoston nimea ei anneta, komento kirjoittaa config/<root_config_name>/<root_config_name>.example.yaml. Lisaa --schema schemas/myapp.schema.json, jotta luodut TOML-, YAML-, JSON- ja JSON5-mallit sidotaan luotuihin JSON Schema -skeemoihin. Jaetut YAML-mallit sitovat vastaavan osioskeeman. JSON- ja JSON5-mallit saavat $schema-kentan, jonka VS Code tunnistaa. Komento kirjoittaa myos juuri- ja osioskeemat valittuun skeemapolkuun.

demo config-template --output app_config.example.toml --schema schemas/myapp.schema.json

Luo juuri- ja osio-JSON Schema -skeemat:

demo config-schema

Ilman --output-arvoa config-schema kirjoittaa juuriskeeman tiedostoon config/<root_config_name>/<root_config_name>.schema.json.

Validoi koko runtime-konfiguraatiopuu:

demo config-validate

Luodut editoriskeemat valttavat tarkoituksella required-kenttien diagnostiikkaa jaetuille tiedostoille. config-validate lataa includet, kayttaa oletusarvot ja ajaa lopullisen confique-validoinnin, mukaan lukien #[config(validate = Self::validate)]-attribuutilla maaritellyt validaattorit. Luodut *.schema.json-tiedostot ovat IDE-taydennysta ja editorin perustarkistuksia varten, eivat kentta-arvon kelvollisuuden arviointiin. Se tulostaa Configuration is ok, kun validointi onnistuu.

Shell-taydennykset

Tulosta taydennykset stdoutiin:

demo completions zsh

Asenna taydennykset:

demo install-completions zsh

Poista taydennykset:

demo uninstall-completions zsh

Asennin tukee Bashia, Elvishia, Fishiä, PowerShellia ja Zsh:ta. Se kirjoittaa taydennystiedoston kayttajan kotihakemiston alle ja paivittaa shellin kaynnistystiedoston niille shelleille, jotka sita vaativat.

Ennen olemassa olevan shellin kaynnistystiedoston, kuten ~/.zshrc, ~/.bashrc, Elvish rc -tiedoston tai PowerShell-profiilin muuttamista komento kirjoittaa varmuuskopion alkuperaisen tiedoston viereen:

<rc-file>.backup.by.<program-name>.<timestamp>

Esimerkit

English | 中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Svenska | Suomi | Nederlands

Repository sisaltaa ajettavat esimerkit konfiguraatiopuiden lataukseen, CLI-ohituksiin, sisaanrakennettuihin konfiguraatiokomentoihin, mallien luontiin ja alemman tason puu-APIin.

Lue repositorion esimerkki-indeksi:

• examples/README.md

Aja esimerkit repositorion juuresta:

cargo run --example basic_loading
cargo run --example cli_overrides -- --server-port 9000
cargo run --example config_commands -- config-template
cargo run --example config_commands -- config-schema
cargo run --example config_commands -- config-validate
cargo run --example generate_templates
cargo run --example tree_api

Puu-API

English | 中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Svenska | Suomi | Nederlands

Kayta alemman tason puu-APIa, kun sovellus ei kayta confique-kirjastoa tai kun se tarvitsee suoran paasan lapikaynnin tuloksiin.

#![allow(unused)]
fn main() {
use std::{
    fs,
    io,
    path::{Path, PathBuf},
};

use rust_config_tree::{ConfigSource, load_config_tree};

fn load_source(path: &Path) -> io::Result<ConfigSource<String>> {
    let content = fs::read_to_string(path)?;
    let includes = content
        .lines()
        .filter_map(|line| line.strip_prefix("include: "))
        .map(PathBuf::from)
        .collect();

    Ok(ConfigSource::new(content, includes))
}

let tree = load_config_tree("config.yaml", load_source)?;

for node in tree.nodes() {
    println!("{}", node.path().display());
}
Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
}

Lapikayntisaannot

Puulataaja:

• normalisoi lahdepolut leksikaalisesti;
• hylkaa tyhjat include-polut;
• ratkaisee suhteelliset includet ne maaritelleesta tiedostosta;
• sailyttaa absoluuttiset include-polut;
• tunnistaa rekursiiviset include-syklit;
• ohittaa tiedostot, jotka on jo ladattu toisen include-haaran kautta.

ConfigTreeOptions voi kaantaa saman tason includejen lapikayntijarjestyksen:

#![allow(unused)]
fn main() {
use rust_config_tree::{ConfigTreeOptions, IncludeOrder};

let options = ConfigTreeOptions::default().include_order(IncludeOrder::Reverse);
let _ = options;
}

Polkuapurit

Polkuapurit ovat vain leksikaalisia. Ne eivat ratkaise symbolisia linkkeja eivatka vaadi polkujen olemassaoloa:

• absolutize_lexical(path)
• normalize_lexical(path)
• resolve_include_path(parent_path, include_path)

GitHub Pages

English | 中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Svenska | Suomi | Nederlands

Tama repository julkaisee oppaan mdBookilla ja GitHub Pagesilla.

Jokainen kieliopas on itsenainen mdBook-projekti. Jokaisella kielella on oma SUMMARY.md, joten vasen sivupalkki sisaltaa vain nykyisen kielen sivut:

manual/
  en/
    book.toml
    SUMMARY.md
    introduction.md
    quick-start.md
    ...
  zh/
    book.toml
    SUMMARY.md
    introduction.md
    quick-start.md
    ...
  ja/
    book.toml
    SUMMARY.md
    introduction.md
    quick-start.md
    ...
  ko/
  fr/
  de/
  es/
  pt/
  sv/
  fi/
  nl/

Rakenna paikallisesti:

scripts/publish-pages.sh

Luotu sivusto kirjoitetaan hakemistoon:

target/mdbook

Julkaisun tyonkulku

.github/workflows/pages.yml-tyonkulku ajetaan pusheissa main-haaraan ja kasin kaynnistettyna. Se:

1. Checkouttaa repositorion.
2. Asentaa mdBookin.
3. Ajaa scripts/publish-pages.sh.
4. Lataa target/mdbook-hakemiston Pages-artefaktiksi.
5. Julkaisee artefaktin GitHub Pagesiin.

Julkaistu URL on:

https://developerworks.github.io/rust-config-tree/

Crate-julkaisu

Koko commit-, push-, Pages-julkaisu- ja crate-julkaisuvirralle:

scripts/release.sh --execute --message "Release 0.1.3"

Kayta crate-julkaisun apuria repositorion juuresta:

scripts/publish-crate.sh

Oletustila ajaa tarkistukset ja cargo publish --dry-run -komennon. Julkaise crates.io:hon tarkistusten onnistuttua. Jos nykyinen versio on jo olemassa crates.io:ssa, skripti kasvattaa patch-version automaattisesti:

scripts/publish-crate.sh --execute

Skriptin kaytto on tiivistetty tiedostossa scripts/README.md.