Builder con stato nel tipo
Codifichi la validità nel sistema dei tipi.
Builder con stato nel tipo è una lezione Learn Rust Coding gratuita su CoddyKit. Questa è la lezione 3 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Learn Rust Coding, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Learn Rust Coding include 4 lezioni in totale.
Il problema dei builder semplici
Un builder normale consente di chiamare build() in qualsiasi momento, anche prima di impostare i campi obbligatori. I dati mancanti emergono quindi come un panic a runtime o un Err.
I builder con stato tipizzato spostano questo controllo in fase di compilazione: dimenticare un passaggio obbligatorio impedisce semplicemente la compilazione.
Codificare lo stato nei tipi
Il trucco consiste nel rendere il builder generico rispetto a tipi marker che rappresentano i passaggi completati. Quando imposta ogni campo, cambia il tipo del builder.
Il metodo build() diventa disponibile solo quando ogni marker obbligatorio raggiunge lo stato "set".
struct Missing;
struct Set;Un builder generico rispetto ai marker
Fornisca i parametri di tipo del builder per lo stato di ogni campo obbligatorio. PhantomData trasporta il marcatore senza memorizzare dati reali.
use std::marker::PhantomData;
struct ReqBuilder<H, U> {
url: Option<String>,
method: Option<String>,
_state: PhantomData<(H, U)>,
}Lo stato iniziale
Il costruttore restituisce un builder in cui ogni marcatore obbligatorio è Missing. A questo punto non esiste alcun build(), quindi il sistema dei tipi sa che l'oggetto è incompleto.
impl ReqBuilder<Missing, Missing> {
fn new() -> Self {
ReqBuilder { url: None, method: None, _state: PhantomData }
}
}Transizione di un marcatore
Un setter consuma il builder precedente e ne restituisce uno nuovo con il marcatore di quel campo impostato su Set. L'altro marcatore viene preservato mantenendo generico il relativo parametro di tipo.
impl<U> ReqBuilder<Missing, U> {
fn url(self, url: &str) -> ReqBuilder<Set, U> {
ReqBuilder { url: Some(url.to_string()),
method: self.method, _state: PhantomData }
}
}La seconda transizione
L'impostazione del metodo funziona allo stesso modo: il secondo marcatore passa da Missing a Set, mentre il primo rimane invariato.
impl<H> ReqBuilder<H, Missing> {
fn method(self, m: &str) -> ReqBuilder<H, Set> {
ReqBuilder { url: self.url,
method: Some(m.to_string()), _state: PhantomData }
}
}build() solo quando tutto è impostato
È fondamentale che build() sia implementato solo per ReqBuilder<Set, Set>. Qualsiasi altro stato semplicemente non dispone di questo metodo, quindi la chiamata non viene compilata.
All'interno, le chiamate a unwrap non possono mai causare un panic, perché il tipo dimostra che entrambi i campi sono presenti.
struct Request { url: String, method: String }
impl ReqBuilder<Set, Set> {
fn build(self) -> Request {
Request { url: self.url.unwrap(), method: self.method.unwrap() }
}
}Unire tutti gli elementi
Una catena corretta viene compilata senza problemi, perché ogni chiamata avvicina il builder a ReqBuilder<Set, Set>, dove esiste build().
fn demo() -> Request {
ReqBuilder::new()
.url("https://example.com")
.method("GET")
.build()
}L'errore di compilazione che si desidera
Se si salta un passaggio obbligatorio, il compilatore rifiuta il codice. La chiamata a build() su ReqBuilder<Set, Missing> segnala "no method named build", rilevando l'omissione prima ancora dell'esecuzione del programma.
// ReqBuilder::new().url("x").build();
// error: no method named `build` found for
// ReqBuilder<Set, Missing>Una versione eseguibile autonoma
Questo programma minimale usa un solo campo obbligatorio per mostrare l'intera transizione dall'inizio alla fine. Viene compilato e stampa il valore costruito.
use std::marker::PhantomData;
struct Missing; struct Set;
struct B<N> { name: Option<String>, _s: PhantomData<N> }
impl B<Missing> {
fn new() -> Self { B { name: None, _s: PhantomData } }
fn name(self, n: &str) -> B<Set> {
B { name: Some(n.to_string()), _s: PhantomData }
}
}
impl B<Set> {
fn build(self) -> String { self.name.unwrap() }
}
fn main() {
let v = B::new().name("prod").build();
println!("built: {}", v);
}Costi e compromessi
I builder basati sullo stato dei tipi offrono garanzie in fase di compilazione senza alcun overhead a runtime, poiché i marcatori vengono eliminati. Il prezzo da pagare consiste in una maggiore complessità dei tipi e in blocchi impl combinatori man mano che aumentano i campi obbligatori.
Riservi questo pattern alle API in cui una costruzione incompleta deve essere impossibile per progettazione.
Verifica rapida
Individui ciò che garantisce effettivamente la completezza in un builder basato sullo stato dei tipi.
Riepilogo
I builder basati sullo stato dei tipi codificano ogni passaggio obbligatorio come parametro di tipo marcatore, trasportato da PhantomData. I setter consumano il builder e restituiscono un nuovo tipo con un marcatore impostato su Set.
Poiché build() è implementato solo per lo stato completamente Set, dimenticare un passaggio provoca un errore di compilazione, non un panic a runtime, senza alcun costo a runtime.
Domande Frequenti
La lezione «Builder con stato nel tipo» è gratuita?
Sì — il testo completo di «Builder con stato nel tipo» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Learn Rust Coding, passa a CoddyKit PRO. Il corso Learn Rust Coding include 4 lezioni in totale.
Cosa imparerò in «Builder con stato nel tipo»?
Codifichi la validità nel sistema dei tipi. Eserciti Learn Rust Coding con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare Learn Rust Coding?
Non è richiesta alcuna esperienza precedente. Learn Rust Coding su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 3 di 4.
Quanto tempo richiede la lezione «Builder con stato nel tipo»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione Learn Rust Coding?
Sì. Ogni lezione Learn Rust Coding include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Il pattern Builder
- Il pattern Newtype
- Builder con stato nel tipo
- Ergonomia di Deref e dei wrapper