Lição 53: Serialização (JSON, Serde, Persistência)

1. Narrativa

Os mechas da Academia Æther geram enormes volumes de dados de missão — logs de combate, estatísticas de energia, registros de pilotos. Tudo precisa ser armazenado e transmitido. Serialização é a arte de converter estruturas de dados complexas em formato transmissível e armazenável, e desserialização é a arte de reconstruí-las. O piloto que domina serialização nunca perde o histórico de suas missões.

2. Conceito

Serialização é o processo de transformar dados em memória para um formato que pode ser armazenado ou transmitido:

• Formato texto: JSON, CSV, URL-encoded — legível por humanos
• Formato binário: Bincode, MessagePack — eficiente em tamanho
• Serde: Ecossistema Rust para serialização/desserialização automática
• Validação: Verificar integridade dos dados antes de confiar neles

3. Requisitos

• Implementar serialização manual de structs para strings
• Implementar desserialização manual de strings para structs
• Validar dados antes da desserialização
• Trabalhar com lotes de dados (multi-linha)
• Converter para formatos de transmissão (URL params)

4. Design de Dados

graph LR
    A[RegistroMecha] -->|serializar_mecha| B["String: id|nome|..."]
    B -->|desserializar_mecha| A
    A -->|para_parametros_url| C[String: id=1&nome=...]
    A -->|validar_registro| D[Ok / Err]
    A -->|serializar_lote| E[Multi-line String]
    E -->|desserializar_lote| A

5. Diagrama de Fluxo

flowchart TD
    A[Texto Recebido] --> B[Desserializar]
    B --> C{Parse OK?}
    C -->|Não| D[ErroDesserializacao]
    C -->|Sim| E[RegistroMecha]
    E --> F[Validar]
    F --> G{Válido?}
    G -->|Não| H[ErroDesserializacao]
    G -->|Sim| I[Armazenar / Processar]

6. Funções

Função	Descrição
serializar_mecha	Serializa registro para formato pipe-delimited
desserializar_mecha	Desserializa linha para registro
serializar_lote	Serializa lista para texto multi-linha
desserializar_lote	Desserializa texto para lista de registros
validar_registro	Valida consistência dos dados
filtrar_por_status	Filtra registros por status
calcular_estatisticas_lote	Calcula estatísticas agregadas
para_parametros_url	Converte para formato URL-encoded

7. Exemplo

let registro = RegistroMecha {
    id: 1, nome: "Æther-01".into(), piloto: "Rex".into(),
    status: StatusMecha::Ativo, energia: 100, missoes: 42,
};
let texto = serializar_mecha(&registro);
assert_eq!(texto, "1|Æther-01|Rex|ativo|100|42");
let restaurado = desserializar_mecha(&texto).unwrap();
assert_eq!(restaurado, registro);

Serialização JSON com Serde

Os tipos RegistroMecha e StatusMecha derivam Serialize e Deserialize, permitindo conversão automática para JSON e de volta:

use serde_json::json;

let registro = RegistroMecha {
    id: 1, nome: "Æther-01".into(), piloto: "Rex".into(),
    status: StatusMecha::Ativo, energia: 100, missoes: 42,
};

// Serializar para JSON
let json = serde_json::to_string(&registro).unwrap();
assert!(json.contains("\"nome\":\"Æther-01\""));

// Desserializar de JSON
let restaurado: RegistroMecha = serde_json::from_str(&json).unwrap();
assert_eq!(restaurado, registro);

// Construir a partir de um valor JSON
let valor = json!({ "id": 2, "nome": "Titan-07", "piloto": "Max",
                    "status": "EmCombate", "energia": 80, "missoes": 15 });
let outro: RegistroMecha = serde_json::from_value(valor).unwrap();

8. Missão

1. Implementar serializar_mecha convertendo struct para string pipe-delimited
2. Implementar desserializar_mecha fazendo split por | e parse dos campos
3. Implementar serializar_lote juntando linhas com \n
4. Implementar desserializar_lote fazendo split por \n e desserializando cada linha
5. Implementar validar_registro verificando restrições de cada campo
6. Implementar filtrar_por_status usando iterators
7. Implementar calcular_estatisticas_lote agregando dados com fold
8. Implementar para_parametros_url montando query string

9. Como Executar

cargo build
cargo test
cargo clippy -- -D warnings
cargo fmt --check

10. Dicas

• Use .split('|') para separar campos na desserialização
• Use .parse::<u32>() para converter strings em números
• Trate erros com map_err() para converter falhas de parse em ErroDesserializacao
• Linhas vazias no lote devem ser ignoradas com .filter(|l| !l.is_empty())
• URL encoding usa & como separador e = entre chave e valor