Servidor HTTP básico en Rust con Axum — Capítulo 20

Por /

Construyendo APIs web asíncronas en Rust

En el contexto de un libro sobre programación avanzada en Rust, este capítulo aborda las bases de la programación de redes mediante el framework Axum, que se integra con el ecosistema Tokio para aplicaciones web asíncronas. Axum facilita la creación de servidores HTTP eficientes y escalables, lo que resulta esencial para desarrollar servicios backend modernos. Su enfoque en la seguridad de tipos y la concurrencia hace que sea una elección natural para proyectos que requieren alto rendimiento y fiabilidad.

Axum router

El router de Axum constituye el componente central para enrutar solicitudes HTTP a funciones manejadoras específicas. Basado en el crate axum, este router permite definir rutas de manera declarativa, asociando métodos HTTP como GET, POST o DELETE a paths URL. La estructura del router se construye mediante el tipo Router, que se puede componer de forma modular para organizar aplicaciones complejas.

Una instancia básica de router se crea con Router::new(), y las rutas se añaden mediante el método route(). Por ejemplo, para definir una ruta simple que responda a solicitudes GET en el path raíz:

use axum::{Router, routing::get};

fn hello_world() -> &'static str {
    "Hello, world!"
}

let app: Router = Router::new()
    .route("/", get(hello_world));

En este fragmento, get es un constructor de método que vincula la función hello_world al verbo HTTP GET. Axum soporta anidamiento de routers mediante nest(), lo que permite modularizar subaplicaciones. Por instancia, un subrouter para una API podría definirse como:

let api_router: Router = Router::new()
    .route("/users", get(list_users));

let app: Router = Router::new()
    .nest("/api", api_router);

Es fundamental destacar que las rutas deben ser únicas dentro de un router; conflictos en paths generan errores en tiempo de compilación. Además, Axum integra con Tokio para ejecutar el servidor de forma asíncrona, iniciándose con axum::Server::bind() seguido de serve(app). Esta integración asegura que el router maneje concurrencia sin bloquear hilos, diferenciándose de frameworks síncronos en lenguajes como Python (por ejemplo, Flask), donde la asincronía requiere extensiones adicionales.

Los casos borde incluyen paths con parámetros dinámicos, que se manejan con extractores (discutidos en secciones posteriores), y el soporte para wildcards en rutas como /*path para capturar segmentos restantes. En comparación con Go’s net/http, donde el enrutamiento es más manual, Axum ofrece una abstracción de tipos más segura, previniendo errores comunes en el manejo de solicitudes.

Handlers async

Las funciones manejadoras (handlers) en Axum son asíncronas por diseño, lo que permite operaciones no bloqueantes como lecturas de base de datos o llamadas a servicios externos. Un handler se define como una función async que devuelve un tipo implementando IntoResponse, como String, StatusCode o estructuras más complejas.

Para ilustrar, un handler básico que responde de forma asíncrona podría ser:

use axum::http::StatusCode;

async fn async_handler() -> (StatusCode, &'static str) {
    // Simulación de operación asíncrona
    tokio::time::sleep(std::time::Duration::from_secs(1)).await;
    (StatusCode::OK, "Respuesta asíncrona")
}

Este handler se registra en el router con get(async_handler) o equivalentes para otros métodos. La asincronía es obligatoria en Axum; funciones síncronas deben envolverse en un bloqueo como tokio::task::spawn_blocking para evitar bloquear el executor. Esto contrasta con frameworks como Express en Node.js, donde la asincronía es opcional y propensa a errores de callback hell, mientras que Rust’s async/await promueve código legible y seguro.

Handlers pueden recibir extractores como argumentos, permitiendo acceso a datos de la solicitud de manera tipada. Por ejemplo, un handler que extrae el cuerpo de una solicitud POST:

use axum::{extract::Json, response::IntoResponse};

async fn create_item(Json(payload): Json<serde_json::Value>) -> impl IntoResponse {
    // Procesamiento asíncrono del payload
    StatusCode::CREATED
}

Un detalle sutil es el manejo de errores: handlers que devuelven Result se convierten automáticamente en respuestas HTTP con códigos de error si fallan, gracias a la trait IntoResponse implementada para Result. Casos borde incluyen timeouts en operaciones asíncronas, que se gestionan con tokio::time::timeout(), asegurando que el servidor no quede colgado indefinidamente.

JSON con serde

La serialización y deserialización de JSON en Axum se integra perfectamente con el crate serde, permitiendo el intercambio de datos estructurados en APIs REST. Serde proporciona traits como Serialize y Deserialize para tipos personalizados, y Axum los utiliza en extractores y respuestas para manejar payloads JSON de forma automática.

Para definir una estructura serializable:

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct Item {
    id: u32,
    name: String,
}

Un handler que responde con JSON podría ser:

use axum::Json;

async fn get_item() -> Json<Item> {
    Json(Item { id: 1, name: "Ejemplo".to_string() })
}

Aquí, Json envuelve el tipo y lo convierte en una respuesta HTTP con cabecera Content-Type: application/json. Para extraer JSON de una solicitud:

async fn post_item(Json(item): Json<Item>) {
    // Lógica asíncrona con el item
}

Serde maneja validaciones implícitas mediante atributos como #[serde(rename = "fieldName")] para mapeo de campos, y errores de deserialización resultan en respuestas 400 Bad Request automáticas. En comparación con JSON en Java (usando Jackson), Serde es más ligero y flexible, soportando derivación automática de traits sin anotaciones excesivas. Casos borde incluyen tipos opcionales con Option<T>, que se serializan como null si ausentes, y el manejo de enums para variantes discriminadas en JSON.

La integración con Axum asegura que no se requiera boilerplate manual para parsing, diferenciándose de enfoques en C++ donde bibliotecas como nlohmann/json exigen más código explícito.

Extractor Path/State

Los extractores en Axum permiten acceder a partes específicas de la solicitud HTTP de manera tipada y segura. El extractor Path captura segmentos dinámicos de la URL, mientras que State inyecta estado compartido en handlers, como conexiones a bases de datos.

Para Path, se define en el router con placeholders como /:id:

.route("/:id", get(get_by_id))

async fn get_by_id(Path(id): Path<u32>) {
    // Uso del id extraído
}

Path deserializa el segmento en el tipo especificado, fallando con 400 si no coincide. Un detalle importante es el soporte para tuplas en paths complejos, como Path((user_id, item_id)): Path<(u32, u32)> para rutas como /users/:user_id/items/:item_id.

El extractor State se usa para compartir datos globales:

use axum::extract::State;
use std::sync::Arc;

#[derive(Clone)]
struct AppState {
    db: Arc<String>, // Simulación de estado
}

let state = AppState { db: Arc::new("conexión".to_string()) };
let app = Router::new()
    .route("/", get(handler))
    .with_state(state);

async fn handler(State(state): State<AppState>) {
    // Acceso a state.db
}

State debe ser Clone para su propagación segura en entornos asíncronos, y su ausencia genera errores en tiempo de compilación. En contraste con state management en frameworks como Django, donde el estado es global y propenso a race conditions, Axum’s State aprovecha Rust’s ownership para garantizar seguridad.

Casos borde incluyen extracción fallida, que se maneja con responses personalizadas mediante FromRequest, aunque para usos básicos, los extractores built-in cubren la mayoría de escenarios.

Proyecto completo: API REST de tareas (To-Do)

Para ilustrar la integración de los conceptos anteriores, se presenta una API REST completa para gestionar tareas (To-Do). El proyecto utiliza Axum para el router, handlers asíncronos, Serde para JSON, y extractores Path y State. Se estructura en un crate de Cargo con dependencias mínimas.

Estructura de carpetas:

todo-api/
├── Cargo.toml
├── src/
│   ├── main.rs
│   └── lib.rs  // Opcional, pero aquí se incluye para modularidad

Contenido de Cargo.toml:

[package]
name = "todo-api"
version = "0.1.0"
edition = "2021"

[dependencies]
axum = "0.6"
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tower-http = { version = "0.3", features = ["trace"] }  # Para logging básico

Código completo en src/main.rs:

use axum::{
    extract::{Path, State},
    http::StatusCode,
    response::IntoResponse,
    routing::{delete, get, post},
    Json, Router,
};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::net::SocketAddr;
use std::sync::{Arc, Mutex};

#[derive(Clone)]
struct AppState {
    tasks: Arc<Mutex<HashMap<u32, Task>>>,
}

#[derive(Serialize, Deserialize, Clone)]
struct Task {
    id: u32,
    title: String,
    completed: bool,
}

#[tokio::main]
async fn main() {
    let state = AppState {
        tasks: Arc::new(Mutex::new(HashMap::new())),
    };

    let app = Router::new()
        .route("/tasks", get(list_tasks))
        .route("/tasks", post(create_task))
        .route("/tasks/:id", get(get_task))
        .route("/tasks/:id", delete(delete_task))
        .with_state(state);

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    axum::Server::bind(&addr)
        .serve(app.into_make_service())
        .await
        .unwrap();
}

async fn list_tasks(State(state): State<AppState>) -> Json<Vec<Task>> {
    let tasks = state.tasks.lock().unwrap();
    Json(tasks.values().cloned().collect())
}

async fn create_task(
    State(state): State<AppState>,
    Json(mut task): Json<Task>,
) -> impl IntoResponse {
    let mut tasks = state.tasks.lock().unwrap();
    let id = tasks.len() as u32 + 1;
    task.id = id;
    tasks.insert(id, task.clone());
    (StatusCode::CREATED, Json(task))
}

async fn get_task(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> impl IntoResponse {
    let tasks = state.tasks.lock().unwrap();
    match tasks.get(&id) {
        Some(task) => Ok(Json(task.clone())),
        None => Err(StatusCode::NOT_FOUND),
    }
}

async fn delete_task(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> impl IntoResponse {
    let mut tasks = state.tasks.lock().unwrap();
    if tasks.remove(&id).is_some() {
        StatusCode::NO_CONTENT
    } else {
        StatusCode::NOT_FOUND
    }
}

Este proyecto implementa endpoints para listar, crear, obtener y eliminar tareas, utilizando un HashMap en memoria como estado compartido. El servidor se ejecuta en localhost:3000 y maneja solicitudes asíncronas. Para producción, se recomendaría reemplazar el almacenamiento en memoria por una base de datos persistente, aunque eso excede el alcance de este ejemplo básico.

Con estos fundamentos en redes y servidores HTTP mediante Axum, el siguiente capítulo explorará patrones de concurrencia avanzada para escalar aplicaciones distribuidas.

Dejar un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Scroll al inicio