Rust S3存储插件库s3s的使用指南

概述

s3s是一个Rust库，用于高效安全地与Amazon S3对象存储服务进行交互。它提供了简洁的API来执行常见的S3操作，如上传、下载、删除对象等。

安装

在Cargo.toml中添加依赖：

[dependencies]
s3s = "0.1"  # 请使用最新版本
tokio = { version = "1.0", features = ["full"] }

基本使用方法

1. 创建S3客户端

use s3s::S3Client;
use s3s::auth::Credentials;

#[tokio::main]
async fn main() {
    let credentials = Credentials::new(
        "YOUR_ACCESS_KEY_ID",
        "YOUR_SECRET_ACCESS_KEY",
        None,  // 可选的token
        None,  // 可选的过期时间
    );
    
    let client = S3Client::new(
        "us-east-1",  // 区域
        credentials,
    ).await.unwrap();
}

2. 上传文件到S3

use std::fs::File;
use std::io::Read;

async fn upload_file(client: &S3Client, bucket: &str, key: &str, file_path: &str) {
    let mut file = File::open(file_path).unwrap();
    let mut contents = Vec::new();
    file.read_to_end(&mut contents).unwrap();
    
    client.put_object(bucket, key, contents)
        .await
        .expect("Failed to upload file");
    
    println!("File uploaded successfully to {}/{}", bucket, key);
}

3. 下载文件从S3

use std::fs::File;
use std::io::Write;

async fn download_file(client: &S3Client, bucket: &str, key: &str, output_path: &str) {
    let data = client.get_object(bucket, key)
        .await
        .expect("Failed to download file");
    
    let mut file = File::create(output_path).unwrap();
    file.write_all(&data).unwrap();
    
    println!("File downloaded successfully from {}/{}", bucket, key);
}

4. 列出桶中的对象

async fn list_objects(client: &S3Client, bucket: &str) {
    let objects = client list_objects(bucket)
        .await
        .expect("Failed to list objects");
    
    println!("Objects in bucket {}:", bucket);
    for obj in objects {
        println!("- {}", obj.key);
    }
}

高级功能

1. 使用多部分上传（适合大文件）

use s3s::multipart::MultiPartUpload;

async fn multipart_upload(client: &S3Client, bucket: &str, key: &str, file_path: &str) {
    let mut upload = MultiPartUpload::new(client, bucket, key)
        .await
        .expect("Failed to initiate multipart upload");
    
    let mut file = File::open(file_path).unwrap();
    let mut buffer = vec![0; 5 * 1024 * 1024]; // 5MB chunks
    
    loop {
        let bytes_read = file.read(&mut buffer).unwrap();
        if bytes_read == 0 {
            break;
        }
        
        upload.upload_part(&buffer[..bytes_read])
            .await
            .expect("Failed to upload part");
    }
    
    upload.complete()
        .await
        .expect("Failed to complete upload");
    
    println!("Multipart upload completed for {}/{}", bucket, key);
}

2. 设置对象ACL（访问控制）

use s3s::acl::ObjectAcl;

async fn set_object_acl(client: &S3Client, bucket: &str, key: &str) {
    client.put_object_acl(
        bucket,
        key,
        ObjectAcl::PublicRead  // 或其他ACL选项
    )
    .await
    .expect("Failed to set object ACL");
    
    println!("ACL set for {}/{}", bucket, key);
}

安全注意事项

1. 永远不要将访问密钥硬编码在代码中，使用环境变量或安全的密钥管理系统
2. 为不同的应用使用不同的IAM用户和权限
3. 考虑使用临时安全凭证而不是长期凭证

// 从环境变量读取凭证的更好做法
use std::env;

fn get_credentials_from_env() -> Credentials {
    let access_key = env::var("AWS_ACCESS_KEY_ID").expect("AWS_ACCESS_KEY_ID not set");
    let secret_key = env::var("AWS_SECRET_ACCESS_KEY").expect("AWS_SECRET_ACCESS_KEY not set");
    
    Credentials::new(&access_key, &secret_key, None, None)
}

错误处理

s3s库提供了详细的错误类型，建议妥善处理：

use s3s::error::S3Error;

async fn safe_operation(client: &S3Client) -> Result<(), S3Error> {
    match client.list_objects("my-bucket").await {
        Ok(objects) => {
            for obj in objects {
                println!("Found object: {}", obj.key);
            }
            Ok(())
        },
        Err(S3Error::NoSuchBucket) => {
            eprintln!("Bucket does not exist");
            Ok(())
        },
        Err(e) => {
            eprintln!("S3 operation failed: {}", e);
            Err(e)
        }
    }
}

完整示例代码

下面是一个完整的示例，展示了如何使用s3s库进行基本的S3操作：

use s3s::{S3Client, auth::Credentials};
use std::fs::File;
use std::io::{Read, Write};
use tokio;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. 创建S3客户端（从环境变量获取凭证）
    let credentials = Credentials::new(
        &std::env::var("AWS_ACCESS_KEY_ID")?,
        &std::env::var("AWS_SECRET_ACCESS_KEY")?,
        None,
        None,
    );
    
    let client = S3Client::new("us-east-1", credentials).await?;
    
    // 2. 上传文件
    let bucket = "my-test-bucket";
    let file_key = "test.txt";
    let file_path = "./test.txt";
    
    upload_file(&client, bucket, file_key, file_path).await?;
    
    // 3. 列出桶中对象
    list_objects(&client, bucket).await?;
    
    // 4. 下载文件
    let output_path = "./downloaded_test.txt";
    download_file(&client, bucket, file_key, output_path).await?;
    
    Ok(())
}

async fn upload_file(
    client: &S3Client,
    bucket: &str,
    key: &str,
    file_path: &str
) -> Result<(), Box<dyn std::error::Error>> {
    let mut file = File::open(file_path)?;
    let mut contents = Vec::new();
    file.read_to_end(&mut contents)?;
    
    client.put_object(bucket, key, contents).await?;
    println!("File uploaded successfully to {}/{}", bucket, key);
    Ok(())
}

async fn download_file(
    client: &S3Client,
    bucket: &str,
    key: &str,
    output_path: &str
) -> Result<(), Box<dyn std::error::Error>> {
    let data = client.get_object(bucket, key).await?;
    
    let mut file = File::create(output_path)?;
    file.write_all(&data)?;
    
    println!("File downloaded successfully from {}/{}", bucket, key);
    Ok(())
}

async fn list_objects(
    client: &S3Client,
    bucket: &str
) -> Result<(), Box<dyn std::error::Error>> {
    let objects = client.list_objects(bucket).await?;
    
    println!("Objects in bucket {}:", bucket);
    for obj in objects {
        println!("- {}", obj.key);
    }
    Ok(())
}

这个完整示例展示了如何：

1. 从环境变量获取AWS凭证创建S3客户端
2. 上传文件到指定S3桶
3. 列出桶中的所有对象
4. 下载之前上传的文件

使用前请确保：

1. 已设置AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY环境变量
2. 指定的S3桶已存在
3. 本地有测试文件(test.txt)可用于上传