Módulos em Rust: como dividir o código em vários arquivos sem enlouquecer

Quando um arquivo já é apertado demais

Você programa em Rust. Seu projeto está crescendo. Ainda ontem, main.rs continha tudo — funções, estruturas, algumas configurações. E hoje você gasta cinco minutos para encontrar uma função específica entre milhares de linhas. Familiar?

Mais cedo ou mais tarde, todo desenvolvedor Rust enfrenta a necessidade de dividir o código em partes lógicas. Parece simples, não? Criou uma pasta, organizou os arquivos, importou — e pronto. Mas o sistema de módulos do Rust é famoso por sua rigidez. Uma entrada errada em mod.rs — e o compilador exibe um erro que você levará meia hora para decifrar.

Neste artigo, vamos analisar os principais erros ao dividir um módulo Rust em vários arquivos e, principalmente, mostrar como evitá-los. Você aprenderá como organizar corretamente a estrutura de arquivos, quando usar mod.rs e quando usar lib.rs, e por que pub use é seu melhor amigo.

Anatomia do sistema de módulos Rust

Antes de mergulharmos nos erros, vamos revisar os fundamentos. Em Rust, um módulo é uma unidade de organização de código. Por padrão, cada arquivo é um módulo, mas não é tão linear assim.

Existem duas abordagens:

\n
• Arquivo-módulo de mesmo nome: o arquivo utils.rs se torna automaticamente o módulo utils se você declarar mod utils; em lib.rs ou main.rs.
\n
• Diretório-módulo: a pasta utils/ com o arquivo mod.rs dentro. Neste caso, mod.rs é o ponto de entrada do módulo.
\n

Parece simples, mas é aqui que a maioria das armadilhas se esconde. Vamos analisar as mais comuns.

Top 5 erros ao dividir um módulo em vários arquivos

Erro nº 1: Esqueceu de declarar o submódulo

Você criou o arquivo network/tcp.rs e tenta usá-lo. Escreve use network::tcp; — e recebe um erro de compilação. Por quê? Porque o Rust não escaneia pastas automaticamente. Você deve declarar explicitamente cada submódulo.

// network/mod.rs\n// ❌ Erro: submódulo tcp não declarado\n// use network::tcp; // não compilará\n\n// ✅ Correto:\npub mod tcp; // declaramos o submódulo\n

Como evitar: Sempre verifique se você adicionou pub mod nome_do_submódulo; no módulo pai. Isso é semelhante a uma importação explícita — o Rust exige clareza.

Erro nº 2: Confusão entre mod.rs e lib.rs

Iniciantes frequentemente colocam mod.rs na raiz do projeto, ao lado de main.rs. Isso funciona, mas apenas se você estiver criando uma biblioteca. Para um arquivo executável (main.rs), o módulo raiz é o próprio main.rs. E mod.rs é um arquivo dentro de uma pasta.

my_project/\n├── main.rs        // módulo raiz para o binário\n├── lib.rs         // módulo raiz para a biblioteca (se houver)\n├── utils/\n│   ├── mod.rs     // ponto de entrada do módulo utils\n│   └── helpers.rs\n

Como evitar: Lembre-se da regra: mod.rs vive apenas dentro de uma pasta-módulo. Se você precisar de um módulo raiz para a biblioteca — use lib.rs.

Erro nº 3: Esqueceu o pub nos submódulos

Você declarou o submódulo, mas ainda assim não consegue chamar a função. Provavelmente, você esqueceu de especificar pub.

// network/mod.rs\npub mod tcp;\n\n// network/tcp.rs\n// ❌ Função privada por padrão\nfn connect() { /* ... */ }\n\n// ✅ Tornando-a pública\npub fn connect() { /* ... */ }\n

Em Rust, tudo é privado por padrão. Isso não é um bug, é uma funcionalidade: você decide o que expor ao mundo externo. Se a função for necessária fora do módulo — coloque pub.

Como evitar: Use pub com consciência. Para utilitários internos, mantenha o acesso privado. Para API, torne público.

Erro nº 4: Ignorar