Melhores Práticas de Macros

Prefira funções, genéricos e traits; use macros quando a sintaxe ou a geração de código exigir. Boas macros têm ótimos erros, testes e gramática de entrada documentada.

Como Usar Esta Lista

• Revise antes de adicionar um novo macro_rules! ou crate de proc-macro.
• Use como checklist para macros de DSL/framework internas.
• Combine com Depurando Macros para o fluxo de trabalho.

A - Quando Usar Macro

• Tente fn, const fn, trait, impl primeiro. Melhores erros e suporte de IDE.
• Use macro_rules! apenas para sintaxe repetitiva. Não para lógica de negócios.
• Use proc macros para derives e atributos. Quando a transformação de AST for necessária.
• Evite macros para ocultar hacks de propriedade. Corrija o design da API em vez disso.
• Documente a gramática de entrada de macro aceita. Exemplos para cada variante.

B - Implementação

• Proc macro em crate separada com proc-macro = true. Mantenha syn fora do grafo de dependência de tempo de execução.
• Use syn::Error::new_spanned para diagnósticos. Aponte para o token do usuário, não para os internos da macro.
• Suporte genéricos com split_for_impl. Derives devem funcionar em struct Foo<T>.
• Reemita attrs e visibilidade em itens transformados. Não ignore #[allow] ou pub.
• Use caminhos $crate:: em macro_rules! exportadas. Resolve corretamente a partir da crate consumidora.

C - Teste e Depuração

• Snapshots de cargo expand para macros não triviais. Verificados em CI via macrotest ou revisão manual.
• Testes de falha de compilação trybuild para entrada inválida. Bloqueie mensagens de erro.
• Teste unitário de lógica de parse/geração com proc_macro2. Sem o driver completo do compilador.
• Controle eprintln! de depuração por feature ou env. Sem compilações barulhentas para usuários.
• Acompanhe o impacto do tempo de compilação. Divida expansões enormes para build.rs se necessário.

D - API e Manutenção

• Prefira API pública estável fora da macro. A macro gera um wrapper fino em torno de fn testadas.
• Versionamento de crates de proc-macro com semver. Sintaxe de DSL quebrada é um bump principal.
• Fixe versões de syn/quote conscientemente. O alinhamento do workspace reduz a duplicação de syn.
• README mostra antes/depois da expansão para um exemplo. Onboarding para consumidores de macro.
• Evite vazar nomes de tipos internos gerados. Superfície pública estável entre releases.

E - Segurança e Correção

• Macros SQL/DSL ainda parametrizam dados do usuário em tempo de execução. String em tempo de compilação não é sanitização.
• Sem sistema de arquivos/rede em proc macros em compilações de CI. Expansão determinística.
• Higiene: evite colidir idents gerados com código do usuário. Use módulos privados ou prefixos únicos.
• Revise unsafe no código gerado como unsafe escrito à mão. Macro não absolve a revisão.
• Audite proc macros de terceiros como qualquer dependência. Risco na cadeia de suprimentos.

FAQs

Relacionado

• Noções Básicas de Macros - introdução
• Depurando Macros - ferramentas
• syn & quote - implementação
• 50 Regras de Rust

Versões de Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.