Cargo: Unresolved Import

O erro “unresolved import” ocorre quando o compilador não consegue encontrar o item que você está tentando importar com use. É um dos erros mais comuns ao organizar código em módulos ou ao usar crates externos.

A Mensagem de Erro

error[E0432]: unresolved import `serde::Serialize`
 --> src/main.rs:1:5
  |
1 | use serde::Serialize;
  |     ^^^^^^^^^^^^^^^^ no `Serialize` in the root

Variação com módulo interno:

error[E0432]: unresolved import `crate::modelos`
 --> src/main.rs:1:5
  |
1 | use crate::modelos::Usuario;
  |     ^^^^^^^^^^^^^^ could not find `modelos` in the crate root

Variação com caminho parcialmente correto:

error[E0432]: unresolved import `std::collection::HashMap`
 --> src/main.rs:1:5
  |
1 | use std::collection::HashMap;
  |         ^^^^^^^^^^ could not find `collection` in `std`
  |
  = help: did you mean `collections`?

O Que Significa

O sistema de módulos do Rust é explícito — você precisa declarar módulos e importar items corretamente. O erro “unresolved import” significa que o compilador procurou o caminho especificado no use e não encontrou o item. As causas mais frequentes são:

Dependência não adicionada ao Cargo.toml
Erro de digitação no caminho do import
Módulo não declarado com mod
Item é privado (não marcado com pub)
Feature flag necessária não ativada
Caminho incorreto no sistema de módulos

Código com Erro

// ERRO: crate `serde` não está no Cargo.toml
use serde::{Serialize, Deserialize};

// ERRO: typo — "collection" em vez de "collections"
use std::collection::HashMap;

// ERRO: módulo não declarado
use crate::modelos::Usuario;

fn main() {}

Como Resolver

Solução 1: Adicionar Dependência ao Cargo.toml

Se o import é de um crate externo, adicione-o:

# Usando cargo add (recomendado)
cargo add serde --features derive
cargo add tokio --features full
cargo add reqwest --features json

Ou edite Cargo.toml manualmente:

[dependencies]
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
reqwest = { version = "0.12", features = ["json"] }

Depois o import funciona:

use serde::{Serialize, Deserialize};

Solução 2: Corrigir Erros de Digitação

O compilador frequentemente sugere o nome correto:

// ERRO:
use std::collection::HashMap;
// Compilador sugere: did you mean `collections`?

// CORRETO:
use std::collections::HashMap;

Caminhos comuns da biblioteca padrão:

use std::collections::{HashMap, HashSet, BTreeMap, VecDeque};
use std::io::{self, Read, Write, BufRead, BufReader};
use std::fs::{self, File};
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex, RwLock, mpsc};
use std::thread;
use std::time::{Duration, Instant};
use std::fmt::{self, Display};
use std::error::Error;

Solução 3: Declarar Módulos Corretamente

O Rust precisa saber sobre seus módulos. A estrutura de arquivos deve corresponder às declarações:

Estrutura do projeto:

src/
├── main.rs
├── modelos/
│   ├── mod.rs         (ou modelos.rs no diretório pai)
│   └── usuario.rs
└── servicos/
    ├── mod.rs
    └── autenticacao.rs

Declarações necessárias:

// src/main.rs
mod modelos;      // Declara o módulo
mod servicos;

use crate::modelos::usuario::Usuario;
use crate::servicos::autenticacao::login;

fn main() {
    let user = Usuario::novo("Alice");
    login(&user);
}

// src/modelos/mod.rs
pub mod usuario;  // Declara submódulo e o torna público

// src/modelos/usuario.rs
pub struct Usuario {
    pub nome: String,
}

impl Usuario {
    pub fn novo(nome: &str) -> Self {
        Usuario { nome: nome.to_string() }
    }
}

Solução 4: Tornar Items Públicos

Se o item existe mas é privado:

// src/utils.rs
// ERRADO: função é privada por padrão
fn formatar(texto: &str) -> String {
    texto.to_uppercase()
}

// CORRETO: marque com `pub`
pub fn formatar(texto: &str) -> String {
    texto.to_uppercase()
}

Níveis de visibilidade:

pub fn publica() {}                    // Visível de qualquer lugar
pub(crate) fn so_no_crate() {}         // Visível dentro do crate
pub(super) fn so_no_modulo_pai() {}    // Visível no módulo pai
fn privada() {}                        // Só no módulo atual

Solução 5: Ativar Feature Flags

Alguns items só estão disponíveis com features:

# Cargo.toml
[dependencies]
# Sem a feature "derive", Serialize não está disponível
serde = { version = "1", features = ["derive"] }

# Sem "macros", o atributo #[tokio::main] não existe
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

Solução 6: Usar Caminhos Alternativos

// Caminho absoluto no crate
use crate::modelos::Usuario;

// Caminho relativo ao módulo pai
use super::utils::formatar;

// Caminho relativo ao módulo atual
use self::helpers::interno;

// Re-exportação para simplificar imports
// Em src/modelos/mod.rs:
pub mod usuario;
pub use usuario::Usuario;  // Re-exporta

// Agora em main.rs pode usar:
use crate::modelos::Usuario;  // Mais curto

Dica: Verificar Imports Rapidamente

# Lista todas as dependências do projeto
cargo tree

# Verifica se uma dependência existe
cargo search nome-do-crate

# Documentação das dependências
cargo doc --open

Cargo: Unresolved Import — Como Resolver