FerrousPath

Nivel 1 · Fundamentos· Lección 10 de 10 · 25 min

Módulos, crates y Cargo

Organizar el código en módulos, controlar la visibilidad, usar dependencias de crates.io — y un primer proyecto.

Paquetes, crates, módulos

  • Un crate es una unidad de compilación: un binario (tiene main) o una biblioteca.
  • Un paquete es lo que crea cargo new: un Cargo.toml más uno o varios crates.
  • Un módulo es un espacio de nombres dentro de un crate.

src/main.rs es la raíz de un crate binario; src/lib.rs es la raíz de un crate de biblioteca. Un paquete puede tener los dos.

Módulos y visibilidad

mod kitchen {
    pub struct Order {
        pub dish: String,
        notes: String, // campo privado
    }

    impl Order {
        pub fn new(dish: &str) -> Order {
            Order { dish: dish.to_string(), notes: String::new() }
        }

        pub fn summary(&self) -> String {
            format!("{} ({})", self.dish, quality_check(&self.notes))
        }
    }

    fn quality_check(notes: &str) -> &'static str {
        if notes.is_empty() { "standard" } else { "custom" }
    }

    pub mod pantry {
        pub fn stock() -> u32 {
            super::secret_reserve() + 10 // `super` es el módulo padre
        }
    }

    fn secret_reserve() -> u32 {
        5
    }
}

use kitchen::Order;

fn main() {
    let order = Order::new("ramen");
    println!("{}", order.summary());
    println!("{}", kitchen::pantry::stock());
    // order.notes;               // ❌ campo privado
    // kitchen::quality_check(""); // ❌ función privada
}

Todo es privado por defecto. pub hace que un elemento sea visible para el módulo padre. Los campos de un struct tienen su propia visibilidad, así que un tipo puede ser público mientras su representación permanece oculta: así es como se protegen los invariantes. pub(crate) significa «visible en cualquier parte de este crate, pero no fuera de él».

Rutas: crate:: empieza en la raíz del crate, super:: en el módulo padre, self:: en el módulo actual. use trae una ruta al ámbito.

Módulos en archivos

Los proyectos reales ponen los módulos en archivos separados:

src/
├── main.rs          // contiene: mod kitchen;
├── kitchen.rs       // el contenido del módulo kitchen; contiene: pub mod pantry;
└── kitchen/
    └── pantry.rs    // el contenido de kitchen::pantry

mod kitchen; (con punto y coma) le dice al compilador que cargue el módulo desde kitchen.rs. Cada módulo se declara una sola vez, en su padre; en todos los demás sitios lo traes con use. Los archivos no son módulos hasta que alguna declaración mod lo dice.

Dependencias

Las bibliotecas viven en crates.io. Añade una con:

cargo add rand

lo que edita Cargo.toml:

[package]
name = "guess"
version = "0.1.0"
edition = "2024"

[dependencies]
rand = "0.9"

"0.9" significa «cualquier 0.9.x»: Cargo sigue el versionado semántico y no elegirá una versión que se declare incompatible. Las versiones exactas elegidas quedan registradas en Cargo.lock. La documentación de todos los crates publicados está en docs.rs/<nombre-del-crate>.

Las ediciones (2015, 2018, 2021, 2024) son revisiones opcionales del lenguaje. Crates de ediciones distintas interoperan libremente, así que el ecosistema nunca se divide.

Proyecto: un juego de adivinar

Es hora de construir algo en tu máquina. Crea un proyecto, añade rand y escribe esto en src/main.rs:

// crate: rand
use std::cmp::Ordering;
use std::io::{self, Write};

fn main() {
    let secret: u32 = rand::random_range(1..=100);
    let mut attempts = 0;

    loop {
        print!("Guess (1-100): ");
        io::stdout().flush().unwrap();

        let mut line = String::new();
        if io::stdin().read_line(&mut line).unwrap() == 0 {
            println!("\nNo more input. The number was {secret}.");
            break;
        }
        let Ok(guess) = line.trim().parse::<u32>() else {
            println!("Please type a number.");
            continue;
        };
        attempts += 1;

        match guess.cmp(&secret) {
            Ordering::Less => println!("Too small."),
            Ordering::Greater => println!("Too big."),
            Ordering::Equal => {
                println!("Correct in {attempts} attempts!");
                break;
            }
        }
    }
}

Usa casi todo lo visto en este nivel: una dependencia, estado mutable, un bucle, let else, match y la entrada estándar. (El botón Ejecutar funciona, pero el Playground no tiene entrada por teclado: el programa ve el fin de la entrada inmediatamente. Ejecútalo con cargo run para jugar.)

Punto de control del nivel 1

Antes de seguir, deberías poder hacer esto sin consultar nada:

  • Explicar por qué let b = a; invalida a en el caso de un String pero no en el de un i32.
  • Enunciar la regla de los préstamos y dar un ejemplo que el compilador rechace.
  • Modelar un dominio pequeño con un struct y un enum y escribir un match sobre él.
  • Escribir una función que devuelva Result y usar ? dentro de ella.

Ejercicios

  1. Amplía el juego: limita al jugador a 7 intentos e imprime el número secreto si falla.
  2. Mueve la lógica de comparación a un módulo game con una función pública fn check(guess: u32, secret: u32) -> Verdict que devuelva un enum tuyo.
  3. Proyecto. Escribe una lista de tareas de línea de comandos que guarde las tareas en un Vec<Task> y entienda add <texto>, done <n>, list y quit escritos por la entrada estándar.

Comprueba lo que has entendido

Elige una respuesta para ver la explicación.

  1. 1.¿Cuál es la visibilidad por defecto de una función dentro de un módulo?

  2. 2.¿Dónde busca Cargo el código de mod network; declarado en src/main.rs?

  3. 3.¿Para qué sirve Cargo.lock?

Términos clave de esta lección

¿Has terminado la lección y los ejercicios?