# Recursos do Cargo

O conjunto de recursos de napi controla quais símbolos do Node-API e APIs Rust de alto nível são compilados no addon. Escolha o nível mais baixo do Node-API que forneça as APIs usadas e habilite somente as integrações opcionais necessárias para sua crate.

[dependencies]
napi = { version = "3", features = ["napi6", "async", "serde-json"] }
napi-derive = "3"

# Padrões

napi habilita estes recursos por padrão:

default = ["napi4", "dyn-symbols"]

Isso significa que adicionar features = ["napi2"] sem desabilitar os padrões ainda compila para o Node-API 4. Para usar um nível abaixo de 4, desabilite explicitamente os padrões e decida se quer manter o carregamento dinâmico de símbolos:

[dependencies]
napi = {
  version = "3",
  default-features = false,
  features = ["napi3", "dyn-symbols"]
}

# Níveis do Node-API

Os recursos napi1 a napi10 são cumulativos. Por exemplo, napi8 habilita napi7, que habilita todos os níveis inferiores. O nível escolhido é a capacidade mínima do Node-API da qual seu addon pode depender.

A tabela lista gates representativos de alto nível, não todas as funções brutas reexportadas por napi-sys.

O Node.js fez backport de alguns níveis do Node-API para várias linhas de lançamento, portanto uma única versão principal do Node não é um teste de compatibilidade preciso. Consulte a matriz oficial de versões do Node-API e o valor real do runtime:

console.log(process.versions.napi)

No código nativo, Env::get_napi_version() lê o mesmo valor. A declaração de runtimes compatíveis do seu pacote não deve ser mais ampla do que o nível Node-API escolhido e as versões de runtime que você realmente testa.

# Escolhendo um nível

1. Comece com o napi4 do template/padrão, a menos que uma dependência ou API necessária exija outra coisa.
2. Aumente o nível quando o compilador indicar que uma API necessária é condicionada a um recurso.
3. Teste o runtime mais antigo no intervalo de compatibilidade resultante.
4. Mantenha minNodeApiVersion da CLI, recursos do Cargo, engines do pacote e a matriz de CI consistentes.

Aumentar o recurso pode tornar o addon resultante impossível de carregar ou usar em runtimes mais antigos. Diminuí-lo remove APIs Rust durante a compilação e é a maneira mais segura de descobrir dependências acidentais de um nível mais novo.

# Async e Tokio

Os recursos de componentes habilitam recursos na dependência Tokio. Nem todos implicam o tokio_rt do napi-rs; liste-o explicitamente, a menos que outro recurso selecionado, como web_stream, já o habilite.

[dependencies]
napi = { version = "3", features = ["async", "tokio_fs", "tokio_time"] }

Para trabalho limitado por CPU, prefira AsyncTask, que usa o pool de workers do libuv, em vez de bloquear o runtime Tokio.

# Recursos de conversão

Consulte Conversões de tipos para direcionalidade e comportamento de cópia de dados.

# Linkedição e detecção do runtime

# dyn-symbols

Em alvos nativos compatíveis, dyn-symbols resolve funções do Node-API a partir do processo host quando o addon inicializa, em vez de exigir que todos os símbolos sejam resolvidos pelo linker da plataforma. Ele é habilitado por padrão.

Isso é especialmente útil entre sistemas operacionais e hosts compatíveis com Node que têm comportamentos diferentes de linkedição nativa. Funções ausentes usam stubs gerados para que o carregamento de símbolos continue, mas chamar uma API ausente ainda falha. dyn-symbols não transforma Node-API 10 em Node-API 4.

Desabilite-o somente quando o modelo de linkedição estática/direta do alvo for deliberado e testado:

napi = { version = "3", default-features = false, features = ["napi6"] }

# node_version_detect

node_version_detect lê e armazena em cache a versão do Node host durante o registro do módulo. O napi-rs a usa para selecionar alguns caminhos otimizados e protegidos, incluindo caminhos mais novos de criação de propriedades quando os símbolos e recursos complementares necessários estão habilitados.

Ele não é uma proteção geral de compatibilidade para toda chamada Node-API. Seu código ainda deve respeitar o recurso Node-API selecionado e a matriz de runtimes compatíveis.

# Diagnósticos e observabilidade

[dependencies]
napi = { version = "3", features = ["napi4", "tracing"] }
napi-derive = { version = "3", features = ["tracing"] }

Os eventos gerados de callback usam o target de tracing napi. Instale e configure um subscriber de tracing na aplicação que incorpora o addon ou no caminho de inicialização do addon, caso queira observá-los.

# Recursos de compatibilidade e somente de desenvolvimento

Os atributos de iterador são marcados como experimentais na API Rust, mas não são controlados pelo recurso Cargo experimental. Iteradores síncronos estão no runtime bindgen base; iteradores assíncronos requerem tokio_rt.

# Testes somente com Cargo usando noop

[features]
noop = ["napi/noop", "napi-derive/noop"]

[dependencies]
napi = "3"
napi-derive = "3"

Use isso para testar lógica Rust pura que esteja em uma crate de addon. Execute testes de integração JavaScript contra um addon realmente compilado para conversões, exceções, referências, finalizers, workers e limpeza do ambiente.

# O pacote full

full é um pacote de conveniência que contém exatamente:

full = [
  "latin1",
  "napi10",
  "async",
  "serde-json",
  "experimental",
  "chrono_date",
]

Ele não significa todos os recursos: por exemplo, não inclui web_stream, object_indexmap, deferred_trace, node_version_detect, tracing, error_anyhow nem todos os componentes do Tokio.

Como aumenta o nível do Node-API para 10 e habilita APIs experimentais, full é conveniente para builds de documentação e testes internos amplos, mas raramente é o padrão correto para um addon publicado.

# Recursos do napi-derive

A crate de macro procedural tem seu próprio conjunto de recursos:

Não confunda napi-derive/strict com o atributo por função #[napi(strict)]: o recurso verifica o uso do macro durante a compilação; o atributo valida valores JavaScript em tempo de execução.

# Base recomendada para addons publicados

[dependencies]
napi = {
  version = "3",
  default-features = false,
  features = ["napi4", "dyn-symbols"]
}
napi-derive = "3"

[build-dependencies]
napi-build = "2"

Adicione recursos de integração somente quando a API pública exigir, documente o nível Node-API mínimo resultante e teste esse runtime mínimo e os runtimes atualmente compatíveis na CI.