本地文件服务

Feature: file | 无外部依赖

简介

本地文件服务，提供文件上传、下载、删除、目录列表、URL 生成等功能。

支持文件类型校验、大小限制、路径安全检查（防路径遍历攻击）。

配置

[file]
root = "./uploads"                    # 存储根目录，不存在时自动创建
max_size = 10485760                   # 最大文件大小（字节），默认 10MB
allowed = ["jpg","png","gif","pdf"]   # 允许的扩展名，为空则不限制
url_prefix = "/files"                 # 访问 URL 前缀

API

FileService

FileInfo

#![allow(unused)]
fn main() {
pub struct FileInfo {
    pub path: String,    // 相对路径
    pub name: String,    // 文件名
    pub ext: String,     // 扩展名（小写）
    pub size: u64,       // 文件大小（字节）
    pub mime: String,    // MIME 类型
    pub is_dir: bool,    // 是否为目录
}
}

DirList

#![allow(unused)]
fn main() {
pub struct DirList {
    pub path: String,          // 当前目录路径
    pub entries: Vec<FileInfo>, // 子项列表
}
}

安全特性

路径遍历防护

自动拦截包含 .. 或 \0 的路径，canonicalize 后校验是否在 root 目录内：

#![allow(unused)]
fn main() {
// ✅ 正常路径
fs.upload("docs/readme.txt", data)?;

// ❌ 路径遍历攻击 → 返回 41905 错误
fs.upload("../../etc/passwd", data)?;
}

文件类型校验

配置 allowed 列表后，只有列出的扩展名允许上传：

#![allow(unused)]
fn main() {
// 配置 allowed = ["jpg", "png", "pdf"]

// ✅ 允许
fs.upload("photo.jpg", data)?;

// ❌ 拒绝 → 返回 41903 错误
fs.upload("virus.exe", data)?;
}

文件大小限制

上传时自动检查文件大小：

#![allow(unused)]
fn main() {
// 配置 max_size = 10485760 (10MB)

// ❌ 超过限制 → 返回 41902 错误
fs.upload("big.zip", &huge_data)?;
}

使用示例

#![allow(unused)]
fn main() {
use afaster::{FileConfig, FileService};

let config = FileConfig {
    root: "./uploads".to_string(),
    max_size: 10 * 1024 * 1024,
    allowed: vec!["jpg".into(), "png".into(), "pdf".into()],
    url_prefix: "/files".to_string(),
};

let fs = FileService::new(&config)?;

// 上传
let info = fs.upload("avatars/1.jpg", &image_bytes)?;
println!("已上传: {} ({} bytes)", info.path, info.size);

// 下载
let data = fs.download("avatars/1.jpg")?;

// 生成 URL
let url = fs.url("avatars/1.jpg")?; // "/files/avatars/1.jpg"

// 目录列表
let list = fs.list("avatars")?;
for entry in &list.entries {
    println!("{}: {} bytes", entry.name, entry.size);
}

// 删除
fs.delete("avatars/1.jpg")?;
}

支持的 MIME 类型

错误码