Sérialisation — serde

struct Utilisateur ──Serialize──► modèle de données serde ──serde_json──► {"nom":"Ada"}
                    ◄─Deserialize──                        ◄─────────────

[dependencies]
serde = { version = "1", features = ["derive"] }   # derive : active #[derive(Serialize, Deserialize)]
serde_json = "1"                                   # format JSON
toml = "0.8"                                       # format TOML (si besoin)

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Utilisateur {
    id: u32,
    nom: String,
    email: String,
    actif: bool,
    roles: Vec<String>,
}

struct Connexion;                         // pas de Serialize

// #[derive(Serialize)]
// struct Etat { c: Connexion }           // ERREUR : the trait `Serialize` is not implemented for `Connexion`

let u = Utilisateur {
    id: 1,
    nom: "Ada".into(),
    email: "[email protected]".into(),
    actif: true,
    roles: vec!["admin".into()],
};

let compact = serde_json::to_string(&u)?;          // {"id":1,"nom":"Ada",...}
let lisible = serde_json::to_string_pretty(&u)?;   // indenté
let octets: Vec<u8> = serde_json::to_vec(&u)?;
serde_json::to_writer(std::io::stdout(), &u)?;     // directement dans un flux, sans String intermédiaire

let texte = r#"{"id":2,"nom":"Linus","email":"[email protected]","actif":false,"roles":[]}"#;

// 1. Annoter la variable
let u: Utilisateur = serde_json::from_str(texte)?;

// 2. Turbofish
let u = serde_json::from_str::<Utilisateur>(texte)?;

// 3. Depuis des octets ou un lecteur
let u: Utilisateur = serde_json::from_slice(texte.as_bytes())?;
let f = std::fs::File::open("u.json")?;
let u: Utilisateur = serde_json::from_reader(std::io::BufReader::new(f))?;

Un champ manquant, en trop (selon les options, section 11), ou d'un mauvais type produit une erreur qui indique la ligne et la colonne : missing field \email` at line 1 column 30`.

use serde_json::{json, Value};

let v: Value = serde_json::from_str(r#"{"nom":"Ada","langages":["rust","c"],"age":36}"#)?;

let nom = v["nom"].as_str();                     // Some("Ada")
let premier = v["langages"][0].as_str();         // Some("rust")
let absent = &v["inexistant"];                   // Value::Null, pas de panique
let age = v.get("age").and_then(Value::as_u64);  // Some(36)

let construit = json!({
    "statut": "ok",
    "total": 3,
    "elements": [1, 2, 3],
});

let v: Value = serde_json::to_value(&u)?;            // struct -> Value
let u2: Utilisateur = serde_json::from_value(v)?;    // Value -> struct

#[derive(Debug, Deserialize)]
struct Config {
    serveur: Serveur,
    base: Base,
}

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

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

let texte = r#"
[serveur]
hote = "0.0.0.0"
port = 8080

[base]
url = "postgres://localhost/app"
connexions = 10
"#;

let c: Config = toml::from_str(texte)?;

Les tables TOML ([serveur]) correspondent aux structs imbriquées. La même struct se lirait depuis un JSON {"serveur": {...}, "base": {...}} sans modification.

#[derive(Deserialize)]
struct Recherche { q: String, page: Option<u32> }

let r: Recherche = serde_urlencoded::from_str("q=rust+web&page=2")?;

C'est le format des formulaires HTML et des paramètres d'URL. Les extracteurs Form<T> et Query<T> d'axum l'utilisent.

#[derive(Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]           // tous les champs : cree_le -> creeLe
struct Article {
    id: u32,
    cree_le: String,
    #[serde(rename = "titreArticle")]        // un champ précis
    titre: String,
}

Valeurs de rename_all : lowercase, UPPERCASE, camelCase, PascalCase, snake_case, SCREAMING_SNAKE_CASE, kebab-case, SCREAMING-KEBAB-CASE.

#[derive(Serialize, Deserialize)]
struct Produit {
    #[serde(rename(serialize = "price", deserialize = "prix"))]
    prix: f64,
}

#[derive(Deserialize)]
struct Contact {
    #[serde(alias = "mail", alias = "e-mail")]
    email: String,
}

À quoi ça sert : renommer un champ sans casser les anciens clients ou les anciens fichiers.

#[derive(Serialize, Deserialize)]
struct Session {
    utilisateur: String,
    #[serde(skip)]                           // ni écrit ni lu ; à la lecture : Default::default()
    cache: Vec<u8>,
    #[serde(skip_serializing)]               // lu mais jamais écrit
    mot_de_passe: String,
    #[serde(skip_deserializing)]             // écrit mais jamais lu
    calcule: u32,
}

#[derive(Serialize)]
struct Reponse {
    donnees: Vec<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    erreur: Option<String>,                  // absent du JSON si None, au lieu de "erreur": null
    #[serde(skip_serializing_if = "Vec::is_empty")]
    avertissements: Vec<String>,
}

#[derive(Deserialize)]
struct Options {
    #[serde(default)]                        // absent -> Default::default() (0, "", false, vec vide)
    verbeux: bool,
    #[serde(default = "port_defaut")]        // absent -> valeur d'une fonction
    port: u16,
}

fn port_defaut() -> u16 { 8080 }

#[derive(Deserialize, Default)]
#[serde(default)]                            // sur la struct : tout champ absent prend la valeur de Default
struct Reglages { taille: u32, theme: String }

#[derive(Serialize, Deserialize)]
struct Pagination { page: u32, par_page: u32 }

#[derive(Serialize, Deserialize)]
struct ListeArticles {
    articles: Vec<String>,
    #[serde(flatten)]
    pagination: Pagination,                  // {"articles":[..],"page":1,"par_page":20}
}

#[derive(Deserialize)]
struct AvecExtras {
    nom: String,
    #[serde(flatten)]
    autres: std::collections::HashMap<String, serde_json::Value>,   // récupère tous les champs inconnus
}

#[derive(Deserialize, Debug)]
struct Profil {
    nom: String,
    bio: Option<String>,
}

#[derive(Serialize, Deserialize)]
enum Evenement {
    Connexion { utilisateur: String },
    Achat { montant: u32 },
    Deconnexion,
}

// {"Connexion":{"utilisateur":"ada"}}
// {"Achat":{"montant":30}}
// "Deconnexion"

#[derive(Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
enum Evenement2 {
    Connexion { utilisateur: String },
    Achat { montant: u32 },
    Deconnexion,
}
// {"type":"connexion","utilisateur":"ada"}
// {"type":"deconnexion"}

La forme la plus courante dans les API web. Ne marche pas avec des variantes tuple contenant un simple nombre ou texte (Achat(u32)).

#[derive(Serialize, Deserialize)]
#[serde(tag = "type", content = "data")]
enum Message {
    Texte(String),
    Nombre(i64),
}
// {"type":"Texte","data":"bonjour"}

Fonctionne avec tous les types de variantes.

#[derive(Serialize, Deserialize, Debug)]
#[serde(untagged)]
enum Identifiant {
    Numero(u64),
    Nom(String),
}
// 42      -> Numero(42)
// "ada"   -> Nom("ada")

serde essaie chaque variante dans l'ordre et garde la première qui correspond. Pratique pour accepter plusieurs formes, mais les erreurs sont peu parlantes (« data did not match any variant ») et l'ordre compte.

#[derive(Serialize, Deserialize, Debug, PartialEq)]
#[serde(rename_all = "lowercase")]
enum Statut { Brouillon, Publie, Archive }
// "brouillon", "publie", "archive"

mod secondes {
    use serde::{Deserialize, Deserializer, Serializer};
    use std::time::Duration;

    pub fn serialize<S: Serializer>(d: &Duration, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_u64(d.as_secs())
    }

    pub fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Duration, D::Error> {
        Ok(Duration::from_secs(u64::deserialize(d)?))
    }
}

#[derive(Serialize, Deserialize)]
struct Cache {
    #[serde(with = "secondes")]
    duree: std::time::Duration,           // {"duree": 300}
}

#[derive(Deserialize)]
struct Inscription {
    #[serde(deserialize_with = "minuscules")]
    email: String,
}

fn minuscules<'de, D: serde::Deserializer<'de>>(d: D) -> Result<String, D::Error> {
    Ok(String::deserialize(d)?.trim().to_lowercase())
}

#[derive(Deserialize, Debug)]
#[serde(try_from = "String")]
struct Email(String);

impl TryFrom<String> for Email {
    type Error = String;
    fn try_from(s: String) -> Result<Self, Self::Error> {
        if s.contains('@') { Ok(Email(s)) } else { Err(format!("email invalide : {s}")) }
    }
}

#[derive(Deserialize, Debug)]
struct Compte { email: Email }

let r: Result<Compte, _> = serde_json::from_str(r#"{"email":"pas-un-email"}"#);   // Err : email invalide

Un JSON invalide ne peut alors jamais produire un Email : le principe « parse, don't validate » (voir structures-enums) appliqué à serde. into = "String" fait l'inverse à la sérialisation.

use serde::ser::{Serialize, SerializeStruct, Serializer};

struct Point { x: i32, y: i32 }

impl Serialize for Point {
    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        let mut st = s.serialize_struct("Point", 3)?;
        st.serialize_field("x", &self.x)?;
        st.serialize_field("y", &self.y)?;
        st.serialize_field("distance", &((self.x.pow(2) + self.y.pow(2)) as f64).sqrt())?;   // champ calculé
        st.end()
    }
}

Rarement nécessaire : les attributs couvrent presque tous les cas. Implémenter Deserialize à la main est nettement plus long (un visitor) ; on le réserve aux formats vraiment particuliers.

#[derive(Serialize, Deserialize, Debug)]
struct Reponse<T> {
    succes: bool,
    donnees: Option<T>,
    erreur: Option<String>,
}

impl<T> Reponse<T> {
    fn ok(d: T) -> Self { Reponse { succes: true, donnees: Some(d), erreur: None } }
    fn err(e: impl Into<String>) -> Self { Reponse { succes: false, donnees: None, erreur: Some(e.into()) } }
}

let r = Reponse::ok(vec![1, 2, 3]);
let json = serde_json::to_string(&r)?;     // {"succes":true,"donnees":[1,2,3],"erreur":null}

#[derive(Deserialize)]
struct Ligne<'a> {
    nom: &'a str,                                  // pointe dans le texte JSON : aucune allocation
    #[serde(borrow)]
    note: std::borrow::Cow<'a, str>,               // emprunte si possible, alloue si le texte contient un échappement
}

let source = String::from(r#"{"nom":"ada","note":"bien"}"#);
let l: Ligne = serde_json::from_str(&source)?;

Un &str ne fonctionne que si le texte JSON ne contient aucune séquence d'échappement (\", \n) ; Cow gère les deux cas (voir borrow-avance).

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct ChangerMotDePasse {
    ancien: String,
    nouveau: String,
}
// {"ancien":"a","nouveau":"b","role":"admin"} -> Err : unknown field `role`

Par défaut, serde ignore les champs en trop. C'est rarement un problème (ils ne sont stockés nulle part), mais deny_unknown_fields signale une erreur de client, et documente que le payload est fermé.

// Dangereux : désérialiser directement l'entité complète depuis la requête
// #[derive(Deserialize)] struct Utilisateur { id: u32, nom: String, est_admin: bool }
// let u: Utilisateur = serde_json::from_str(corps)?;    // le client peut envoyer "est_admin": true

// Sûr : une struct d'entrée qui ne contient QUE ce que le client a le droit de fixer
#[derive(Deserialize)]
struct ModifierProfil {
    nom: String,
    bio: Option<String>,
}

Ne désérialise jamais une requête directement dans un type qui contient des champs que le client ne doit pas contrôler (rôle, identifiant, propriétaire, prix).

#[derive(Serialize)]
struct UtilisateurPublic<'a> {
    id: u32,
    nom: &'a str,
    // ni le hachage du mot de passe, ni l'email, ni les jetons
}

Une struct de sortie dédiée garantit qu'un champ ajouté plus tard à l'entité (un jeton, une adresse) n'apparaît pas automatiquement dans l'API.

use runique::prelude::*;
use serde::Serialize;

#[derive(Serialize)]
struct ArticleResume {
    id: Pk,
    titre: String,
}

#[derive(Serialize)]
struct ListeArticles {
    articles: Vec<ArticleResume>,
    total: usize,
}

pub async fn liste_articles(request: Request) -> AppResult<Response> {
    let articles = article::Entity::find()
        .filter(article::Column::Publie.eq(true))
        .all(request.db())
        .await?;                                          // DbErr -> AppError automatiquement

    let articles: Vec<ArticleResume> = articles
        .into_iter()
        .map(|a| ArticleResume { id: a.id, titre: a.titre })
        .collect();
    let total = articles.len();

    Ok(Json(ListeArticles { articles, total }).into_response())
}

Renvoyer directement Vec<article::Model> compilerait aussi (le Model est sérialisable), mais exposerait toutes les colonnes, y compris celles ajoutées plus tard.

use serde::{Deserialize, Deserializer};

// 1. Un String, converti plus tard à la main : simple, mais la validation est repoussée
#[derive(Deserialize)]
struct V1 { date: String }

// 2. chrono avec sa feature serde : NaiveDate lit directement "AAAA-MM-JJ"
#[derive(Deserialize)]
struct V2 { date: chrono::NaiveDate }

// 3. deserialize_with : un format sur mesure ("09/11/2026")
#[derive(Deserialize)]
struct V3 {
    #[serde(deserialize_with = "date_fr")]
    date: chrono::NaiveDate,
}

fn date_fr<'de, D: Deserializer<'de>>(d: D) -> Result<chrono::NaiveDate, D::Error> {
    let s = String::deserialize(d)?;
    chrono::NaiveDate::parse_from_str(&s, "%d/%m/%Y").map_err(serde::de::Error::custom)
}

// 4. Un newtype avec try_from : réutilisable partout
#[derive(Deserialize)]
#[serde(try_from = "String")]
struct DateFr(chrono::NaiveDate);

impl TryFrom<String> for DateFr {
    type Error = String;
    fn try_from(s: String) -> Result<Self, String> {
        chrono::NaiveDate::parse_from_str(&s, "%d/%m/%Y")
            .map(DateFr)
            .map_err(|e| format!("date invalide « {s} » : {e}"))
    }
}

#[derive(Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]        #[serde(deny_unknown_fields)]
#[serde(tag = "type")]   #[serde(tag = "t", content = "c")]   #[serde(untagged)]
#[serde(try_from = "String")]   #[serde(into = "String")]   #[serde(default)]

#[serde(rename = "x")]   #[serde(alias = "y")]   #[serde(skip)]
#[serde(skip_serializing_if = "Option::is_none")]   #[serde(default = "fonction")]
#[serde(flatten)]   #[serde(with = "module")]   #[serde(deserialize_with = "f")]   #[serde(borrow)]

serde_json::to_string(&v)?   to_string_pretty   to_vec   to_writer   to_value
serde_json::from_str::<T>(s)?   from_slice   from_reader   from_value
json!({ "a": 1 })   v["cle"].as_str()   v.get("cle")
toml::from_str::<T>(s)?   serde_urlencoded::from_str::<T>(s)?