以下是关于tagged-base64库的完整使用指南，包含所有示例代码：

完整示例代码

1. 预定义标签使用示例

use tagged_base64::prelude::*;

fn main() {
    // 编码示例
    let data = b"hello world";
    let encoded = data.to_base64(Standard);  // 使用标准Base64编码
    println!("Encoded: {}", encoded);
    
    // 解码示例
    let decoded = Vec::<u8>::from_base64(&encoded, Standard).unwrap();
    assert_eq!(decoded, data);
}

2. 自定义标签实现示例

use tagged_base64::{TaggedBase64, Tag};

// 自定义标签定义
struct MyCustomTag;
impl Tag for MyCustomTag {
    const CONFIG: base64::Config = base64::Config::new(
        base64::CharacterSet::Standard,  // 使用标准字符集
        true                             // 使用填充
    );
}

fn main() {
    let secret_data = b"sensitive information";
    
    // 使用自定义标签编码
    let encoded = secret_data.to_base64(MyCustomTag);
    println!("Securely encoded: {}", encoded);
    
    // 必须使用相同标签解码
    let decoded = Vec::<u8>::from_base64(&encoded, MyCustomTag).unwrap();
    assert_eq!(decoded, secret_data);
}

3. 序列化/反序列化完整示例

use serde::{Serialize, Deserialize};
use tagged_base64::{TaggedBase64, Standard};

#[derive(Serialize, Deserialize, Debug)]
struct User {
    #[serde(with = "tagged_base64::serde")]  // 使用tagged-base64的serde支持
    avatar: Vec<u8>,
    name: String,
}

fn main() {
    // 创建用户对象
    let user = User {
        avatar: b"binary image data".to_vec(),
        name: "Alice".to_string(),
    };
    
    // 序列化为JSON
    let json = serde_json::to_string(&user).unwrap();
    println!("Serialized JSON: {}", json);
    
    // 从JSON反序列化
    let deserialized: User = serde_json::from_str(&json).unwrap();
    println!("Deserialized user: {:?}", deserialized);
    assert_eq!(deserialized.avatar, b"binary image data");
}

4. 高级用法完整示例

use tagged_base64::{TaggedBase64, UrlSafe, Standard, Mime, DecodeError};

fn main() {
    // 多种编码配置示例
    let data = b"complex data @#$%^&";
    println!("Standard编码: {}", data.to_base64(Standard));
    println!("URL安全编码: {}", data.to_base64(UrlSafe));
    println!("MIME编码: {}", data.to_base64(Mime));

    // 错误处理示例
    match Vec::<u8>::from_base64("invalid!data", Standard) {
        Ok(data) => println!("解码成功: {:?}", data),
        Err(DecodeError::InvalidByte(_, _)) => println!("错误: 包含无效字符"),
        Err(e) => println!("其他错误: {}", e),
    }
}

5. 性能优化完整示例

use std::borrow::Cow;
use tagged_base64::{TaggedBase64, Standard};

fn main() {
    // 预分配缓冲区示例
    let large_data = vec![0u8; 1024 * 1024];  // 1MB数据
    let encoded = encode_large_data(&large_data);
    println!("编码数据长度: {}", encoded.len());

    // Cow使用示例
    let input1 = "base64:SGVsbG8gV29ybGQ=";  // Base64编码数据
    let input2 = "plain text";               // 普通文本
    
    println!("解码结果1: {:?}", maybe_decode(input1));
    println!("解码结果2: {:?}", maybe_decode(input2));
}

// 预分配缓冲区的编码函数
fn encode_large_data(data: &[u8]) -> String {
    let mut buf = String::with_capacity(data.len() * 4 / 3 + 4);
    data.write_base64(Standard, &mut buf).unwrap();
    buf
}

// 使用Cow避免不必要拷贝的函数
fn maybe_decode<'a>(input: &'a str) -> Cow<'a, [u8]> {
    if input.starts_with("base64:") {
        let encoded = &input[7..];
        Cow::Owned(Vec::<u8>::from_base64(encoded, Standard).unwrap())
    } else {
        Cow::Borrowed(input.as_bytes())
    }
}

使用建议

1. 对于安全性要求高的场景，建议为每种数据类型创建独立的标签
2. 处理大型数据时，务必使用预分配缓冲区的方式
3. 在Web应用中，URL路径或参数编码使用UrlSafe标签
4. 考虑使用新类型模式(New Type Pattern)包装不同标签的Base64数据

这个库通过类型系统在编译期捕获了许多潜在错误，同时保持了良好的运行时性能，是传统Base64编码的强类型替代方案。