二、技術棧與版本

三、項目初始化與結構

# 安裝 Shuttle CLI
cargo install cargo-shuttle

# 創建項目
cargo shuttle init --name shuttle-example-axum
cd shuttle-example-axum

骨架：

src/

├── main.rs      # 入口 + 路由

├── db.rs        # 數據庫連接

├── models.rs    # 實體與 JSON

└── migrations.sql # 建表腳本

四、數據庫與遷移：一行注解搞定

① 注解獲取連接池

use shuttle_shared_db::Postgres;
use sqlx::PgPool;

#[shuttle_runtime::main]
async fn axum(
    #[Postgres] pool: PgPool,   // ← 自動注入
) -> shuttle_axum::ShuttleAxum {
    // 運行遷移
    sqlx::migrate!()
        .run(&pool)
        .await
        .expect("migrate failed");

    let state = AppState { db: pool };
    Ok(router(state).into())
}

② 遷移文件 migrations.sql

CREATE TABLE IF NOT EXISTS records (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT NOT NULL
);

?? AI 審查
把「SQL 注入風險」提交評審？「代碼審查助手」可自動檢查參數綁定、拼接語句，提前發現 80% 潛在 Bug！

五、模型與 JSON：自動映射

// src/models.rs
use serde::{Deserialize, Serialize};
use sqlx::FromRow;

#[derive(Debug, Serialize, Deserialize, FromRow)]
pub struct Record {
    pub id: i32,
    pub name: String,
    pub email: String,
}

#[derive(Debug, Deserialize)]
pub struct CreateRecord {
    pub name: String,
    pub email: String,
}

#[derive(Debug, Deserialize)]
pub struct UpdateRecord {
    pub name: Option<String>,
    pub email: Option<String>,
}

六、路由與業務邏輯

① 共享狀態

// src/main.rs
use axum::{
    extract::{Path, State, Json},
    http::StatusCode,
    response::IntoResponse,
    routing::{get, post, put, delete},
    Router,
};
use sqlx::PgPool;

#[derive(Clone)]
struct AppState {
    db: PgPool,
}

async fn create_record(
    State(state): State<AppState>,
    Json(payload): Json<CreateRecord>,
) -> impl IntoResponse {
    let rec = sqlx::query_as!(
        Record,
        "INSERT INTO records (name, email) VALUES ($1, $2) RETURNING *",
        payload.name, payload.email
    )
    .fetch_one(&state.db)
    .await
    .unwrap();
    (StatusCode::CREATED, Json(rec))
}

② 動態路徑與參數綁定

async fn get_record_by_id(
    State(state): State<AppState>,
    Path(id): Path<i32>,
) -> impl IntoResponse {
    let rec = sqlx::query_as!(
        Record,
        "SELECT * FROM records WHERE id = $1",
        id
    )
    .fetch_optional(&state.db)
    .await
    .unwrap();

    match rec {
        Some(r) => (StatusCode::OK, Json(r)),
        None => (StatusCode::NOT_FOUND, Json("")),
    }
}

③ 部分更新（PATCH）

async fn update_record(
    State(state): State<AppState>,
    Path(id): Path<i32>,
    Json(payload): Json<UpdateRecord>,
) -> impl IntoResponse {
    // 動態構建 SET 子句
    let mut sql = String::from("UPDATE records SET ");
    let mut args: Vec<String> = vec![];
    if let Some(name) = payload.name {
        sql.push_str("name = $1,");
        args.push(name);
    }
    if let Some(email) = payload.email {
        sql.push_str("email = $2,");
        args.push(email);
    }
    sql.truncate(sql.len() - 1); // 去掉末尾逗號
    sql.push_str(" WHERE id = $3 RETURNING *");

    let rec = sqlx::query_as::<_, Record>(&sql)
        .bind(args.get(0).unwrap_or(&"".to_string()))
        .bind(args.get(1).unwrap_or(&"".to_string()))
        .bind(id)
        .fetch_one(&state.db)
        .await
        .unwrap();
    (StatusCode::OK, Json(rec))
}

? AI 補救
把「動態 SQL 拼接」寫進注釋太麻煩？用「代碼文檔生成器」提示詞，自動在函數頭部生成標準注釋，提醒后續接入 sqlx-query-builder，文檔一鍵達標！

七、路由匯總

fn router(state: AppState) -> Router {
    Router::new()
        .route("/records", post(create_record).get(list_records))
        .route("/records/:id", get(get_record_by_id).put(update_record).delete(delete_record))
        .with_state(state)
}

八、部署與測試

① 本地運行

cargo shuttle run
# 默認端口 8000

② 一鍵部署

cargo shuttle deploy --allow-dirty
# 自動生成域名：https://shuttle-example-axum.shuttleapp.rs

③ 快速驗證

# 新增
curl -X POST https://<your-domain>.shuttleapp.rs/records \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"alice@example.com"}'

# 查詢
curl https://<your-domain>.shuttleapp.rs/records/1

九、擴展方向

十、總結與下一步

通過本教程，你已掌握：

• Shuttle 零運維部署流程
• Axum 異步路由與狀態共享
• SQLx 編譯時安全查詢
• 動態 SQL 構建與錯誤處理

下一步可添加認證、分頁、OpenAPI 文檔等功能，打造生產級后端。祝編碼愉快！

今晚就 push 到 GitHub，明天就能用 Shuttle 一鍵上線！??

原文鏈接: https://www.shuttle.dev/blog/2024/01/31/write-a-rest-api-rust