Rust多哈希（multihash）派生实现库multihash-derive-impl使用指南

multihash-derive-impl是一个Rust库，用于简化multihash的实现过程，支持自定义哈希算法并提供高效的编解码功能。

主要特性

• 通过派生宏简化multihash实现
• 支持自定义哈希算法
• 提供高效的编解码功能
• 与标准multihash格式兼容

使用方法

添加依赖

首先在Cargo.toml中添加依赖：

[dependencies]
multihash-derive-impl = "0.1"
multihash = "0.18"

基本用法

use multihash_derive_impl::{MultihashDigest, Multihash};
use multihash::{Code, Hasher, MultihashDigest};

// 定义一个简单的哈希算法
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MyCustomHasher;

impl Hasher for MyCustomHasher {
    type Size = typenum::U32; // 输出32字节

    fn update(&mut self, input: &[u8]) {
        // 实现你的哈希更新逻辑
    }

    fn finalize(&mut self) -> multihash::MultihashGeneric<Self::Size> {
        // 实现哈希最终化逻辑
        let digest = [0u8; 32]; // 示例输出
        Code::Sha2_256.wrap(digest).unwrap()
    }

    fn reset(&mut self) {
        // 重置哈希状态
    }
}

// 使用派生宏实现Multihash
#[derive(MultihashDigest)]
pub enum MyMultihash {
    #[mh(code = 0x12, hasher = MyCustomHasher)]
    MyCustomHash,
    #[mh(code = 0x13, hasher = multihash::Sha2_256)]
    Sha2_256,
}

fn main() {
    // 使用自定义哈希
    let hash = MyMultihash::digest(&MyCustomHasher, b"hello world");
    println!("Custom hash: {:?}", hash);
    
    // 使用标准SHA2-256
    let sha_hash = MyMultihash::digest(&multihash::Sha2_256, b"hello world");
    println!("SHA2-256 hash: {:?}", sha_hash);
}

自定义哈希算法

use multihash_derive_impl::{MultihashDigest, Multihash};
use multihash::{Hasher, MultihashDigest};

// 自定义哈希算法结构体
#[derive(Debug, Default)]
pub struct SimpleXorHasher {
    state: u8,
}

impl Hasher for SimpleXorHasher {
    type Size = typenum::U1; // 1字节输出
    
    fn update(&mut self, input: &[u8]) {
        for &byte in input {
            self.state ^= byte;
        }
    }
    
    fn finalize(&mut self) -> multihash::MultihashGeneric<Self::Size> {
        let digest = [self.state];
        // 使用自定义code 0x99
        multihash::Multihash::wrap(0x99, &digest).unwrap()
    }
    
    fn reset(&mut self) {
        self.state = 0;
    }
}

// 定义包含自定义算法的multihash枚举
#[derive(MultihashDigest)]
pub enum CustomMultihash {
    #[mh(code = 0x99, hasher = SimpleXorHasher)]
    SimpleXor,
}

fn main() {
    let mut hasher = SimpleXorHasher::default();
    let hash = CustomMultihash::digest(&mut hasher, b"example data");
    println!("Simple XOR hash: {:?}", hash);
}

编解码示例

use multihash::Multihash;
use std::convert::TryFrom;

// 假设使用之前的MyMultihash定义

fn encode_decode_example() {
    let data = b"data to hash";
    
    // 编码
    let hash = MyMultihash::digest(&multihash::Sha2_256, data);
    let encoded = hash.to_bytes();
    
    // 解码
    let decoded = Multihash::from_bytes &encoded).unwrap();
    assert_eq!(hash, decoded);
    
    println!("Original: {:?}", hash);
    println!("Encoded: {:?}", encoded);
    println!("Decoded: {:?}", decoded);
}

高级用法

支持多种哈希算法

#[derive(MultihashDigest)]
pub enum ComprehensiveMultihash {
    #[mh(code = 0x12, hasher = multihash::Sha2_256)]
    Sha2_256,
    #[mh(code = 0x13, hasher = multihash::Sha2_512)]
    Sha2_512,
    #[mh(code = 0x14, hasher = multihash::Sha3_256)]
    Sha3_256,
    #[mh(code = 0x15, hasher = multihash::Blake2b256)]
    Blake2b256,
    #[mh(code = 0x99, hasher = SimpleXorHasher)] // 自定义算法
    SimpleXor,
}

fn multi_algorithm_example() {
    let data = b"multi-algorithm example";
    
    let hashes = vec![
        ComprehensiveMultihash::digest(&multihash::Sha2_256, data),
        ComprehensiveMultihash::digest(&multihash::Sha3_256, data),
        ComprehensiveMultihash::digest(&mut SimpleXorHasher::default(), data),
    ];
    
    for hash in hashes {
        println!("Hash ({:?}): {}", hash.code(), hex::encode(hash.digest()));
    }
}

性能提示

1. 对于频繁哈希的场景，重用Hasher实例比每次都创建新实例更高效
2. 编解码操作是零拷贝的，尽可能利用这一特性
3. 自定义哈希算法时，确保update和finalize方法高效实现

注意事项

• 自定义哈希算法的code应避免与标准multihash code冲突
• 确保自定义哈希算法正确实现Hasher trait的所有方法
• 编解码错误处理应使用Rust的标准错误处理模式

这个库特别适合需要支持多种哈希算法或需要自定义哈希算法的场景，通过派生宏大大简化了multihash的实现过程。

完整示例

下面是一个完整的示例，展示了如何定义自己的Multihash类型并使用它：

use multihash_derive_impl::{MultihashDigest, Multihash};
use multihash::{Hasher, MultihashDigest};
use typenum::U32;

// 自定义哈希算法 - 简单的加法哈希
#[derive(Debug, Default)]
pub struct SumHasher {
    sum: u32,
}

impl Hasher for SumHasher {
    type Size = U32; // 32字节输出
    
    fn update(&mut self, input: &[u8]) {
        for &byte in input {
            self.sum = self.sum.wrapping_add(byte as u32);
        }
    }
    
    fn finalize(&mut self) -> multihash::MultihashGeneric<Self::Size> {
        let digest = self.sum.to_be_bytes(); // 转换为大端字节序
        multihash::Multihash::wrap(0x90, &digest).unwrap() // 使用自定义code 0x90
    }
    
    fn reset(&mut self) {
        self.sum = 0;
    }
}

// 定义自己的Multihash类型
#[derive(MultihashDigest)]
pub enum MyHash {
    #[mh(code = 0x90, hasher = SumHasher)] // 自定义算法
    SumHash,
    #[mh(code = 0x12, hasher = multihash::Sha2_256)] // 标准算法
    Sha256,
    #[mh(code = 0xb240, hasher = multihash::Blake2b256)] // 另一个标准算法
    Blake2b256,
}

fn main() {
    // 使用自定义哈希算法
    let mut hasher = SumHasher::default();
    let sum_hash = MyHash::digest(&mut hasher, b"test data");
    println!("Sum hash: {:?}", sum_hash);
    
    // 使用标准SHA-256
    let sha_hash = MyHash::digest(&multihash::Sha2_256, b"test data");
    println!("SHA-256 hash: {:?}", sha_hash);
    
    // 使用Blake2b
    let blake_hash = MyHash::digest(&multihash::Blake2b256, b"test data");
    println!("Blake2b hash: {:?}", blake_hash);
    
    // 编解码示例
    let encoded = sha_hash.to_bytes();
    let decoded = multihash::Multihash::from_bytes(&encoded).unwrap();
    assert_eq!(sha_hash, decoded);
    println!("Encoded SHA-256: {:?}", encoded);
}

这个完整示例展示了：

1. 如何定义自定义哈希算法(SumHasher)
2. 如何创建支持多种哈希算法的Multihash枚举(MyHash)
3. 如何使用不同的哈希算法计算哈希值
4. 如何进行编解码操作

输出结果会显示三种不同算法的哈希值，以及SHA-256哈希的编码形式。