Módulos en Rust: cómo dividir el código en varios archivos sin volverse loco

Cuando un archivo ya es demasiado pequeño

Estás escribiendo en Rust. Tu proyecto crece. Ayer main.rs lo contenía todo: funciones, estructuras, un par de configuraciones. Y hoy pierdes cinco minutos buscando la función que necesitas entre miles de líneas. ¿Te suena familiar?

Tarde o temprano, todo desarrollador de Rust se enfrenta a la necesidad de dividir el código en partes lógicas. Parecería que no podría ser más sencillo: creas una carpeta, colocas los archivos, importas y listo. Pero el sistema de módulos de Rust es famoso por su rigurosidad. Una entrada incorrecta en mod.rs y el compilador arroja un error que te tomará media hora descifrar.

En este artículo, analizaremos los principales errores al dividir un módulo de Rust en varios archivos y, lo más importante, mostraremos cómo evitarlos. Aprenderá a organizar correctamente la estructura de archivos, cuándo usar mod.rs y cuándo lib.rs, y por qué pub use es su mejor amigo.

Anatomía del sistema de módulos de Rust

Antes de sumergirnos en los errores, recordemos los conceptos básicos. En Rust, un módulo es una unidad de organización del código. Por defecto, cada archivo es un módulo, pero no todo es tan lineal.

Hay dos enfoques:

\n
• Archivo-módulo homónimo: el archivo utils.rs se convierte automáticamente en el módulo utils si declaras mod utils; en lib.rs o main.rs.
\n
• Directorio-módulo: una carpeta utils/ con un archivo mod.rs dentro. En este caso, mod.rs es el punto de entrada al módulo.
\n

Suena simple, pero aquí es donde se esconden la mayoría de las trampas. Analicemos las más comunes.

Top 5 errores al dividir un módulo en varios archivos

Error n.º 1: Olvidaste declarar el submódulo

Creaste el archivo network/tcp.rs e intentas usarlo. Escribes use network::tcp; y obtienes un error de compilación. ¿Por qué? Porque Rust no escanea las carpetas automáticamente. Debes declarar explícitamente cada submódulo.

// network/mod.rs\n// ❌ Error: el submódulo tcp no está declarado\n// use network::tcp; // no compilará\n\n// ✅ Correcto:\npub mod tcp; // declaramos el submódulo\n

Cómo evitarlo: Siempre verifica que hayas agregado pub mod nombre_del_submódulo; en el módulo padre. Es similar a una importación explícita: Rust exige claridad.

Error n.º 2: Confusión entre mod.rs y lib.rs

Los principiantes suelen colocar mod.rs en la raíz del proyecto, junto a main.rs. Esto funciona, pero solo si estás creando una biblioteca. Para un archivo ejecutable (main.rs), el módulo raíz es el propio main.rs. Y mod.rs es un archivo dentro de una carpeta.

my_project/\n├── main.rs        // módulo raíz para el binario\n├── lib.rs         // módulo raíz para la biblioteca (si existe)\n├── utils/\n│   ├── mod.rs     // punto de entrada al módulo utils\n│   └── helpers.rs\n

Cómo evitarlo: Recuerda la regla: mod.rs solo vive dentro de una carpeta-módulo. Si necesitas un módulo raíz para la biblioteca, usa lib.rs.

Error n.º 3: Olvidaste el pub en los submódulos

Declaraste el submódulo, pero aún así no puedes llamar a la función. Lo más probable es que hayas olvidado especificar pub.

// network/mod.rs\npub mod tcp;\n\n// network/tcp.rs\n// ❌ La función es privada por defecto\nfn connect() { /* ... */ }\n\n// ✅ La hacemos pública\npub fn connect() { /* ... */ }\n

En Rust, todo es privado por defecto. Esto no es un error, sino una característica: tú decides qué exponer al mundo exterior. Si la función se necesita fuera del módulo, coloca pub.

Cómo evitarlo: Usa pub de forma consciente. Para utilidades internas, deja el acceso privado. Para API, hazlo público.

Error n.º 4: Ignorar