静态文件中间件

静态文件中间件用于高效地处理和提供 HTML、CSS、JS、图片等静态资源请求，是 Web 应用开发中不可或缺的基础能力。

静态文件中间件典型时序图

说明

• 静态文件中间件会先访问文件系统获取文件的元信息（如最后修改时间、文件大小），用于生成 ETag。
• 生成 ETag 后，与客户端的 If-None-Match 头进行比对。
• 如果 ETag 匹配，直接返回 304 Not Modified，无需读取文件内容。
• 如果 ETag 不匹配，才会读取文件内容并返回。
• 这样既保证了缓存的高效性，也最大限度减少了磁盘 IO。

快速启动

只需 4 步即可应用静态文件服务：

import spire_web_hosting.*
import spire_web_http.*
import spire_web_staticfiles.*

main() {
    // 1.构建Web主机
    let builder = WebHost.createBuilder()
    let host = builder.build()

    // 2. 启用欢迎页中间件（可选）
    host.useDefaultFiles()

    // 3. 启用静态文件中间件
    host.useStaticFiles()

    // 4. 启动主机
    host.run()
}

添加依赖

需要在依赖配置文件(cjpm.toml)中添加如下依赖：

[dependencies]
  spire_web_http = { path = "/spire_web_http"}
  spire_web_hosting = { path = "/spire_web_hosting"}
  spire_web_routing = { path = "/spire_web_routing"}
  spire_extensions_options = { path = "/spire_extensions_options"}
  spire_extensions_injection = { path = "/spire_extensions_injection"}
  spire_web_staticfiles = { path = "/spire_web_staticfiles"}

默认文件中间件

欢迎页中间件会自动查找 wwwroot 目录下的默认首页文件（如 index.html ）。支持自定义欢迎页文件名：

host.useDefaultFiles { options =>
    // 添加自定义欢迎页文件名
    options.defaultFileNames.add("welcome.html")
}

静态文件中间件配置

支持自定义内容类型映射、默认内容类型等高级选项：

host.useStaticFiles { options =>
    // 自定义内容类型映射
    let contentTypeProvider = ContentTypeProvider()
    contentTypeProvider.mappings[".bcmap"] = "application/octet-stream"
    options.contentTypeProvider = contentTypeProvider
}

或设置默认内容类型：

host.useStaticFiles { options =>
    options.serveUnknownFileTypes = true
    options.defaultContentType = "application/octet-stream"
}

目录结构建议

项目根目录/
├─ src/
│  ├─ main.cj
│  └─ ...
├─ wwwroot/
│  ├─ html/
│  ├─ css/
│  ├─ index.html
│  └─ ...
└─ ...

资源管理

所有静态资源建议统一放置于 wwwroot 目录下，便于统一管理和访问。

最佳实践

• 推荐将所有前端静态资源（HTML、CSS、JS、图片等）集中放在 wwwroot 目录。
• 使用 useDefaultFiles() 可自动支持首页访问体验。
• 通过 useStaticFiles() 提供高性能的静态资源服务。
• 如需自定义内容类型或支持特殊文件扩展名，可通过 contentTypeProvider 配置。