Módulos e Sistema de Crates do Rust

O código Rust é organizado em três níveis aninhados que são constantemente confundidos porque compartilham vocabulário: módulos, que formam uma árvore de namespace e privacidade dentro de um crate; crates, que são a unidade real que o compilador compila; e pacotes (ou workspaces, para vários pacotes juntos), que é o que o Cargo gerencia. Confundir esses - tratar "módulo" e "crate" como sinônimos, por exemplo - é a fonte mais comum de confusão para pessoas que organizam seu primeiro projeto Rust não trivial.

Esta página é a âncora conceitual para a seção de módulos e crates. Noções Básicas de Módulos aborda mod, layout de arquivos e sintaxe use na prática; esta página explica o que cada nível realmente é para o compilador, como o modelo de privacidade do Rust difere de "público vs. privado" na maioria das outras linguagens e como o modelo mental de workspace escala essa mesma estrutura em um projeto multi-crate.

Resumo

• Módulos formam uma árvore que controla o namespace e a visibilidade dentro de um crate; crates são a unidade real de compilação do compilador; pacotes (e workspaces de pacotes) são o que o Cargo gerencia e versiona.
• Por que Importa: Bases de código grandes precisam de uma maneira de ocultar detalhes de implementação, agrupar código relacionado e dividir a compilação em unidades independentemente compiláveis - e o Rust dá a cada uma dessas três necessidades um mecanismo distinto e construído para fins específicos em vez de um conceito sobrecarregado.
• Conceitos Chave: árvore de módulos, privacidade (pub, pub(crate), pub(super)), raiz do crate, pacote vs. crate, workspace.
• Quando Usar: Módulos para organizar e encapsular código dentro de um crate; um novo limite de crate quando o código precisa de compilação independente, versionamento ou uma superfície de API dyn-free; um workspace quando vários crates no mesmo repositório devem compartilhar um lockfile e versões de dependência.
• Limitações / Trade-offs: Mais crates significam limites mais limpos, mas mais superfícies de API inter-crate para projetar e versionar; módulos profundamente aninhados melhoram a organização, mas adicionam verbosidade de caminho que use apenas parcialmente compensa.
• Tópicos Relacionados: propriedade e empréstimo (a privacidade protege invariantes da mesma forma que a propriedade protege o aliasing), objetos de trait e design de API pública, resolução de dependências do Cargo.

Fundamentos

Todo crate tem exatamente uma árvore de módulos, enraizada em sua raiz de crate - src/lib.rs para um crate de biblioteca, src/main.rs para um binário. Todos os outros módulos no crate são nós nessa árvore, declarados com mod nome; (carregando nome.rs ou nome/mod.rs) ou mod nome { ... } (declarado inline). A árvore existe para fazer duas coisas: dar a cada item um caminho totalmente qualificado (crate::api::routes::health) e atuar como o limite no qual a privacidade é aplicada.

A privacidade no Rust é mais rigorosa, por padrão, do que na maioria das linguagens que você pode ter usado antes: cada item - funções, structs, campos de struct, variantes de enum, blocos impl - é privado, a menos que explicitamente marcado de outra forma, e "privado" significa visível apenas dentro do módulo que o define e dos descendentes desse módulo. Este é o padrão oposto de linguagens onde "público, a menos que marcado como privado" é a norma, e isso significa que um novo módulo Rust, pronto para uso, é um forte limite de encapsulamento em vez de um aberto.

pub é o marcador mais permissivo, expondo um item a qualquer coisa que possa ver o caminho do módulo que leva a ele (incluindo, em última análise, outros crates, se o caminho for reexportado publicamente). Marcadores mais restritos existem para necessidades mais restritas: pub(crate) expõe um item em qualquer lugar dentro do crate atual, mas em nenhum lugar fora dele - a escolha idiomática para "API interna compartilhada, não faz parte do nosso contrato público". pub(super) expõe um item apenas ao módulo pai. pub(in some::path) restringe a visibilidade a uma subárvore arbitrária e nomeada. Esse sistema graduado é o que permite que um crate tenha uma estrutura interna rica - módulos auxiliares, utilitários internos, detalhes de implementação - sem que nada disso vaze acidentalmente para a API pública real do crate.

Mecânicas e Interações

Ajuda pensar nos três níveis como respondendo a três perguntas diferentes:

  módulo   -> "O que pode ver este item?"          (namespace + privacidade, dentro de um crate)
  crate    -> "O que o compilador compila como uma unidade?"   (uma raiz, uma árvore de módulos)
  pacote  -> "O que o Cargo constrói, versiona e publica?"  (um Cargo.toml, um ou mais crates)

Um crate é a coisa real que rustc compila: uma raiz de crate, sua árvore de módulos inteira, compilada junta em uma biblioteca (.rlib) ou binário. Limites de crate importam por razões reais e técnicas além da organização - código genérico e implementações de trait são monomorfizados por crate, caches de compilação incremental por crate, e a regra do órfão (que restringe a implementação de um trait estrangeiro para um tipo estrangeiro) é definida em termos de limites de crate especificamente.

Um pacote é o que um único Cargo.toml descreve: um nome, uma versão, dependências e até um crate de biblioteca mais quaisquer crates binários, de exemplo, de teste e de benchmark. Esta é a camada onde "crate" e "pacote" são mais frequentemente confundidos, porque o caso comum - um Cargo.toml, um lib.rs ou main.rs - faz com que pacote e crate pareçam a mesma coisa. Eles divergem assim que um pacote define tanto um crate de biblioteca (src/lib.rs) quanto um ou mais binários (src/bin/*.rs, ou src/main.rs junto com a biblioteca): isso é um pacote contendo múltiplos crates, compartilhando dependências, mas cada um compilado e monomorfizado separadamente.

# Um pacote, dois crates: uma biblioteca mais um binário CLI que a utiliza.
[package]
name = "toolkit"
version = "0.1.0"
 
[lib]
name = "toolkit"        # crate 1: a biblioteca, src/lib.rs
 
[[bin]]
name = "toolkit-cli"     # crate 2: o binário, src/bin/cli.rs
path = "src/bin/cli.rs"

Um workspace é a camada mais externa: vários pacotes, listados sob uma tabela raiz [workspace], compartilhando um único Cargo.lock para que cada crate no workspace resolva a mesma versão de cada dependência compartilhada. Crucialmente, um workspace não altera os limites de privacidade ou compilação - cada pacote membro ainda compila seus próprios crate(s) independentemente, com sua própria árvore de módulos e sua própria superfície pub voltada para os outros. O que um workspace muda é puramente uma preocupação do nível do Cargo: unificação de versões de dependência, um lockfile compartilhado e a capacidade de executar cargo build --workspace ou cargo test -p some-crate em todo o conjunto a partir de uma raiz.

Considerações Avançadas e Aplicações

Escolher a profundidade do módulo versus os limites do crate versus os membros do workspace é uma decisão arquitetônica real, não apenas estilística, porque cada nível impõe uma força diferente de separação.

O modelo de privacidade interage com os limites do crate de uma forma que surpreende pessoas vindas de linguagens onde "público" é um conceito único e plano: um item pode ser pub em toda a sua árvore de módulos e ainda ser completamente invisível fora do crate, porque nada o reexporta através da raiz do crate. Inversamente, pub use permite que um crate reexporte um item profundamente aninhado em um caminho raso e conveniente - é assim que um crate apresenta uma superfície de API pública limpa no estilo "prelude", mantendo sua estrutura de módulo interna real livre para ser reorganizada sem quebrar essa superfície pública, desde que o caminho de reexportação permaneça estável. Projetar essa superfície pública deliberadamente - decidir o que é pub, o que é pub(crate) e o que é reexportado na raiz do crate - é efetivamente projetar o contrato semver do seu crate, já que qualquer item publicamente alcançável é algo em que o código downstream agora pode depender.

A regra do órfão é o exemplo mais aguçado de limites de crate importando além da organização: você pode implementar um trait que define para qualquer tipo, e você pode implementar um trait estrangeiro para um tipo que define, mas geralmente não pode implementar um trait estrangeiro para um tipo estrangeiro - essa combinação específica é bloqueada no nível do limite do crate para evitar que dois crates definam implementações conflitantes do mesmo trait para o mesmo tipo. Nenhum nível de aninhamento de módulo muda isso; é fundamentalmente uma regra de nível de crate, que é um dos sinais mais claros de que "módulo" e "crate" não são conceitos intercambiáveis, mesmo quando a estrutura de um projeto pequeno os faz parecer assim.

Conceitos Errôneos Comuns

• "Módulos e crates são basicamente a mesma unidade organizacional" - Um módulo é um nó de namespace e privacidade dentro da árvore de um crate; um crate é a coisa real que o compilador compila como uma unidade. Um crate pode (e geralmente faz) conter muitos módulos, mas um módulo nunca é compilado independentemente.
• "Um pacote sempre significa um crate" - O caso comum (um Cargo.toml, um lib.rs) faz parecer que isso é verdade, mas um pacote pode definir um crate de biblioteca mais vários crates binários simultaneamente, cada um compilado separadamente do mesmo Cargo.toml.
• "pub em um campo de struct ou item o torna automaticamente visível fora do crate" - pub torna um item tão visível quanto o caminho que leva a ele permite; se nada reexportar esse caminho na raiz do crate ou acima dela, o item permanece efetivamente privado para crates externos, mesmo que esteja marcado como pub.
• "Tudo o que não está marcado como pub é visível dentro do mesmo arquivo" - A privacidade é escopo ao módulo, não ao arquivo; uma struct declarada privada em um módulo é invisível mesmo para código irmão em um módulo diferente dentro do mesmo arquivo, a menos que esse código esteja aninhado dentro do mesmo módulo.
• "Um workspace une seus crates membros em uma única unidade de compilação" - Não une; cada membro do workspace ainda compila como seu próprio crate independente com sua própria árvore de módulos e limite de privacidade. Um workspace apenas unifica a resolução de dependências (um Cargo.lock compartilhado) e a conveniência da ferramenta de compilação.

FAQs

Relacionados

• Noções Básicas de Módulos - mod prático, layout de arquivos e sintaxe use.
• Visibilidade e Privacidade - pub, pub(crate), pub(super) e padrões de encapsulamento em profundidade.
• Crates e Pacotes - a distinção pacote/crate com exemplos concretos de Cargo.toml.
• Projetando uma API Pública - moldando deliberadamente a superfície pub de um crate como um contrato semver.
• Workspaces - repositórios multi-crate, dependências compartilhadas e comandos Cargo em nível de workspace.
• Workspaces do Cargo - o lado de ferramentas do Cargo da configuração do workspace.

Versões da Pilha: Esta página foi escrita para Rust 1.97.0 (edição 2024).