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 の移転では、利用するクライアントで事前に確認してください。
運用上の注意点
-
308 はキャッシュされやすい
- 恒久リダイレクトはブラウザや CDN に長く残る場合があります。誤った宛先を配信すると、サーバー側を直しても利用者の手元で残り続けます。
- 初回は
Redirect::temporary(307)で動作確認し、問題なければpermanentに切り替える手順が安全です。
-
リダイレクトチェーンを作らない
-
/a→/b→/cのように連鎖させると、クローラーの評価や表示速度に不利です。旧 URL から最終宛先へ 1 ホップで飛ばしてください。
-
-
古いクライアントとの互換性
- 308 は RFC 7538 で定義され、現在は RFC 9110 に統合されています。古い HTTP クライアントでは未対応の可能性があります。そうした相手がいる API では 301 との使い分けを検討してください。
-
GET のみの HTML ページ
- 301 でも実害は少ないです。メソッド維持が必要かどうかで選べば十分です。
まとめ
- axum では
Redirect::permanent(...)の 1 行で 308 を返せる - パスパラメータ、クエリ、ワイルドカード、ホスト正規化の 5 パターンを押さえれば、実務のリダイレクトはほぼ賄える
- 宛先は固定プレフィックスやホスト定数から組み立て、オープンリダイレクトを避ける
- 初回は 307 で確認し、問題なければ 308 にするとキャッシュ事故を避けられる
URL 移行は、検索流入やサイテーションの評価にも関わる地味に重要な作業です。AI 検索や生成エンジン経由の流入を意識する場合も、旧 URL を適切なステータスコードで新 URL へ接続しておくことが、土台として役立ちます。
ライセンス
本記事で使用したクレートのライセンスは以下のとおりです(各リポジトリの記載に基づきます)。
- axum: MIT
- tokio: MIT
- tower: MIT
参考リンク
- axum 公式ドキュメント
Redirect: https://docs.rs/axum/latest/axum/response/struct.Redirect.html - axum GitHub リポジトリ: https://github.com/tokio-rs/axum
- RFC 9110 HTTP Semantics (15.4 Redirection 3xx): https://www.rfc-editor.org/rfc/rfc9110.html#name-redirection-3xx
- RFC 7538 The Hypertext Transfer Protocol Status Code 308 (Permanent Redirect): https://www.rfc-editor.org/rfc/rfc7538
- MDN: 308 Permanent Redirect: https://developer.mozilla.org/ja/docs/Web/HTTP/Status/308
✍️ 本記事の著者: 合同会社ジモラボ
ジモラボは、八王子を拠点に AI を活用した SaaS を多数開発しています。
- 🌐 公式サイト: https://locallab.jp
- 🔍 AI SEO 最適化 SaaS: lookupai.jp
- 📺 YouTube: @locallab_llc
- ✉️ お問い合わせ: info@locallab.jp