Rust Axum中介軟體鑑權實戰：從JWT到RBAC的6種生產模式
编程语言
Rust Web服務的鑑權，為什麼總是踩坑
你寫了個Axum介面，裸奔上線；你加了JWT校驗，發現token過期後使用者直接401；你想做RBAC許可權控制，發現Axum的中介軟體裡拿不到使用者角色；你加了限流，發現未認證請求也在消耗配額。2026年，Axum 0.8已經提供了FromRequestParts提取器、Tower Layer中介軟體、以及型別安全的狀態管理——但鑑權這件事，從來不是框架能幫你做完的。
本文將從JWT校驗出發，帶你完成JWT認證→API Key認證→RBAC許可權控制→限流防護→會話管理→生產級鑑權服務的6種實戰模式，讓Axum的鑑權從"能跑"變成"能抗"。
核心概念
| 概念 | 說明 |
|---|---|
| FromRequestParts | Axum提取器trait，從請求Parts中提取認證資訊 |
| JWT (JSON Web Token) | 無狀態令牌，包含使用者身份與過期時間的簽名資料 |
| API Key | 透過Header傳遞的密鑰，適合服務間呼叫 |
| RBAC | 基於角色的存取控制，使用者→角色→許可權三級模型 |
| Tower Layer | 中介軟體抽象層，用於組合認證、限流等橫切關注點 |
| Rate Limiting | 限流，防止介面被惡意刷量 |
| Session | 有狀態會話，服務端儲存登入狀態（Redis等） |
| Claims | JWT載荷中的宣告資料（sub/exp/role等） |
鑑權請求流程
請求鑑權流程：
1. 客戶端傳送請求，攜帶Authorization Header或API Key
2. 中介軟體/Extractor提取認證憑證
3. 驗證憑證有效性（簽名校驗/過期檢查/密鑰匹配）
4. 構建使用者上下文（UserId/Role/Permissions）
5. RBAC中介軟體檢查使用者是否有權存取當前路由
6. 限流中介軟體檢查請求頻率
7. Handler執行業務邏輯，可透過State存取使用者上下文
8. 響應返回客戶端
問題分析：Axum鑑權開發的5大挑戰
- JWT校驗與使用者上下文脫節：中介軟體裡校驗了token，但Handler裡拿不到使用者資訊，只能重新解析一遍
- 多種認證方式難以共存：JWT和API Key要同時支援，中介軟體寫成了if-else麵條程式碼
- RBAC許可權模型設計混亂：角色和許可權用字串硬編碼，新增許可權要改十幾個地方
- 限流與認證順序衝突：限流在認證之前，未認證請求浪費限流配額；限流在認證之後，惡意請求直接打到認證層
- 會話管理缺乏生產方案：JWT無狀態但無法主動撤銷，Session有狀態但Redis連線池和過期清理都是坑
分步實操：6種生產級鑑權模式
模式1：JWT認證中介軟體與FromRequestParts
use axum::extract::{FromRequestParts, Request};
use axum::http::request::Parts;
use axum::response::{IntoResponse, Response};
use axum::middleware::{Next, from_fn};
use axum::{Json, Router, middleware, routing::get};
use jsonwebtoken::{decode, encode, DecodingKey, EncodingKey, Header, Validation};
use serde::{Deserialize, Serialize};
use chrono::{Utc, Duration};
use std::sync::Arc;
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct Claims {
pub sub: String,
pub role: String,
pub exp: i64,
pub iat: i64,
}
#[derive(Clone)]
pub struct AuthConfig {
pub jwt_secret: String,
pub jwt_expiration_hours: i64,
}
pub struct AppState {
pub auth_config: AuthConfig,
pub db: DbPool,
}
pub type SharedState = Arc<AppState>;
impl Claims {
pub fn new(user_id: &str, role: &str, expiration_hours: i64) -> Self {
let now = Utc::now();
Self {
sub: user_id.to_string(),
role: role.to_string(),
iat: now.timestamp(),
exp: (now + Duration::hours(expiration_hours)).timestamp(),
}
}
pub fn encode(&self, secret: &str) -> Result<String, jsonwebtoken::errors::Error> {
encode(
&Header::default(),
self,
&EncodingKey::from_secret(secret.as_bytes()),
)
}
pub fn decode(token: &str, secret: &str) -> Result<Self, jsonwebtoken::errors::Error> {
let token_data = decode::<Claims>(
token,
&DecodingKey::from_secret(secret.as_bytes()),
&Validation::default(),
)?;
Ok(token_data.claims)
}
}
use axum::extract::FromRequestParts;
use axum::http::StatusCode;
pub struct AuthUser {
pub user_id: String,
pub role: String,
}
#[axum::async_trait]
impl FromRequestParts<SharedState> for AuthUser {
type Rejection = AuthError;
async fn from_request_parts(
parts: &mut Parts,
state: &SharedState,
) -> Result<Self, Self::Rejection> {
let auth_header = parts
.headers
.get("authorization")
.and_then(|v| v.to_str().ok())
.ok_or(AuthError::MissingToken)?;
let token = auth_header
.strip_prefix("Bearer ")
.ok_or(AuthError::InvalidTokenFormat)?;
let claims = Claims::decode(token, &state.auth_config.jwt_secret)
.map_err(|_| AuthError::InvalidToken)?;
Ok(AuthUser {
user_id: claims.sub,
role: claims.role,
})
}
}
async fn protected_handler(
auth_user: AuthUser,
) -> Result<Json<serde_json::Value>, AuthError> {
Ok(Json(serde_json::json!({
"user_id": auth_user.user_id,
"role": auth_user.role,
})))
}
pub fn auth_router() -> Router<SharedState> {
Router::new()
.route("/me", get(protected_handler))
.route("/refresh", get(refresh_token))
}
async fn refresh_token(
auth_user: AuthUser,
State(state): State<SharedState>,
) -> Result<Json<serde_json::Value>, AuthError> {
let claims = Claims::new(
&auth_user.user_id,
&auth_user.role,
state.auth_config.jwt_expiration_hours,
);
let token = claims.encode(&state.auth_config.jwt_secret)?;
Ok(Json(serde_json::json!({ "token": token })))
}
模式2：API Key認證與Header提取
use axum::extract::FromRequestParts;
use axum::http::request::Parts;
use std::collections::HashMap;
use tokio::sync::RwLock;
#[derive(Debug, Clone)]
pub struct ApiKeyInfo {
pub key_id: String,
pub client_name: String,
pub permissions: Vec<String>,
pub rate_limit: u32,
}
pub struct ApiKeyState {
pub keys: Arc<RwLock<HashMap<String, ApiKeyInfo>>>,
}
pub struct AuthenticatedApi {
pub key_info: ApiKeyInfo,
}
#[axum::async_trait]
impl FromRequestParts<SharedState> for AuthenticatedApi {
type Rejection = AuthError;
async fn from_request_parts(
parts: &mut Parts,
state: &SharedState,
) -> Result<Self, Self::Rejection> {
let api_key = parts
.headers
.get("x-api-key")
.and_then(|v| v.to_str().ok())
.ok_or(AuthError::MissingApiKey)?;
let keys = state.api_key_state.keys.read().await;
let key_info = keys
.get(api_key)
.ok_or(AuthError::InvalidApiKey)?
.clone();
Ok(AuthenticatedApi { key_info })
}
}
async fn api_endpoint(
auth: AuthenticatedApi,
) -> Result<Json<serde_json::Value>, AuthError> {
Ok(Json(serde_json::json!({
"client": auth.key_info.client_name,
"permissions": auth.key_info.permissions,
})))
}
use axum::extract::FromRequestParts;
use axum::http::request::Parts;
pub enum AuthMethod {
Jwt(AuthUser),
ApiKey(AuthenticatedApi),
}
pub struct MultiAuth;
#[axum::async_trait]
impl FromRequestParts<SharedState> for AuthMethod {
type Rejection = AuthError;
async fn from_request_parts(
parts: &mut Parts,
state: &SharedState,
) -> Result<Self, Self::Rejection> {
if parts.headers.contains_key("x-api-key") {
let api_auth = AuthenticatedApi::from_request_parts(parts, state).await?;
Ok(AuthMethod::ApiKey(api_auth))
} else if parts.headers.contains_key("authorization") {
let jwt_auth = AuthUser::from_request_parts(parts, state).await?;
Ok(AuthMethod::Jwt(jwt_auth))
} else {
Err(AuthError::NoAuthMethod)
}
}
}
async fn multi_auth_handler(
auth: AuthMethod,
) -> Json<serde_json::Value> {
match auth {
AuthMethod::Jwt(user) => Json(serde_json::json!({
"method": "jwt",
"user_id": user.user_id,
})),
AuthMethod::ApiKey(api) => Json(serde_json::json!({
"method": "api_key",
"client": api.key_info.client_name,
})),
}
}
模式3：RBAC角色許可權控制與列舉許可權
use strum::{Display, EnumString};
use std::collections::HashSet;
#[derive(Debug, Clone, PartialEq, Eq, Hash, Display, EnumString)]
pub enum Permission {
#[strum(to_string = "users:read")]
UsersRead,
#[strum(to_string = "users:write")]
UsersWrite,
#[strum(to_string = "users:delete")]
UsersDelete,
#[strum(to_string = "products:read")]
ProductsRead,
#[strum(to_string = "products:write")]
ProductsWrite,
#[strum(to_string = "orders:read")]
OrdersRead,
#[strum(to_string = "orders:write")]
OrdersWrite,
#[strum(to_string = "admin:full")]
AdminFull,
}
#[derive(Debug, Clone, PartialEq, Eq, Display, EnumString)]
pub enum Role {
#[strum(to_string = "viewer")]
Viewer,
#[strum(to_string = "editor")]
Editor,
#[strum(to_string = "admin")]
Admin,
#[strum(to_string = "superadmin")]
SuperAdmin,
}
impl Role {
pub fn permissions(&self) -> HashSet<Permission> {
match self {
Role::Viewer => HashSet::from([
Permission::UsersRead,
Permission::ProductsRead,
Permission::OrdersRead,
]),
Role::Editor => HashSet::from([
Permission::UsersRead,
Permission::ProductsRead,
Permission::ProductsWrite,
Permission::OrdersRead,
Permission::OrdersWrite,
]),
Role::Admin => HashSet::from([
Permission::UsersRead,
Permission::UsersWrite,
Permission::ProductsRead,
Permission::ProductsWrite,
Permission::OrdersRead,
Permission::OrdersWrite,
]),
Role::SuperAdmin => HashSet::from([Permission::AdminFull]),
}
}
pub fn has_permission(&self, permission: &Permission) -> bool {
let perms = self.permissions();
perms.contains(&Permission::AdminFull) || perms.contains(permission)
}
}
use axum::extract::{FromRequestParts, Path};
use axum::http::request::Parts;
pub struct RequirePermission(pub Permission);
#[axum::async_trait]
impl FromRequestParts<SharedState> for RequirePermission {
type Rejection = AuthError;
async fn from_request_parts(
parts: &mut Parts,
state: &SharedState,
) -> Result<Self, Self::Rejection> {
let auth_user = AuthUser::from_request_parts(parts, state).await?;
let role: Role = auth_user.role.parse().map_err(|_| AuthError::InvalidRole)?;
let required = Permission::UsersWrite;
if !role.has_permission(&required) {
return Err(AuthError::Forbidden(
format!("Missing permission: {}", required),
));
}
Ok(RequirePermission(required))
}
}
async fn delete_user_handler(
auth_user: AuthUser,
Path(user_id): Path<String>,
) -> Result<StatusCode, AuthError> {
let role: Role = auth_user.role.parse().map_err(|_| AuthError::InvalidRole)?;
if !role.has_permission(&Permission::UsersDelete) {
return Err(AuthError::Forbidden("Missing users:delete permission".into()));
}
tracing::info!("Deleting user: {}", user_id);
Ok(StatusCode::NO_CONTENT)
}
模式4：限流中介軟體與Tower Layer
use axum::extract::Request;
use axum::middleware::Next;
use axum::response::Response;
use std::collections::HashMap;
use std::sync::Arc;
use std::time::Instant;
use tokio::sync::RwLock;
#[derive(Clone)]
pub struct RateLimitConfig {
pub max_requests: u32,
pub window_secs: u64,
}
#[derive(Debug)]
struct RateLimitEntry {
count: u32,
window_start: Instant,
}
#[derive(Clone)]
pub struct RateLimitState {
pub entries: Arc<RwLock<HashMap<String, RateLimitEntry>>>,
pub config: RateLimitConfig,
}
impl RateLimitState {
pub fn new(config: RateLimitConfig) -> Self {
Self {
entries: Arc::new(RwLock::new(HashMap::new())),
config,
}
}
pub async fn check_rate_limit(&self, key: &str) -> bool {
let mut entries = self.entries.write().await;
let now = Instant::now();
let entry = entries.entry(key.to_string()).or_insert(RateLimitEntry {
count: 0,
window_start: now,
});
if now.duration_since(entry.window_start).as_secs() > self.config.window_secs {
entry.count = 0;
entry.window_start = now;
}
entry.count += 1;
entry.count <= self.config.max_requests
}
}
pub async fn rate_limit_middleware(
request: Request,
next: Next,
) -> Result<Response, AuthError> {
let state = request
.extensions()
.get::<RateLimitState>()
.cloned()
.ok_or(AuthError::InternalServerError("Rate limit state not found".into()))?;
let key = request
.headers()
.get("x-api-key")
.and_then(|v| v.to_str().ok())
.or_else(|| {
request.headers()
.get("x-forwarded-for")
.and_then(|v| v.to_str().ok())
})
.unwrap_or("anonymous")
.to_string();
if !state.check_rate_limit(&key).await {
return Err(AuthError::RateLimited);
}
Ok(next.run(request).await)
}
use axum::Router;
use axum::middleware;
use tower::ServiceBuilder;
use tower_http::limit::RateLimitLayer;
use std::time::Duration;
pub fn create_rate_limited_router(state: SharedState) -> Router<SharedState> {
let rate_limit_state = RateLimitState::new(RateLimitConfig {
max_requests: 100,
window_secs: 60,
});
Router::new()
.route("/api/data", get(data_handler))
.layer(middleware::from_fn(rate_limit_middleware))
.layer(middleware::from_fn(auth_middleware))
.with_state(state)
}
pub fn create_tower_rate_limited_router(state: SharedState) -> Router<SharedState> {
Router::new()
.route("/api/data", get(data_handler))
.layer(
ServiceBuilder::new()
.layer(RateLimitLayer::new(100, Duration::from_secs(60)))
.into_inner(),
)
.with_state(state)
}
async fn data_handler() -> &'static str {
"OK"
}
模式5：會話管理與Redis後端
use redis::AsyncCommands;
use serde::{Deserialize, Serialize};
use uuid::Uuid;
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Session {
pub session_id: String,
pub user_id: String,
pub role: String,
pub created_at: i64,
pub expires_at: i64,
pub ip_address: Option<String>,
pub user_agent: Option<String>,
}
impl Session {
pub fn new(user_id: &str, role: &str, ttl_secs: i64, ip: Option<&str>, ua: Option<&str>) -> Self {
let now = Utc::now().timestamp();
Self {
session_id: Uuid::new_v4().to_string(),
user_id: user_id.to_string(),
role: role.to_string(),
created_at: now,
expires_at: now + ttl_secs,
ip_address: ip.map(|s| s.to_string()),
user_agent: ua.map(|s| s.to_string()),
}
}
pub fn is_expired(&self) -> bool {
Utc::now().timestamp() > self.expires_at
}
}
#[derive(Clone)]
pub struct SessionStore {
pub client: redis::Client,
pub ttl_secs: i64,
pub key_prefix: String,
}
impl SessionStore {
pub fn new(redis_url: &str, ttl_secs: i64) -> Result<Self, redis::RedisError> {
Ok(Self {
client: redis::Client::open(redis_url)?,
ttl_secs,
key_prefix: "session:".to_string(),
})
}
pub async fn create_session(&self, session: &Session) -> Result<(), redis::RedisError> {
let mut conn = self.client.get_multiplexed_async_connection().await?;
let key = format!("{}{}", self.key_prefix, session.session_id);
let value = serde_json::to_string(session).unwrap();
conn.set_ex(&key, value, self.ttl_secs as u64).await?;
Ok(())
}
pub async fn get_session(&self, session_id: &str) -> Result<Option<Session>, redis::RedisError> {
let mut conn = self.client.get_multiplexed_async_connection().await?;
let key = format!("{}{}", self.key_prefix, session_id);
let value: Option<String> = conn.get(&key).await?;
match value {
Some(v) => Ok(Some(serde_json::from_str(&v).unwrap())),
None => Ok(None),
}
}
pub async fn delete_session(&self, session_id: &str) -> Result<(), redis::RedisError> {
let mut conn = self.client.get_multiplexed_async_connection().await?;
let key = format!("{}{}", self.key_prefix, session_id);
conn.del(&key).await?;
Ok(())
}
pub async fn refresh_session(&self, session_id: &str) -> Result<(), redis::RedisError> {
let mut conn = self.client.get_multiplexed_async_connection().await?;
let key = format!("{}{}", self.key_prefix, session_id);
conn.expire(&key, self.ttl_secs as i64).await?;
Ok(())
}
}
use axum::extract::{FromRequestParts, Request};
use axum::http::request::Parts;
use axum::middleware::Next;
use axum::response::Response;
use axum::Extension;
pub struct SessionUser {
pub session: Session,
}
#[axum::async_trait]
impl FromRequestParts<SharedState> for SessionUser {
type Rejection = AuthError;
async fn from_request_parts(
parts: &mut Parts,
state: &SharedState,
) -> Result<Self, Self::Rejection> {
let cookie_header = parts
.headers
.get("cookie")
.and_then(|v| v.to_str().ok())
.ok_or(AuthError::MissingSession)?;
let session_id = extract_session_id(cookie_header)
.ok_or(AuthError::MissingSession)?;
let session = state
.session_store
.get_session(&session_id)
.await
.map_err(|_| AuthError::InternalServerError("Redis error".into()))?
.ok_or(AuthError::SessionExpired)?;
if session.is_expired() {
state.session_store.delete_session(&session_id).await.ok();
return Err(AuthError::SessionExpired);
}
state.session_store.refresh_session(&session_id).await.ok();
Ok(SessionUser { session })
}
}
fn extract_session_id(cookie_header: &str) -> Option<String> {
cookie_header
.split(';')
.find_map(|cookie| {
let mut parts = cookie.trim().splitn(2, '=');
let name = parts.next()?.trim();
if name == "session_id" {
Some(parts.next()?.trim().to_string())
} else {
None
}
})
}
async fn login_handler(
State(state): State<SharedState>,
Json(payload): Json<LoginRequest>,
) -> Result<Json<serde_json::Value>, AuthError> {
let user = state.db.verify_user(&payload.username, &payload.password).await
.ok_or(AuthError::InvalidCredentials)?;
let session = Session::new(
&user.id,
&user.role,
state.session_store.ttl_secs,
None,
None,
);
state.session_store.create_session(&session).await
.map_err(|_| AuthError::InternalServerError("Failed to create session".into()))?;
Ok(Json(serde_json::json!({
"session_id": session.session_id,
"expires_at": session.expires_at,
})))
}
async fn logout_handler(
session_user: SessionUser,
State(state): State<SharedState>,
) -> Result<StatusCode, AuthError> {
state.session_store
.delete_session(&session_user.session.session_id)
.await
.map_err(|_| AuthError::InternalServerError("Failed to delete session".into()))?;
Ok(StatusCode::NO_CONTENT)
}
模式6：生產級鑑權服務組合
use axum::{Router, routing::{get, post}, middleware, extract::State};
use tower::ServiceBuilder;
use tower_http::cors::{CorsLayer, Any};
use tower_http::trace::TraceLayer;
use std::time::Duration;
pub struct AppState {
pub auth_config: AuthConfig,
pub api_key_state: ApiKeyState,
pub rate_limit_state: RateLimitState,
pub session_store: SessionStore,
pub db: DbPool,
}
pub type SharedState = Arc<AppState>;
pub fn create_production_router(state: SharedState) -> Router {
let public_routes = Router::new()
.route("/auth/login", post(login_handler))
.route("/auth/register", post(register_handler))
.route("/health", get(health_check));
let jwt_protected = Router::new()
.route("/users/me", get(get_profile))
.route("/users/me", post(update_profile))
.route("/auth/refresh", get(refresh_token))
.layer(middleware::from_fn_with_state(
state.clone(),
jwt_auth_middleware,
));
let api_key_routes = Router::new()
.route("/api/v1/data", get(data_handler))
.route("/api/v1/reports", get(reports_handler))
.layer(middleware::from_fn_with_state(
state.clone(),
api_key_auth_middleware,
));
let admin_routes = Router::new()
.route("/admin/users", get(list_users_handler))
.route("/admin/users/{id}", post(delete_user_handler))
.layer(middleware::from_fn_with_state(
state.clone(),
admin_auth_middleware,
));
let session_routes = Router::new()
.route("/dashboard", get(dashboard_handler))
.route("/auth/logout", post(logout_handler))
.layer(middleware::from_fn_with_state(
state.clone(),
session_auth_middleware,
));
Router::new()
.merge(public_routes)
.nest("/api", jwt_protected)
.nest("/external", api_key_routes)
.nest("/manage", admin_routes)
.nest("/web", session_routes)
.layer(
ServiceBuilder::new()
.layer(TraceLayer::new_for_http())
.layer(CorsLayer::new().allow_origin(Any).allow_methods(Any).allow_headers(Any))
.into_inner(),
)
.with_state(state)
}
async fn jwt_auth_middleware(
State(state): State<SharedState>,
mut request: Request,
next: Next,
) -> Result<Response, AuthError> {
let auth_header = request.headers()
.get("authorization")
.and_then(|v| v.to_str().ok())
.ok_or(AuthError::MissingToken)?;
let token = auth_header
.strip_prefix("Bearer ")
.ok_or(AuthError::InvalidTokenFormat)?;
let claims = Claims::decode(token, &state.auth_config.jwt_secret)
.map_err(|_| AuthError::InvalidToken)?;
request.extensions_mut().insert(AuthUser {
user_id: claims.sub.clone(),
role: claims.role.clone(),
});
Ok(next.run(request).await)
}
async fn api_key_auth_middleware(
State(state): State<SharedState>,
mut request: Request,
next: Next,
) -> Result<Response, AuthError> {
let api_key = request.headers()
.get("x-api-key")
.and_then(|v| v.to_str().ok())
.ok_or(AuthError::MissingApiKey)?;
let keys = state.api_key_state.keys.read().await;
let key_info = keys.get(api_key).ok_or(AuthError::InvalidApiKey)?.clone();
if !state.rate_limit_state.check_rate_limit(&key_info.key_id).await {
return Err(AuthError::RateLimited);
}
request.extensions_mut().insert(key_info);
Ok(next.run(request).await)
}
async fn admin_auth_middleware(
State(state): State<SharedState>,
mut request: Request,
next: Next,
) -> Result<Response, AuthError> {
let auth_header = request.headers()
.get("authorization")
.and_then(|v| v.to_str().ok())
.ok_or(AuthError::MissingToken)?;
let token = auth_header.strip_prefix("Bearer ").ok_or(AuthError::InvalidTokenFormat)?;
let claims = Claims::decode(token, &state.auth_config.jwt_secret)
.map_err(|_| AuthError::InvalidToken)?;
let role: Role = claims.role.parse().map_err(|_| AuthError::InvalidRole)?;
if !role.has_permission(&Permission::UsersWrite) {
return Err(AuthError::Forbidden("Admin access required".into()));
}
request.extensions_mut().insert(AuthUser {
user_id: claims.sub,
role: claims.role,
});
Ok(next.run(request).await)
}
async fn session_auth_middleware(
State(state): State<SharedState>,
mut request: Request,
next: Next,
) -> Result<Response, AuthError> {
let cookie_header = request.headers()
.get("cookie")
.and_then(|v| v.to_str().ok())
.ok_or(AuthError::MissingSession)?;
let session_id = extract_session_id(cookie_header).ok_or(AuthError::MissingSession)?;
let session = state.session_store.get_session(&session_id).await
.map_err(|_| AuthError::InternalServerError("Redis error".into()))?
.ok_or(AuthError::SessionExpired)?;
if session.is_expired() {
state.session_store.delete_session(&session_id).await.ok();
return Err(AuthError::SessionExpired);
}
state.session_store.refresh_session(&session_id).await.ok();
request.extensions_mut().insert(session);
Ok(next.run(request).await)
}
避坑指南
坑1：JWT密鑰硬編碼
// ❌ 錯誤：密鑰硬編碼在程式碼中
let secret = "my-super-secret-key-123";
// ✅ 正確：從環境變數讀取，啟動時校驗
let secret = std::env::var("JWT_SECRET")
.expect("JWT_SECRET must be set");
if secret.len() < 32 {
panic!("JWT_SECRET must be at least 32 characters");
}
坑2：中介軟體中State型別不匹配
// ❌ 錯誤：from_fn無法存取State，編譯報錯
.layer(middleware::from_fn(my_auth_middleware))
async fn my_auth_middleware(
State(state): State<SharedState>, // from_fn不支援State引數！
request: Request,
next: Next,
) -> Result<Response, AuthError> { ... }
// ✅ 正確：使用from_fn_with_state
.layer(middleware::from_fn_with_state(state.clone(), my_auth_middleware))
async fn my_auth_middleware(
State(state): State<SharedState>,
request: Request,
next: Next,
) -> Result<Response, AuthError> { ... }
坑3：JWT Claims缺少過期校驗
// ❌ 錯誤：手動建立Validation但沒啟用exp檢查
let validation = Validation::new(jsonwebtoken::Algorithm::HS256);
// 預設會檢查exp，但如果手動構造可能遺漏
// ✅ 正確：顯式配置Validation
let mut validation = Validation::new(jsonwebtoken::Algorithm::HS256);
validation.leeway = 60; // 允許60秒時鐘偏移
validation.validate_exp = true;
validation.validate_nbf = true;
let token_data = decode::<Claims>(token, &key, &validation)?;
坑4：RBAC用字串匹配許可權
// ❌ 錯誤：字串硬編碼，容易拼寫錯誤且無法編譯時檢查
if user.role == "admin" || user.permissions.contains(&"users:write".to_string()) {
// 拼寫錯誤不會被編譯器發現
}
// ✅ 正確：使用列舉+strum，編譯時保證許可權名正確
#[derive(EnumString)]
pub enum Permission {
#[strum(to_string = "users:write")]
UsersWrite,
}
let perm = Permission::UsersWrite;
if role.has_permission(&perm) {
// 編譯時安全
}
坑5：Redis連線未複用
// ❌ 錯誤：每次請求建立新連線
async fn get_session(session_id: &str) -> Option<Session> {
let client = redis::Client::open("redis://localhost").unwrap();
let mut conn = client.get_async_connection().await.unwrap(); // 每次新建！
conn.get(session_id).await.ok()
}
// ✅ 正確：使用multiplexed連線複用
pub struct SessionStore {
client: redis::Client,
}
impl SessionStore {
pub async fn get_session(&self, session_id: &str) -> Result<Option<Session>, redis::RedisError> {
let mut conn = self.client.get_multiplexed_async_connection().await?;
let value: Option<String> = conn.get(session_id).await?;
// ...
}
}
報錯排查
| 序號 | 報錯資訊 | 原因 | 解決方法 |
|---|---|---|---|
| 1 | the trait FromRequestParts is not implemented for AuthUser |
未實作FromRequestParts trait | 使用#[axum::async_trait]實作trait，確保Rejection型別實作IntoResponse |
| 2 | mismatched types: expected State<X>, found State<Y> |
中介軟體和Router的State型別不一致 | 統一使用type SharedState = Arc<AppState>別名 |
| 3 | JWT decode error: InvalidToken |
token格式錯誤或密鑰不匹配 | 檢查Bearer前綴、密鑰一致性、演算法匹配 |
| 4 | JWT decode error: ExpiredSignature |
token已過期 | 實作refresh token機制，前端自動續期 |
| 5 | future cannot be sent between threads safely |
Redis連線非Send型別跨await | 使用get_multiplexed_async_connection()替代get_async_connection() |
| 6 | missing field 'exp' in Claims |
Claims結構體缺少exp欄位 | 確保Claims包含exp和iat欄位，Validation預設檢查 |
| 7 | Rate limit state not found in extensions |
Extension未注入 | 在中介軟體或Router層透過.layer(Extension(state))注入 |
| 8 | Redis: Connection refused |
Redis服務未啟動 | 檢查Redis服務狀態和連線URL配置 |
| 9 | handler has too many arguments |
Handler引數超過4個Extractor | 用結構體合併或使用Extension傳遞認證資訊 |
| 10 | Cannot drop a runtime in a context that is already inside a runtime |
在async函式中同步建立Redis連線 | 使用get_multiplexed_async_connection().await非同步連線 |
進階最佳化
1. JWT黑名單與主動撤銷
use std::collections::HashSet;
use tokio::sync::RwLock;
#[derive(Clone)]
pub struct JwtBlacklist {
pub revoked_tokens: Arc<RwLock<HashSet<String>>>,
pub redis_client: Option<redis::Client>,
}
impl JwtBlacklist {
pub fn new(redis_url: Option<&str>) -> Result<Self, redis::RedisError> {
let client = redis_url
.map(redis::Client::open)
.transpose()?;
Ok(Self {
revoked_tokens: Arc::new(RwLock::new(HashSet::new())),
redis_client: client,
})
}
pub async fn revoke_token(&self, jti: &str, exp_secs: i64) -> Result<(), AuthError> {
if let Some(client) = &self.redis_client {
let mut conn = client.get_multiplexed_async_connection().await
.map_err(|_| AuthError::InternalServerError("Redis connection failed".into()))?;
let key = format!("jwt:blacklist:{}", jti);
redis::cmd("SET")
.arg(&key)
.arg("1")
.arg("EX")
.arg(exp_secs)
.exec_async(&mut conn)
.await
.map_err(|_| AuthError::InternalServerError("Redis SET failed".into()))?;
} else {
let mut tokens = self.revoked_tokens.write().await;
tokens.insert(jti.to_string());
}
Ok(())
}
pub async fn is_revoked(&self, jti: &str) -> bool {
if let Some(client) = &self.redis_client {
if let Ok(mut conn) = client.get_multiplexed_async_connection().await {
let key = format!("jwt:blacklist:{}", jti);
if let Ok(exists) = redis::cmd("EXISTS")
.arg(&key)
.query_async::<i32>(&mut conn)
.await
{
return exists > 0;
}
}
}
let tokens = self.revoked_tokens.read().await;
tokens.contains(jti)
}
}
2. 認證中介軟體效能最佳化
use axum::extract::Request;
use axum::middleware::Next;
use axum::response::Response;
use moka::sync::Cache;
use std::sync::Arc;
use std::time::Duration;
#[derive(Clone)]
pub struct AuthCache {
pub token_cache: Cache<String, AuthUser>,
pub api_key_cache: Cache<String, ApiKeyInfo>,
}
impl AuthCache {
pub fn new(max_entries: usize, ttl_secs: u64) -> Self {
Self {
token_cache: Cache::builder()
.max_capacity(max_entries as u64)
.time_to_live(Duration::from_secs(ttl_secs))
.build(),
api_key_cache: Cache::builder()
.max_capacity(max_entries as u64)
.time_to_live(Duration::from_secs(ttl_secs))
.build(),
}
}
}
pub async fn cached_jwt_auth_middleware(
State(state): State<SharedState>,
mut request: Request,
next: Next,
) -> Result<Response, AuthError> {
let auth_header = request.headers()
.get("authorization")
.and_then(|v| v.to_str().ok())
.ok_or(AuthError::MissingToken)?;
let token = auth_header.strip_prefix("Bearer ").ok_or(AuthError::InvalidTokenFormat)?;
if let Some(cached_user) = state.auth_cache.token_cache.get(token) {
request.extensions_mut().insert(cached_user);
return Ok(next.run(request).await);
}
let claims = Claims::decode(token, &state.auth_config.jwt_secret)
.map_err(|_| AuthError::InvalidToken)?;
let auth_user = AuthUser {
user_id: claims.sub.clone(),
role: claims.role.clone(),
};
state.auth_cache.token_cache.insert(token.to_string(), auth_user.clone());
request.extensions_mut().insert(auth_user);
Ok(next.run(request).await)
}
3. OpenTelemetry可觀測性整合
use axum::extract::Request;
use axum::middleware::Next;
use axum::response::Response;
use opentelemetry::trace::{Span, Tracer};
use opentelemetry::KeyValue;
pub async fn observability_middleware(
request: Request,
next: Next,
) -> Response {
let method = request.method().clone();
let path = request.uri().path().to_string();
let auth_method = if request.headers().contains_key("x-api-key") {
"api_key"
} else if request.headers().contains_key("authorization") {
"jwt"
} else if request.headers().contains_key("cookie") {
"session"
} else {
"none"
};
let tracer = opentelemetry::global::tracer("auth-service");
let mut span = tracer.start(format!("{} {}", method, path));
span.set_attribute(KeyValue::new("auth.method", auth_method.to_string()));
span.set_attribute(KeyValue::new("http.method", method.to_string()));
span.set_attribute(KeyValue::new("http.path", path.clone()));
let response = next.run(request).await;
span.set_attribute(KeyValue::new("http.status_code", response.status().as_u16() as i64));
span.end();
response
}
對比分析
| 維度 | Axum+Tower | Actix-web Guard | Go Gin | Java Spring Security |
|---|---|---|---|---|
| 認證模型 | FromRequestParts+Layer | Guard trait+Extractor | 中介軟體函式 | Filter鏈+SecurityContext |
| 型別安全 | ✅編譯時 | ⚠️部分執行時 | ❌執行時 | ❌執行時 |
| 中介軟體組合 | ✅Tower ServiceBuilder | ⚠️手動巢狀 | ✅中介軟體鏈 | ✅Filter鏈 |
| RBAC支援 | 需自行實作 | 需自行實作 | casbin等庫 | ✅內建@PreAuthorize |
| JWT生態 | jsonwebtoken | jsonwebtoken | golang-jwt | jjwt/nimbus |
| 會話管理 | 需自行實作 | 需自行實作 | gorilla/sessions | ✅內建Session |
| 效能 | ⭐極高 | ⭐極高 | ⭐高 | ⭐中 |
| 學習曲線 | ⭐陡 | ⭐陡 | ⭐平緩 | ⭐極陡 |
| 限流整合 | tower-http | 自行實作 | tollbooth等 | bucket4j等 |
| 生產就緒度 | ⭐高 | ⭐高 | ⭐極高 | ⭐極高 |
總結：Axum鑑權的核心優勢在於型別安全的提取器——
FromRequestParts讓認證資訊像普通引數一樣注入Handler，編譯時就能發現型別不匹配。2026年的生產實踐：用FromRequestParts實作JWT/API Key提取→列舉+strum構建RBAC許可權模型→from_fn_with_state編寫帶狀態的中介軟體→Redis管理會話與JWT黑名單→moka快取加速token校驗→Tower ServiceBuilder組合中介軟體管道。關鍵是要理解Axum的提取器模型——認證不是"攔截器"，而是"型別提取"。
線上工具推薦
- Hash計算工具：/zh-TW/encode/hash — 生成SHA256/SHA512等雜湊值，用於API Key校驗
- Base64編解碼：/zh-TW/encode/base64 — 解碼JWT的Header和Payload部分
- JWT解碼工具：/zh-TW/encode/jwt-decode — 線上解析JWT令牌，檢視Claims內容
本站提供瀏覽器本地工具，免註冊即可試用 →
#Rust#Axum#中间件#JWT#认证鉴权#2026#Tower