Melhores Práticas de Interoperabilidade
Regras para limites seguros entre linguagens, mapeamento claro de erros e propriedade explícita de memória.
Como Usar Esta Lista
- Aplique a cada nova superfície FFI, exportação PyO3 ou função napi-rs
- Documente a propriedade no cabeçalho, README e tipos TypeScript
- Testes de integração na linguagem hospedeira são obrigatórios
A - Design de Limites
- Um mecanismo de integração óbvio por hospedeiro. PyO3, napi-rs ou C ABI, não os três misturados.
- Exportações de granularidade grossa. Agrupe trabalho para amortizar o overhead de chamadas.
- ABI estável apenas com
repr(C). Nunca exponha layouts padrão do Rust. - Versão da função exportada.
lib_version()para verificações de compatibilidade.
B - Memória e Propriedade
- Cada alocador tem um free correspondente. Documente em comentários de cabeçalho.
- Copie dados pequenos por padrão. Empreste apenas com tempo de vida documentado.
- Valide pares de ponteiro + comprimento. Rejeite comprimentos nulos e de overflow.
- Sem panics atravessando o limite. Mapeie para códigos de erro ou exceções do hospedeiro.
C - Erros e Threads
- Mapeie erros para os idiomas do hospedeiro.
PyErr,Errordo JS, códigos de status C. - Documente a segurança de threads. Quais funções são reentrantes ou requerem GIL.
- Libere o GIL para Rust apenas de CPU. PyO3
allow_threadsem caminhos críticos. - Callbacks thread-safe explícitos.
ThreadsafeFunctiondo napi quando necessário.
D - Build e Lançamento
- Matriz de CI para triplos enviados. Linux, macOS, Windows no mínimo.
- Pré-builds Manylinux / macOS universal2 / MSVC. Usuários de Node e Python não têm Rust.
- Semver na API de limite pública. Quebras na FFI aumentam a versão principal.
- Auditoria da cadeia de suprimentos.
cargo deny+ auditoria de pacotes do hospedeiro.
E - Testes e Documentação
- Testes de integração na linguagem hospedeira. ctypes, pytest ou runner de teste do node.
- Testes de layout para structs C.
size_ofvssizeofdo C em CI. - Exemplos em ambas as linguagens. Teste unitário Rust + script de exemplo Python/TS.
- Diagrama de propriedade no README. Quem aloca, quem libera, quem pode mutar.
FAQs
PyO3 ou ctypes do Python?
PyO3 para módulos de extensão e ergonomia. ctypes para carregar cdylib arbitrárias sem construir como módulo.
Quando a ABI C é necessária?
Sempre que o consumidor não for Rust: C++, Swift, Go, JVM, Unity, etc.
Posso expor async para Python?
Sim com pyo3-async-runtimes e uma política de loop de eventos em execução documentada no README.
JSON na fronteira?
Ok para plano de controle. Evite para loops críticos movendo megabytes.
Como desaprovo exportações?
Mantenha o símbolo, registre um aviso, remova na próxima versão principal. Nunca reutilize valores de enum.
Múltiplos hospedeiros um crate?
Divida em crate Rust core mais crates adaptadores finos py, napi e ffi.
WASM vs nativo?
WASM para plugins em sandbox; nativo para desempenho máximo e acesso à API do SO.
Revisão de segurança?
Trate FFI como superfície de ataque. Fuzz os pontos de entrada da API C.
Logging através da fronteira?
O hospedeiro fornece um callback de log registrado na inicialização, ou retorne apenas strings de erro estruturadas.
Geração de documentação?
cbindgen para C, napi para .d.ts, Sphinx via docstrings pyo3 para Python.
Relacionados
- Noções Básicas de Interoperabilidade - visão geral da estratégia
- Marshalling de Dados - padrões de propriedade
- PyO3 - extensões Python
- Node.js com napi-rs - addons Node
Versões da 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+.