0Pricing
Learn Rust Coding · Lezione

Endpoint e modelli

Route e dati

Endpoint e modelli è una lezione Learn Rust Coding gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Learn Rust Coding, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Learn Rust Coding include 4 lezioni in totale.

Route e modelli di dati

Un'API è definita dai suoi endpoint (URL e metodi HTTP) e dai modelli (strutture dei dati) che vi transitano. In questa lezione definirete i modelli delle richieste e delle risposte con serde e collegherete route in stile CRUD in Axum.

Definire un modello

Un modello è una semplice struct Rust. Derivate Serialize per trasformarlo in JSON nelle risposte e Deserialize per analizzarlo nei body delle richieste. I nomi dei campi corrispondono direttamente alle chiavi JSON.

use serde::{Serialize, Deserialize};

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

Separare i tipi di richiesta e risposta

I client non dovrebbero inviare l'id assegnato dal server quando creano una risorsa. Usate una struct di input separata per il body della richiesta e il modello completo per le risposte. In questo modo il contratto è chiaro e si impedisce ai client di impostare campi che non dovrebbero modificare.

use serde::Deserialize;

#[derive(Deserialize)]
struct CreateTodo {
    title: String,
}
// The handler assigns the id and sets done = false.

GET: elencare le risorse

Un handler GET /todos restituisce l'intera raccolta come array JSON. Legge lo stato condiviso, estrae rapidamente una copia dei dati dal lock e la racchiude in Json.

use axum::{extract::State, Json};
use std::sync::{Arc, Mutex};

type Store = Arc<Mutex<Vec<Todo>>>;
#[derive(Clone, serde::Serialize)]
struct Todo { id: u32, title: String, done: bool }

async fn list_todos(State(store): State<Store>) -> Json<Vec<Todo>> {
    let todos = store.lock().unwrap().clone();
    Json(todos)
}

POST: creare una risorsa

Un handler POST /todos legge il body JSON con l'estrattore Json, assegna un nuovo id, salva l'elemento e lo restituisce con lo stato 201 Created. La tupla (StatusCode, Json<T>) consente di impostare sia lo stato sia il body.

use axum::{extract::State, Json, http::StatusCode};

async fn create_todo(
    State(store): State<Store>,
    Json(input): Json<CreateTodo>,
) -> (StatusCode, Json<Todo>) {
    let mut todos = store.lock().unwrap();
    let id = todos.len() as u32 + 1;
    let todo = Todo { id, title: input.title, done: false };
    todos.push(todo.clone());
    (StatusCode::CREATED, Json(todo))
}

Parametri del percorso

Per recuperare una singola risorsa, catturate una parte dell'URL con un parametro del percorso. Dichiaratelo nella route come /todos/{id} ed estraetelo con l'estrattore Path. Il tipo richiesto, in questo caso u32, viene analizzato automaticamente.

use axum::extract::{Path, State};
use axum::{Json, http::StatusCode};

async fn get_todo(
    State(store): State<Store>,
    Path(id): Path<u32>,
) -> Result<Json<Todo>, StatusCode> {
    let todos = store.lock().unwrap();
    match todos.iter().find(|t| t.id == id) {
        Some(t) => Ok(Json(t.clone())),
        None => Err(StatusCode::NOT_FOUND),
    }
}

Parametri di query

Il filtraggio e la paginazione usano la stringa di query, ad esempio /todos?done=true. Catturatela con l'estrattore Query in una struct Deserialize. Per i campi facoltativi usate Option, così l'assenza dei parametri non è un problema.

use axum::extract::{Query, State};
use axum::Json;
use serde::Deserialize;

#[derive(Deserialize)]
struct Filter { done: Option<bool> }

async fn filtered(
    State(store): State<Store>,
    Query(f): Query<Filter>,
) -> Json<Vec<Todo>> {
    let todos = store.lock().unwrap();
    let out = todos.iter()
        .filter(|t| f.done.map_or(true, |d| t.done == d))
        .cloned().collect();
    Json(out)
}

PUT e DELETE

L'aggiornamento usa PUT /todos/{id} con un body; l'eliminazione usa DELETE /todos/{id}. Entrambi cercano l'elemento tramite id e restituiscono 404 se non viene trovato. In genere, in caso di successo, Delete restituisce 204 No Content.

use axum::extract::{Path, State};
use axum::http::StatusCode;

async fn delete_todo(
    State(store): State<Store>,
    Path(id): Path<u32>,
) -> StatusCode {
    let mut todos = store.lock().unwrap();
    let before = todos.len();
    todos.retain(|t| t.id != id);
    if todos.len() < before { StatusCode::NO_CONTENT }
    else { StatusCode::NOT_FOUND }
}

Collegare le route

Registrate ogni handler nel router. Raggruppate i metodi sui percorsi condivisi: /todos gestisce l'elenco e la creazione, mentre /todos/{id} gestisce il recupero, l'aggiornamento e l'eliminazione. Collegate l'archivio condiviso con .with_state.

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

fn build(store: Store) -> Router {
    Router::new()
        .route("/todos", get(list_todos).post(create_todo))
        .route("/todos/{id}",
            get(get_todo).delete(delete_todo))
        .with_state(store)
}

Convalidare l'input

Non fidatevi mai dei dati del client. Controllateli all'interno dell'handler e restituite 400 Bad Request quando non sono validi. In questo caso rifiutiamo un titolo vuoto prima di salvare qualsiasi cosa, impedendo ai dati non validi di entrare nel sistema.

use axum::{Json, extract::State, http::StatusCode};

async fn create_validated(
    State(store): State<Store>,
    Json(input): Json<CreateTodo>,
) -> Result<(StatusCode, Json<Todo>), StatusCode> {
    if input.title.trim().is_empty() {
        return Err(StatusCode::BAD_REQUEST);
    }
    let mut todos = store.lock().unwrap();
    let id = todos.len() as u32 + 1;
    let todo = Todo { id, title: input.title, done: false };
    todos.push(todo.clone());
    Ok((StatusCode::CREATED, Json(todo)))
}

Risposte di errore coerenti

Restituire solo i codici di stato funziona, ma le API di produzione restituiscono anche un body JSON con l'errore. Un approccio comune consiste nell'usare un enum di errore personalizzato che implementa IntoResponse, associando ogni variante a uno stato e a un messaggio. In questo modo i client ricevono errori prevedibili e leggibili dalle macchine.

use axum::response::{IntoResponse, Response};
use axum::http::StatusCode;
use axum::Json;
use serde_json::json;

enum ApiError { NotFound, BadRequest(String) }

impl IntoResponse for ApiError {
    fn into_response(self) -> Response {
        let (status, msg) = match self {
            ApiError::NotFound => (StatusCode::NOT_FOUND, "not found".to_string()),
            ApiError::BadRequest(m) => (StatusCode::BAD_REQUEST, m),
        };
        (status, Json(json!({ "error": msg }))).into_response()
    }
}

Verifica rapida

Verificate la vostra comprensione di endpoint e modelli.

Riepilogo

Avete definito endpoint e modelli:

  • I modelli sono struct che derivano Serialize/Deserialize; usate tipi di input separati.
  • Json, Path, Query e State estraggono i dati dalle richieste.
  • Associare le operazioni CRUD a GET/POST/PUT/DELETE con codici di stato appropriati.
  • Convalidate l'input e restituite 400 in presenza di dati non validi.
  • Un tipo di errore personalizzato che implementa IntoResponse fornisce errori JSON coerenti.

Domande Frequenti

La lezione «Endpoint e modelli» è gratuita?

Sì — il testo completo di «Endpoint e modelli» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Learn Rust Coding, passa a CoddyKit PRO. Il corso Learn Rust Coding include 4 lezioni in totale.

Cosa imparerò in «Endpoint e modelli»?

Route e dati Eserciti Learn Rust Coding con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Learn Rust Coding?

Non è richiesta alcuna esperienza precedente. Learn Rust Coding su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.

Quanto tempo richiede la lezione «Endpoint e modelli»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Learn Rust Coding?

Sì. Ogni lezione Learn Rust Coding include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Configurazione del progetto
  2. Endpoint e modelli
  3. Integrazione con il database
  4. Test dell'API
← Torna a Learn Rust Coding