Lib.rs

Rust Embed

Rust 自定义 derive 宏，在发布时将文件加载到 Rust 可执行文件中，在开发期间从文件系统加载。

您可以使用此功能将 css、js 和图片嵌入到单个可执行文件中，并将其部署到您的服务器。它还使您能够构建一个非常小的 Docker 镜像以供部署。

安装

[dependencies]
rust-embed="8.4.0"

文档

您需要将自定义 derive 宏 RustEmbed 添加到您的结构体中，并使用属性 folder，该属性是您的静态文件夹的路径。

路径解析方式如下

• 在 debug 和当 debug-embed 功能未启用时，文件夹路径相对于运行二进制文件的位置解析。
• 在 release 或当 debug-embed 功能启用时，文件夹路径相对于 Cargo.toml 文件解析。

#[derive(Embed)]
#[folder = "examples/public/"]
struct Asset;

该宏将生成以下代码

impl Asset {
  pub fn get(file_path: &str) -> Option<rust_embed::EmbeddedFile> {
    ...
  }

  pub fn iter() -> impl Iterator<Item = Cow<'static, str>> {
    ...
  }
}
impl RustEmbed for Asset {
  fn get(file_path: &str) -> Option<rust_embed::EmbeddedFile> {
    ...
  }
  fn iter() -> impl Iterator<Item = Cow<'static, str>> {
    ...
  }
}

// Where EmbeddedFile contains these fields,
pub struct EmbeddedFile {
  pub data: Cow<'static, [u8]>,
  pub metadata: Metadata,
}
pub struct Metadata {
  hash: [u8; 32],
  last_modified: Option<u64>,
  created: Option<u64>,
}

get(file_path: &str) -> Option<rust_embed::EmbeddedFile>

给定从资源文件夹的相对路径返回 EmbeddedFile 如果找到的话。

如果启用了功能 debug-embed 或编译为发布模式的二进制文件，则字节数据已嵌入到二进制文件中，并返回 Option<rust_embed::EmbeddedFile>。

否则，每次调用都会从文件系统中读取字节，并返回一个Option<rust_embed::EmbeddedFile>。

iter()

遍历这个资源文件夹中的文件。

如果启用了功能debug-embed或者以发布模式编译的二进制文件，则返回一个包含文件相对路径列表的静态数组。

否则，每次调用都会从文件系统中列出文件。

属性

prefix

您可以将#[prefix = "my_prefix/"]添加到RustEmbed结构中，为所有文件路径添加前缀。在get调用中需要此前缀，并且它将包含在iter返回的文件路径中。

metadata_only

您可以将#[metadata_only = true]添加到RustEmbed结构中，以从二进制文件中排除文件内容。仅嵌入文件路径和元数据。

功能

debug-embed

始终将文件嵌入到二进制文件中，即使在调试模式下也是如此。

interpolate-folder-path

允许在folder路径中使用环境变量。示例

#[derive(Embed)]
#[folder = "$CARGO_MANIFEST_DIR/foo"]
struct Asset;

这将拉取相对于您的Cargo.toml文件的foo目录。

compression

在将文件嵌入到二进制文件时压缩每个文件。压缩通过include-flate完成。

include-exclude

使用多个#[include = "*.txt"]和#[exclude = "*.jpg"]属性过滤要嵌入的文件。匹配是通过globset在相对文件路径上完成的。exclude属性比include属性具有更高的优先级。示例

use rust_embed::Embed;

#[derive(Embed)]
#[folder = "examples/public/"]
#[include = "*.html"]
#[include = "images/*"]
#[exclude = "*.txt"]
struct Asset;

用法

use rust_embed::Embed;

#[derive(Embed)]
#[folder = "examples/public/"]
#[prefix = "prefix/"]
struct Asset;

fn main() {
  let index_html = Asset::get("prefix/index.html").unwrap();
  println!("{:?}", std::str::from_utf8(index_html.data.as_ref()));

  for file in Asset::iter() {
      println!("{}", file.as_ref());
  }
}

集成

1. Poem（在“embed”功能标志下）
2. warp_embed（warp 框架）

示例

要运行从文件系统读取的dev模式下的示例，

cargorun --examplebasic

要运行从二进制文件读取的发布模式下的示例，

cargorun --examplebasic --release

注意：要运行actix-web示例

cargorun --exampleactix --featuresactix

注意：要运行rocket示例

cargorun --examplerocket --featuresrocket

注意：要运行warp示例

cargorun --examplewarp --featureswarp-ex

注意：要运行axum示例

cargorun --exampleaxum --featuresaxum-ex

注意：要运行poem示例

cargorun --examplepoem --featurespoem-ex

注意：要运行salvo示例

cargorun --examplesalvo --featuressalvo-ex

测试

debug: cargo test --test lib

release: cargo test --test lib --release

Go Rusketeers! The power is yours!