Skip to content

static-files.md

Latest commit

 

History

History
123 lines (87 loc) · 3.45 KB

static-files.md

File metadata and controls

123 lines (87 loc) · 3.45 KB
Raw

静态文件服务

Exum 提供了强大的静态文件服务，基于 StaticFileServiceBuilder 构建，支持多种高级特性。

功能特性

🌐 跨域支持

  • CORS配置 - 支持完整的CORS跨域配置
  • 预置CORS策略 - 提供 cors_any() 方法快速启用全允许CORS

📱 SPA支持

  • SPA回退 - 支持单页应用的回退机制，未找到文件时返回 index.html
  • 智能路由 - 适合Vue、React等前端框架的单页应用部署

📊 文件处理

  • 流式传输 - 使用 tokio_util::io::ReaderStream 实现高效的文件流传输
  • MIME类型推测 - 自动根据文件扩展名推测正确的MIME类型
  • UTF-8字符集 - 对文本文件自动添加 charset=utf-8 字符集
  • Last-Modified头 - 自动添加文件修改时间，支持浏览器缓存
  • HEAD请求支持 - 正确处理HEAD请求，返回文件元信息

🔧 错误处理

  • 智能404处理 - 文件不存在时返回适当的404响应
  • 错误日志 - 使用tracing记录服务错误信息

使用 StaticFileServiceBuilder

基础用法

use exum::layers::StaticFileServiceBuilder;

#[tokio::main]
async fn main() {
    let static_service = StaticFileServiceBuilder::new("./public")
        .build_router("/static");
    
    let mut app = Application::build(ApplicationConfig::default());
    app.merge(static_service);
    
    app.run().await;
}

启用SPA回退

use exum::layers::StaticFileServiceBuilder;

#[tokio::main]
async fn main() {
    let static_service = StaticFileServiceBuilder::new("./public")
        .with_spa_fallback(true)  // 启用SPA回退
        .build_router("/static");
    
    let mut app = Application::build(ApplicationConfig::default());
    app.merge(static_service);
    
    app.run().await;
}

启用CORS支持

use exum::layers::StaticFileServiceBuilder;

#[tokio::main]
async fn main() {
    let static_service = StaticFileServiceBuilder::new("./public")
        .cors_any()  // 启用全允许CORS
        .build_router("/static");
    
    let mut app = Application::build(ApplicationConfig::default());
    app.merge(static_service);
    
    app.run().await;
}

完整配置示例

use exum::layers::StaticFileServiceBuilder;

#[tokio::main]
async fn main() {
    let static_service = StaticFileServiceBuilder::new("./public")
        .with_spa_fallback(true)  // 启用SPA回退
        .cors_any()               // 启用CORS跨域支持
        .build_router("/assets");
    
    let mut app = Application::build(ApplicationConfig::default());
    app.merge(static_service);
    
    app.run().await;
}

基础静态文件服务（需要 app_chain_ext_full 特性）

注意：static_ 方法使用的是基础的 tower_http::services::ServeDir 服务，体验不如 StaticFileServiceBuilder，例如不支持自动URL编码路径、SPA回退等高级功能。建议优先使用 StaticFileServiceBuilder。

use exum::*;

#[tokio::main]
async fn main() {
    let mut app = Application::build(ApplicationConfig::default());
    app.static_("/static", "./public");
    
    app.run().await;
}

最佳实践

  1. 优先使用StaticFileServiceBuilder - 相比基础的 static_ 方法，提供更多高级功能
  2. 生产环境启用SPA回退 - 适合部署单页应用
  3. 开发环境启用CORS - 方便前后端分离开发
  4. 使用相对路径 - 服务会自动解析为绝对路径，确保安全性