hashlib4cj 统一哈希 API 深度解析:IHash 接口与 HashResult 设计实战指南
hashlib4cj 统一哈希 API 深度解析:IHash 接口与 HashResult 设计实战指南
hashlib4cj 是一个用仓颉(Cangjie)语言实现的哈希算法库,内置 80+ 种哈希函数。本文以官方 API 文档 doc/feature_api.md 为骨架,结合 src/ihash.cj、src/hash.cj、src/hashresult.cj 等源码实现与 HLT 测试用例,系统讲解其核心抽象接口 IHash 与结果类型 HashResult 的设计。读完本文,你将掌握一次性哈希计算、增量哈希计算、流/文件哈希处理、多类型输入输出的统一转换规则,以及如何在 cjpm.toml 中引入依赖并写出可运行的哈希计算代码。
一、API 总览:一套接口,覆盖全部哈希算法
hashlib4cj 的设计核心在于统一抽象:无论底层是加密哈希(Keccak、RIPEMD、Whirlpool、GOST)、非加密哈希(Murmur、FNV、SipHash)还是校验和(CRC、Adler-32),上层都通过同一个接口 IHash 对外提供服务,计算结果统一封装为 HashResult。这种设计让调用方无需关心具体算法的内部状态机,只需掌握 compute*(一次性)与 transform*(增量)两组方法即可。
从源码看,接口定义的成员分为三大类:
- 只读属性:
name、blockSize、hashSize,用于描述算法的元信息; - 一次性哈希计算:
compute*系列,一次调用即返回HashResult; - 增量哈希计算:
transform*系列配合transformFinal(),可分段喂入数据后统一收尾。
此外,src/ihash_info.cj 中还有 IHash32 <: IHash、IHash64 <: IHash、IHash128 <: IHash、ICrypto <: IHash & IBlockHash、IHMAC 等细分接口,用于按位宽、按加密属性对算法族分类,但它们的公共行为全部继承自 IHash。
二、IHash 接口详解
2.1 接口定义原文
接口完整定义如下(与 src/ihash.cj 一致):
public interface IHash {
prop name: String
prop blockSize: Int64
prop hashSize: Int64
// 初始化
func initialize(): Unit
/*一次性哈希计算*/
func computeAny(data: Any): HashResult
func computeByte(data: Byte): HashResult
func computeBool(data: Bool): HashResult
func computeRune(data: Rune): HashResult
func computeStringUTF8(data: String): HashResult
func computeInt16(data: Int16): HashResult
func computeInt32(data: Int32): HashResult
func computeInt64(data: Int64): HashResult
func computeUInt16(data: UInt16): HashResult
func computeUInt32(data: UInt32): HashResult
func computeUInt64(data: UInt64): HashResult
func computeFloat32(data: Float32): HashResult
func computeFloat64(data: Float64): HashResult
func computeRunes(data: Array<Rune>): HashResult
func computeBytes(data: Array<Byte>): HashResult
func computeInt16s(data: Array<Int16>): HashResult
func computeInt32s(data: Array<Int32>): HashResult
func computeInt64s(data: Array<Int64>): HashResult
func computeUInt16s(data: Array<UInt16>): HashResult
func computeUInt32s(data: Array<UInt32>): HashResult
func computeUInt64s(data: Array<UInt64>): HashResult
func computeFloat32s(data: Array<Float32>): HashResult
func computeFloat64s(data: Array<Float64>): HashResult
func computeStream(data: IOStream, length!: Int64): HashResult
func computeFile(fileName: String, from: Int64, length: Int64): HashResult
func computeFileFromPath(fileName: Path, from: Int64, length: Int64): HashResult
/*增量哈希计算*/
/*结束计算,返回计算的结果*/
func transformFinal(): HashResult
func transformBytes(data: Array<Byte>): Unit
func transformBytes(data: Array<Byte>, index: Int64): Unit
func transformBytes(data: Array<Byte>, index: Int64, length: Int64): Unit
func transformAny(data: Any): Unit
func transformByte(data: Byte): Unit
func transformBool(data: Bool): Unit
func transformRune(data: Rune): Unit
func transformStringUTF8(data: String): Unit
func transformInt16(data: Int16): Unit
func transformInt32(data: Int32): Unit
func transformInt64(data: Int64): Unit
func transformUInt16(data: UInt16): Unit
func transformUInt32(data: UInt32): Unit
func transformUInt64(data: UInt64): Unit
func transformFloat32(data: Float32): Unit
func transformFloat64(data: Float64): Unit
func transformRunes(data: Array<Rune>): Unit
func transformInt16Array(data: Array<Int16>): Unit
func transformInt32s(data: Array<Int32>): Unit
func transformInt64s(data: Array<Int64>): Unit
func transformUInt16s(data: Array<UInt16>): Unit
func transformUInt32s(data: Array<UInt32>): Unit
func transformUInt64s(data: Array<UInt64>): Unit
func transformFloat32s(data: Array<Float32>): Unit
func transformFloat64s(data: Array<Float64>): Unit
func transformStream(data: IOStream, length!: Int64): Unit
func transformFile(fileName: String, from: Int64, length: Int64): Unit
func transformFile(fileName: Path, from: Int64, length: Int64): Unit
}
2.2 三个元信息属性
name:返回算法类名,由 src/hash.cj 中通过TypeInfo.of(this).name反射得到;hashSize:摘要字节数(即HashResult的字节长度);blockSize:底层算法一次处理的数据块字节数。
块类哈希的这两个值在基类构造时注入,例如 src/crypto/sha3/keccak/keccak_base.cj 中 Keccak 的 hashSize 取 HashSize 枚举对应值、blockSize 为 200 - hashSize * 2(对应标准海绵结构速率 rate)。位宽枚举定义在 src/hash_size.cj 中:
public enum HashSize {
| HashSize128
| HashSize160
| HashSize192
| HashSize224
| HashSize256
| HashSize384
| HashSize512
public func getInt(): Int64 {
match (this) {
case HashSize128 => 16
case HashSize160 => 20
case HashSize192 => 24
case HashSize224 => 28
case HashSize256 => 32
case HashSize384 => 48
case HashSize512 => 64
}
}
}
2.3 initialize():复用实例前必须重置
initialize() 用于将哈希对象恢复到初始状态。以 src/hash.cj 的 computeBytes 为例,完整生命周期是:
initialize() // 1. 重置内部状态
transformBytes(data) // 2. 喂入数据
let result = transformFinal() // 3. 收尾并取结果
initialize() // 4. 再次重置,便于复用
因此同一个哈希实例可以被反复调用 compute* / transform*,无需每次重新 new。
三、一次性哈希计算:compute 系列
3.1 标量输入
computeByte、computeBool、computeRune、computeInt16/32/64、computeUInt16/32/64、computeFloat32/64、computeStringUTF8 分别接受对应标量类型。其实现均收敛为“先转字节数组,再调用 computeBytes”,例如:
public func computeByte(data: Byte): HashResult {
let temp: Array<Byte> = [data]
return computeBytes(temp)
}
3.2 数组输入
computeBytes、computeRunes、computeInt16s、computeInt32s、computeInt64s、computeUInt16s、computeUInt32s、computeUInt64s、computeFloat32s、computeFloat64s 接受 Array 类型,内部通过 src/toolkit/bit_converter.cj 的 convertInt16sToBytes、convertUInt32sToBytes 等函数批量转换为字节。
3.3 类型统一转换规则(重要)
无论标量还是数组,所有类型最终都经过 convertToBytes / getBytes 按**小端(Little Endian)**写入字节(见 src/toolkit/bit_converter.cj):
Bool:true→[1],false→[0];Rune/ 各整数 / 浮点数:按位宽写入小端字节,例如Float32写 4 字节、Float64写 8 字节;String:value.toArray()得到 UTF-8 字节序列。
特别注意:README 的“特别说明”提醒,参考项目 HashLib 中字符串默认按 UTF-16 编码,因此直接使用 String 相关 API(computeStringUTF8 / transformStringUTF8)计算哈希时,结果与参考项目不同。这是本项目有意为之的设计,跨语言对比摘要值时务必注意编码约定。
3.4 computeAny / transformAny:多态分发
computeAny(data: Any) 在 src/hash.cj 中通过 match 按运行时类型自动分发到对应 compute* 方法,transformAny 同理(src/hash.cj)。若类型不支持,抛出 Exception("unsupport data type ...")。这一设计让上层业务可以传入任意受支持类型而无需手写分支。
四、增量哈希计算:transform 系列
当数据是分片到达(如网络包、大文件流式读取)时,可使用增量模式:
import hashlib4cj.crypto.Gost
main(): Unit {
let gost = Gost()
gost.transformInt8(4)
gost.transformStringUTF8("hashlib4cj")
let res1 = gost.transformFinal()
println(res1)
}
执行结果为:
2DC3ED61D86DEB390588C495A33A01C0859745F64E725E0CBBEE72F0E6D04A44
要点:
transformBytes(data)/transformBytes(data, index)/transformBytes(data, index, length)支持按偏移与长度喂入子区间;index < 0或剩余长度非法时会抛出异常(见 src/hash.cj);transformFinal()结束计算并返回HashResult,之后内部自动重置;- 增量喂入与一次性计算结果必须一致,这正是 HLT 测试
testMultipleTransformsWithRandomData的核心断言(见 src/test/HLT/hashes_hlt_base_test.cj):把随机数据拆成多段transformBytes,与整体computeBytes的HashResult用@Expect比对相等。
五、HashResult:统一的结果类型
5.1 构造与输出 API 原文
public class HashResult {
public init(data: UInt32)
public init(data: Int32)
public init(data: UInt64)
public init(data: Int64)
public init(data: Array<Byte>)
/*多种输出*/
public func getBytes(): Array<Byte>
public func getUInt32(): UInt32
public func getInt32(): Int32
public func getUInt64(): UInt64
public func getInt64(): Int64
public func toString(): String
public func equals(other: HashResult): Bool
public operator func ==(rhs: HashResult): Bool
public func clone(): HashResult
public func getHashCode(): Int64
}
5.2 实现细节(src/hashresult.cj)
HashResult 内部仅持有一个 Array<Byte>,构造时:
- 传入
UInt32/Int32/UInt64/Int64:通过convertToBytes转换为小端字节序列; - 传入
Array<Byte>:直接引用该字节数组。
输出时:
getBytes()返回原始字节数组;getUInt32()/getInt32()/getUInt64()/getInt64()使用readLittleEndian从字节序列按小端解析出数值——对 32 位哈希(如 AP、BKDR)取前 4 字节,对 64 位哈希取前 8 字节;toString()将字节转换为大写十六进制字符串(toHexString(hash).toAsciiUpper()),因此打印出的摘要均为大写字母形式;equals(other)与运算符重载==均按字节序列逐位比较,HashResult实现了Equatable<HashResult>与ToString;clone()返回一份相同字节序列的新实例;getHashCode()基于 Base64 编码串的hashCode()生成,便于在哈希表等容器中使用。
HLT 测试 src/test/HLT/hashresult_test.cj 用随机字节验证了 getBytes() 与 getUInt32() / getUInt64() 小端读取的一致性。
六、流与文件的哈希计算
6.1 computeStream / transformStream
接口中 length 参数带 ! 标记表示命名参数(有默认值),默认 -1 表示读取到流末尾;传入非负值时只处理指定长度的字节。在 src/hash.cj 的实现中:
- 若流是
Seekable且position + length > length,抛出Exception("The length is greater than the file size");若当前位置已到末尾则直接返回; - 读取端协程
readerSpawn按Hash.BUFFER_SIZE分块读取并放入BlockingQueue<Array<Byte>>; - 计算端协程
hasherSpawn从队列取块调用transformBytes,实现读与算并行的流水线处理。
Hash.BUFFER_SIZE 定义于 src/hash.cj:public static var BUFFER_SIZE: Int64 = 64 * 1024(默认 64 KiB)。HLT 测试 testHashStream 会分别以 blockSize=26 与 blockSize=BUFFER_SIZE 两种缓冲尺寸,用 1~BUFFER_SIZE*20+511 等 22 种长度验证 computeStream 与 computeBytes 结果一致,并断言超长/超界读取会抛异常(见 src/test/HLT/hashes_hlt_base_test.cj)。
6.2 computeFile / transformFile
computeFile(fileName: String, from: Int64, length: Int64) 与 computeFileFromPath(fileName: Path, ...) 用于直接对文件做一次性哈希;transformFile 支持在增量计算中嵌入文件片段。实现(src/hash.cj):
public func computeFile(fileName: String, from: Int64, length: Int64): HashResult {
initialize()
transformFile(fileName, from, length)
let result = transformFinal()
initialize()
return result
}
参数语义:
from:文件内起始偏移(SeekPosition.Begin(from)),可用于只校验文件的某一段;length:需要处理的字节数,-1表示从from读到文件末尾;- 底层复用
transformStream的并行流水线。
testHashFile(src/test/HLT/hashes_hlt_base_test.cj)验证了“文件整体计算 == 内存 computeBytes”、“transformBytes 分段 + transformFile 片段 + transformBytes 收尾 == 整体一次性计算”两条等价性。
七、实现类如何接入 IHash
7.1 两条实现路径
从源码结构看,具体算法通过两个抽象基类接入 IHash:
- 块哈希:src/blockhash.cj 的
BlockHash <: Hash & IBlockHash,内部维护HashBuffer缓冲(src/hashbuffer.cj),数据先填满缓冲区再调用子类的transformBlock,transformFinal时先finish()再getResult()。加密哈希如 Echo256(super(HashSize256))即走此路径。 - 非块哈希:src/multiple_transform_nonblock.cj 的
MultipleTransformNonBlock <: Hash & INonBlockHash,把多次transformBytes的输入先聚合(aggregate)成一段连续字节,再一次性computeAggregatedBytes。例如 32 位哈希 AP(super(4, 1))、Murmur2 均属于此类。
7.2 IFastHash32:免装箱的快速路径
IHash32 的若干实现(如 Murmur2)还实现了 src/ihash_info.cj 中的 IFastHash32,直接返回 Int32 而非 HashResult,并提供 computeStringFast、computeBytesFast 等针对标量/数组的快速重载,适合高频散列场景,避免构造结果对象。
八、完整实战:从引入依赖到运行
8.1 引入依赖
在 cjpm.toml 的 [dependencies] 中添加:
hashlib4cj = { git = "https://gitcode.com/FriskKA/hashlib4cj", branch = "main" }
然后在控制台执行:
cjpm update
8.2 编译构建
cjpm build
当前项目 cjpm.toml 中声明 cjc-version = "0.58.3",README 约束支持仓颉版本 0.58.3。
8.3 基本计算示例
对字符串做一次性哈希(UTF-8 编码):
import hashlib4cj.crypto.sha3.echo.Echo256
main(): Unit {
let echo = Echo256()
let res = echo.computeStringUTF8("hashlib4cj")
println(res)
}
执行结果(toString() 的大写十六进制输出):
40484FF47B824758E508AB20C478008738569B2BC6DF3C5745285B31A58A36F3
8.4 多类型输出示例
HashResult 支持多种输入与输出,可将摘要按小端解析为数值:
import hashlib4cj.crypto.Gost
main(): Unit {
let gost = Gost()
let res = gost.computeInt32(4)
println(res.getInt64())
}
执行结果:
-3174266761618810304
九、测试与正确性保障
仓库以双层测试体系保障 API 行为:
- HLT(高层测试):
HashesHLTBaseTest测试模板(src/test/HLT/hashes_hlt_base_test.cj)对每个哈希执行四类校验——多段增量与一次性等价、流式与computeBytes等价、文件与内存等价、以及对照test_data/下参考测试文件校验标准向量; - LLT(底层测试):如 src/test/LLT/hashresutl_test.cj、src/test/LLT/toolkit_test/bit_converter_test.cj 等,覆盖类型转换、缓冲区等基础设施。
这意味着对任何实现了 IHash 的新算法,只要通过这套测试模板,其一次性/增量/流/文件四种计算路径的一致性即得到保证。
十、小结
IHash + HashResult 构成了 hashlib4cj 的统一 API 骨架:compute* 提供零门槛的一次性计算,transform* + transformFinal() 提供大数据的增量与流式处理,HashResult 屏蔽了各算法输出位宽的差异,提供字节、整数与十六进制字符串三种视图。理解这套接口,即可在仓颉项目中自由组合 80+ 种哈希算法,并安全地在一次性、增量、流、文件四种场景间切换。