Axum Routing & Handlers

Defina rotas HTTP, vincule handlers a métodos e retorne respostas tipadas com Axum 0.8.

Receita

Cartão de referência rápida - pronto para copiar e colar.

use axum::{routing::{get, post, delete}, Router, Json};
use serde::{Deserialize, Serialize};
 
#[derive(Deserialize)] struct CreateUser { email: String }
#[derive(Serialize)] struct User { id: u64, email: String }
 
async fn create(Json(body): Json<CreateUser>) -> Json<User> {
    Json(User { id: 1, email: body.email })
}
 
let app = Router::new()
    .route("/users", get(list_users).post(create))
    .route("/users/:id", get(get_user).delete(delete_user));

Quando usar isso: Você precisa de roteamento explícito de métodos HTTP com corpos de solicitação e resposta tipados.

Exemplo de Trabalho

use axum::{
    Router, extract::{Path, State},
    http::StatusCode,
    routing::{delete, get, post},
    Json,
};
use serde::{Deserialize, Serialize};
 
#[derive(Clone, Serialize)]
struct Item { id: u64, name: String }
 
#[derive(Deserialize)]
struct NewItem { name: String }
 
type Store = std::sync::Arc<tokio::sync::RwLock<Vec<Item>>>;
 
async fn list(State(store): State<Store>) -> Json<Vec<Item>> {
    Json(store.read().await.clone())
}
 
async fn create(
    State(store): State<Store>,
    Json(body): Json<NewItem>,
) -> (StatusCode, Json<Item>) {
    let mut guard = store.write().await;
    let item = Item { id: guard.len() as u64 + 1, name: body.name };
    guard.push(item.clone());
    (StatusCode::CREATED, Json(item))
}
 
async fn remove(Path(id): Path<u64>, State(store): State<Store>) -> StatusCode {
    let mut guard = store.write().await;
    if let Some(pos) = guard.iter().position(|i| i.id == id) {
        guard.remove(pos);
        StatusCode::NO_CONTENT
    } else {
        StatusCode::NOT_FOUND
    }
}
 
#[tokio::main]
async fn main() {
    let store = Store::default();
    let app = Router::new()
        .route("/items", get(list).post(create))
        .route("/items/:id", delete(remove))
        .with_state(store);
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

O que isso demonstra:

• Rotas estilo REST com handlers específicos de método no mesmo caminho.
• Tuplas de código de status como (StatusCode::CREATED, Json(item)) para respostas precisas.
• Extratores Path e State combinados em uma única assinatura de handler.
• Armazenamento em memória RwLock para uma demonstração executável sem um banco de dados.

Mergulho Profundo

Como Funciona

• Um Router é um tower::Service que corresponde a requisições por caminho e método.
• Handlers são funções assíncronas cujos últimos parâmetros são extratores; Axum executa extratores em paralelo quando possível.
• Tipos de retorno implementam IntoResponse - strings, tuplas, Json, StatusCode, ou tipos customizados.

Padrões de Rota

Notas de Rust

use axum::response::Redirect;
async fn old() -> Redirect { Redirect::permanent("/v2/old") }

Armadilhas

• Conflitos de ordem de rota - Rotas estáticas e de parâmetro sobrepostas podem corresponder inesperadamente. Correção: Registre caminhos estáticos como /users/me antes de /users/:id.
• Estado ausente - Handlers que usam State sem .with_state() entram em pânico em tempo de execução. Correção: Sempre chame .with_state() no roteador final antes de servir.
• Bloqueio em handlers assíncronos - I/O pesado na CPU ou bloqueante paralisa o worker do Tokio. Correção: Use tokio::task::spawn_blocking ou drivers de banco de dados assíncronos.
• Método errado retorna 405 - Clientes POST para uma rota somente GET. Correção: Documente os métodos permitidos; retorne o cabeçalho Allow em handlers 405 customizados, se necessário.
• Incompatibilidade de campo Serde - Chaves JSON não correspondem aos campos da struct. Correção: Adicione #[serde(rename = "camelCase")] ou retorne um mapeamento explícito 422.

Alternativas

FAQs

Relacionado

• Noções Básicas de Backends Web - Primeira configuração de servidor
• Extratores & Estado - Estado compartilhado e extratores
• Tratamento de Erros em Handlers - Erros tipados
• Middleware & Tower - Camadas transversais
• Testando Serviços Web - Testes de rota

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.