0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Rust + axum で 308 Permanent Redirect を 5 パターンで最短実装する【コピペで動く】

0
Posted at

TL;DR

  • axum の Redirect::permanent は 308 Permanent Redirect を返す(Redirect::temporary は 307、Redirect::to は 303)
  • 308 は 301 と違い HTTP メソッドとボディが維持されるので、POST を含む API の恒久移転でも安全に使える
  • 固定パス、パスパラメータ、クエリ維持、プレフィックス移行、www 正規化の 5 パターンを最小コードで示す
  • 308 はブラウザに強くキャッシュされる。本番投入前は 307 で動作確認するのがおすすめ

動作確認の前提は次のとおりです。

  • Rust 1.80 以降
  • axum 0.8 系
  • tokio 1.x

axum 0.7 以前を使う場合は、パスパラメータの書式が {slug} ではなく :slug、ワイルドカードが {*rest} ではなく *rest になります。

背景

サイトのリニューアルや API のバージョン移行では、旧 URL から新 URL への恒久リダイレクトが必ず必要になります。SEO の評価を引き継ぐにも、外部から張られたリンクを死なせないにも、正しいステータスコードの選択が重要です。

よく使われるリダイレクトのステータスコードは次の 4 つです。

コード 意味 メソッド維持 恒久性
301 Moved Permanently 維持されない場合がある(POST → GET に変わる実装が多い) 恒久
302 Found 維持されない場合がある 一時
307 Temporary Redirect 維持される 一時
308 Permanent Redirect 維持される 恒久

301 は歴史的経緯で、多くのクライアントが POST を GET に書き換えます。GET しか来ない HTML ページなら 301 で問題ありません。ただ、API エンドポイントの移転ではメソッドの書き換えが事故の元です。そこで「恒久かつメソッド維持」を明示できる 308 が便利になります。

axum では axum::response::Redirect がこの 4 種類への対応を持っています。

axum の API ステータス
Redirect::to(uri) 303 See Other
Redirect::temporary(uri) 307 Temporary Redirect
Redirect::permanent(uri) 308 Permanent Redirect

検証 / 実装

準備

# Cargo.toml
[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }

[dev-dependencies]
tower = { version = "0.5", features = ["util"] }

パターン 1: 固定パスの恒久移転(最小構成)

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

fn app() -> Router {
    Router::new()
        .route("/old", get(|| async { Redirect::permanent("/new") }))
        .route("/new", get(|| async { "this is new" }))
}

#[tokio::main]
async fn main() {
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
        .await
        .unwrap();
    axum::serve(listener, app()).await.unwrap();
}

クロージャを 1 つ書くだけで 308 になります。

パターン 2: パスパラメータを引き継ぐ

/blog/{slug} を /articles/{slug} に移す例です。

use axum::{extract::Path, response::Redirect};

async fn blog_to_articles(Path(slug): Path<String>) -> Redirect {
    Redirect::permanent(&format!("/articles/{slug}"))
}

// Router::new().route("/blog/{slug}", get(blog_to_articles))

Path は URL デコード済みの文字列を返します。リダイレクト先は必ず自サイト内の固定プレフィックス(/articles/)から始め、ユーザー入力だけで宛先全体を組み立てないでください。オープンリダイレクトを防ぐための基本です。

パターン 3: クエリ文字列を維持する

検索 URL の移転では、?q=rust&page=2 を落とさないようにします。

use axum::{http::Uri, response::Redirect};

async fn find_to_search(uri: Uri) -> Redirect {
    let to = match uri.query() {
        Some(q) => format!("/search?{q}"),
        None => "/search".to_string(),
    };
    Redirect::permanent(&to)
}

// Router::new().route("/find", get(find_to_search))

uri.query() はパーセントエンコードされた生のクエリを返します。そのまま連結すれば二重エンコードは起きません。

パターン 4: プレフィックス配下を丸ごと移行する

/docs/... 配下をすべて /v2/docs/... に移す例です。

use axum::{extract::Path, response::Redirect};

async fn docs_to_v2(Path(rest): Path<String>) -> Redirect {
    Redirect::permanent(&format!("/v2/docs/{rest}"))
}

// Router::new().route("/docs/{*rest}", get(docs_to_v2))

{*rest} はスラッシュを含む残りのパス全体にマッチします。

パターン 5: www 付きを apex ドメインに正規化する(ミドルウェア)

ホスト名の正規化は、ルートごとではなくミドルウェアで一括処理するのが楽です。

use axum::{
    extract::Request,
    http::header,
    middleware::{self, Next},
    response::{IntoResponse, Redirect, Response},
    Router,
};

const CANONICAL: &str = "example.com";

async fn canonical_host(req: Request, next: Next) -> Response {
    let host = req
        .headers()
        .get(header::HOST)
        .and_then(|v| v.to_str().ok())
        .unwrap_or("");

    if host == format!("www.{CANONICAL}") {
        let pq = req
            .uri()
            .path_and_query()
            .map(|p| p.as_str())
            .unwrap_or("/");
        return Redirect::permanent(&format!("https://{CANONICAL}{pq}")).into_response();
    }
    next.run(req).await
}

fn with_canonical(router: Router) -> Router {
    router.layer(middleware::from_fn(canonical_host))
}

Host ヘッダーはクライアントが自由に書き換えられます。そのため「www. を剥がして使う」のではなく、許可するホスト名を定数で固定して完全一致で比較しています。リバースプロキシ配下では、プロキシが付与する X-Forwarded-Host などの扱いを自分の構成に合わせて確認してください。

テストを書く

ステータスと Location ヘッダーは、サーバーを起動せずに tower::ServiceExt::oneshot で検証できます。

#[cfg(test)]
mod tests {
    use super::*;
    use axum::{
        body::Body,
        http::{header, Request, StatusCode},
    };
    use tower::ServiceExt;

    #[tokio::test]
    async fn old_redirects_with_308() {
        let res = app()
            .oneshot(Request::get("/old").body(Body::empty()).unwrap())
            .await
            .unwrap();

        assert_eq!(res.status(), StatusCode::PERMANENT_REDIRECT);
        assert_eq!(res.headers()[header::LOCATION], "/new");
    }
}

StatusCode::PERMANENT_REDIRECT が 308 です。

結果

cargo run で起動して curl -i で叩くと、次のようなレスポンスになります(出力は一例で、ヘッダーの並びは環境で異なります)。

$ curl -i http://127.0.0.1:3000/old
HTTP/1.1 308 Permanent Redirect
location: /new
content-length: 0

POST でもメソッドが維持されるかは、-L と -X POST で確認できます。

# 308 なら、リダイレクト先にも POST のまま届く
$ curl -i -L -X POST --data 'a=1' http://127.0.0.1:3000/old

307 / 308 では、クライアントは同じメソッドとボディでリダイレクト先に再送します。ただし、実際にどう動くかはクライアント実装に依存します。重要な API の移転では、利用するクライアントで事前に確認してください。

運用上の注意点

  1. 308 はキャッシュされやすい
    • 恒久リダイレクトはブラウザや CDN に長く残る場合があります。誤った宛先を配信すると、サーバー側を直しても利用者の手元で残り続けます。
    • 初回は Redirect::temporary(307)で動作確認し、問題なければ permanent に切り替える手順が安全です。
  2. リダイレクトチェーンを作らない
    • /a → /b → /c のように連鎖させると、クローラーの評価や表示速度に不利です。旧 URL から最終宛先へ 1 ホップで飛ばしてください。
  3. 古いクライアントとの互換性
    • 308 は RFC 7538 で定義され、現在は RFC 9110 に統合されています。古い HTTP クライアントでは未対応の可能性があります。そうした相手がいる API では 301 との使い分けを検討してください。
  4. GET のみの HTML ページ
    • 301 でも実害は少ないです。メソッド維持が必要かどうかで選べば十分です。

まとめ

  • axum では Redirect::permanent(...) の 1 行で 308 を返せる
  • パスパラメータ、クエリ、ワイルドカード、ホスト正規化の 5 パターンを押さえれば、実務のリダイレクトはほぼ賄える
  • 宛先は固定プレフィックスやホスト定数から組み立て、オープンリダイレクトを避ける
  • 初回は 307 で確認し、問題なければ 308 にするとキャッシュ事故を避けられる

URL 移行は、検索流入やサイテーションの評価にも関わる地味に重要な作業です。AI 検索や生成エンジン経由の流入を意識する場合も、旧 URL を適切なステータスコードで新 URL へ接続しておくことが、土台として役立ちます。

ライセンス

本記事で使用したクレートのライセンスは以下のとおりです(各リポジトリの記載に基づきます)。

  • axum: MIT
  • tokio: MIT
  • tower: MIT

参考リンク


✍️ 本記事の著者: 合同会社ジモラボ

ジモラボは、八王子を拠点に AI を活用した SaaS を多数開発しています。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?