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: unCargo.tomlmá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;invalidaaen el caso de unStringpero no en el de uni32. - 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
matchsobre él. - Escribir una función que devuelva
Resulty usar?dentro de ella.
Ejercicios
- Amplía el juego: limita al jugador a 7 intentos e imprime el número secreto si falla.
- Mueve la lógica de comparación a un módulo
gamecon una función públicafn check(guess: u32, secret: u32) -> Verdictque devuelva un enum tuyo. - Proyecto. Escribe una lista de tareas de línea de comandos que guarde las tareas en un
Vec<Task>y entiendaadd <texto>,done <n>,listyquitescritos por la entrada estándar.
Comprueba lo que has entendido
Elige una respuesta para ver la explicación.
1.¿Cuál es la visibilidad por defecto de una función dentro de un módulo?
2.¿Dónde busca Cargo el código de
mod network;declarado ensrc/main.rs?3.¿Para qué sirve
Cargo.lock?