解决utoipa-swagger-ui在Docker容器中的404问题

在使用Rust的utoipa-swagger-ui库时，开发者可能会遇到一个奇怪的问题：在Docker容器中运行时，Swagger UI页面返回404错误，而实际上请求已经正确路由到了Swagger UI。这个问题通常与资源嵌入方式有关，特别是在开发环境和生产环境下的差异。

问题根源分析

utoipa-swagger-ui库依赖于rust-embed来嵌入Swagger UI的静态资源文件。rust-embed在开发模式(--debug)和生产模式(--release)下的行为有所不同：

1. 在开发模式下，rust-embed默认不会真正嵌入文件，而是从文件系统读取
2. 在生产模式下，rust-embed会将文件真正嵌入到二进制中

当在Docker容器中运行开发构建的二进制时，由于容器环境中缺少原始的文件系统路径，rust-embed无法找到Swagger UI的资源文件，导致404错误。

解决方案

有两种方法可以解决这个问题：

1. 使用生产构建

在构建Docker镜像时使用--release标志：

cargo build --release

2. 启用debug-embed特性

在Cargo.toml中为utoipa-swagger-ui添加debug-embed特性：

utoipa-swagger-ui = { version = "8.0.3", features = ["axum", "vendored", "debug-embed"] }

这个特性会强制rust-embed在开发模式下也嵌入文件，确保在Docker环境中能正常工作。

最佳实践建议

1. 对于生产部署，始终使用--release构建
2. 对于开发环境，如果需要在Docker中运行，添加debug-embed特性
3. 考虑在CI/CD流水线中区分开发和生产构建配置

技术背景

rust-embed的这种行为设计是为了提高开发效率。在开发过程中，频繁修改资源文件时，直接从文件系统读取可以避免重新编译。但在部署环境中，将资源嵌入二进制可以简化部署流程并提高安全性。

理解这一机制有助于开发者更好地处理类似问题，特别是在容器化部署场景下。这种模式在其他语言的资源嵌入库中也很常见，是跨环境部署时需要考虑的一个重要因素。