仓颉 std.crypto.digest 包详解:Digest 通用接口与 digest 泛型函数实战指南
仓颉 std.crypto.digest 包详解:Digest 通用接口与 digest 泛型函数实战指南
导读
std.crypto.digest 是仓颉标准库中面向摘要(digest)运算的统一接口层,为 MD5、SHA1、SHA224、SHA256、SHA384、SHA512、HMAC、SM3 等常用摘要算法提供一致的编程模型。本文围绕该包官方文档,完整讲解 Digest 接口的成员语义、三个 digest 泛型函数重载的签名与行为,并结合仓库源码剖析其内部调用链(reset → write → finish),最终通过三个可运行的完整示例,帮助你掌握在仓颉程序中调用摘要算法、自定义摘要算法实现以及处理流式数据的实战能力。
包定位:为多种摘要算法提供统一接口
std.crypto.digest 包位于 stdlib/libs/std/crypto/digest/,其核心设计目标非常明确:不绑定任何具体算法,而是定义一个所有摘要算法实现都必须遵守的通用契约。官方文档(digest_package_overview.md)指出,该包面向的算法包括 MD5、SHA1、SHA224、SHA256、SHA384、SHA512、HMAC、SM3 等。
从当前仓库源码结构看,该包目录下仅包含一个源文件 cryptolib.cj(由 CMakeLists.txt 中的 DIGEST_SRCS 变量纳入构建),其中定义了:
Digest接口:摘要算法的通用接口;- 三个
digest<T>泛型函数:面向Array<Byte>、InputStream、String三种数据形态的摘要入口。
也就是说,具体的算法类(如 MD5、SHA256 的实现)并不在该包的源码目录内,而是由实现方(例如库厂商适配层或第三方实现)通过实现 Digest 接口来提供;上层业务代码只需面向 Digest 接口与 digest 泛型函数编程即可,切换算法时无需改动调用逻辑。这种"接口统一、实现可插拔"的架构,正是该包的核心价值所在。
Digest 接口:摘要算法的统一契约
Digest 接口是摘要运算的抽象契约。其完整定义如下(见 cryptolib.cj 与 digest_package_interfaces.md):
public interface Digest {
prop size: Int64
prop blockSize: Int64
prop algorithm: String
func write(buffer: Array<Byte>): Unit
func finish(to!: Array<Byte>): Unit
func finish(): Array<Byte>
func reset(): Unit
}
继承该接口的 class、interface、struct 都需要遵守其中函数(及属性)的入参与返回值定义。接口成员逐一说明如下:
属性成员
| 属性 | 签名 | 语义 |
|---|---|---|
size |
prop size: Int64 |
返回生成的摘要信息长度,单位字节。例如 MD5 为 16 字节、SHA256 为 32 字节。 |
blockSize |
prop blockSize: Int64 |
返回算法进行分块处理时的块长度(Block 长度),单位字节。该值决定了摘要计算时每次喂给算法的数据分块大小。 |
algorithm |
prop algorithm: String |
获取摘要算法的算法名称,例如 "MD5"、"SHA256"。 |
其中 size 与 blockSize 的类型为 Int64,algorithm 的类型为 String。
函数成员
| 函数 | 签名 | 语义 |
|---|---|---|
write |
func write(buffer: Array<Byte>): Unit |
使用给定的 buffer 更新 digest 对象。即把一段待摘要数据"喂"进算法上下文,可被多次调用来处理分片数据。 |
finish() |
func finish(): Array<Byte> |
返回生成的摘要值(一次性完整结果)。 |
finish(to!) |
func finish(to!: Array<Byte>): Unit |
将生成的信息摘要值写入调用方提供的目标数组 to(! 表示输出参数,调用方负责分配容量)。注意:调用 finish 后不可以再进行摘要计算,如需重新计算必须先调用 reset() 重置上下文。 |
reset() |
func reset(): Unit |
重置 digest 对象到初始状态,用于复用同一个算法实例进行多次摘要运算。 |
值得注意的一个源码细节:finish(): Array<Byte> 在接口中带有默认实现,它会先按 size 分配一个字节数组,再调用 finish(to: buf) 填充并返回(见 cryptolib.cj):
func finish(): Array<Byte> {
let buf = Array<Byte>(size, repeat: 0)
this.finish(to: buf)
return buf
}
这意味着实现类只需实现 finish(to!),即可免费获得 finish() 的便捷封装;当然实现类也可以自行重写 finish() 以定制行为。
digest 泛型函数:三种数据形态的摘要入口
包提供了三个 digest<T> 泛型函数,约束均为 where T <: Digest,即第一个参数必须是某个实现了 Digest 接口的算法类型。三者按输入数据形态区分:
| 函数 | 输入形态 | 状态 |
|---|---|---|
digest<T>(algorithm: T, data: Array<Byte>): Array<Byte> |
内存中的字节数组 | 推荐使用 |
digest<T>(algorithm: T, input: InputStream): Array<Byte> |
输入流(文件、网络、内存流等) | 推荐使用(流式) |
digest<T>(algorithm: T, data: String): Array<Byte> |
字符串 | 已标记 deprecated,建议改用字节数组版本 |
返回值统一为 Array
1. 面向字节数组:digest(T, Array)
public func digest<T>(algorithm: T, data: Array<Byte>): Array<Byte> where T <: Digest
该重载是日常最常用的形态,适合对内存中已有的完整数据进行摘要运算。参数 data 的类型为 Array
完整示例(文档自带,可直接运行):
import std.crypto.digest.*
main() {
let data: Array<Byte> = [1, 2, 3, 4, 5]
let mydigest = MyDigest()
let digestBytes = digest<MyDigest>(mydigest, data)
println(digestBytes)
}
// 自定义 Digest
class MyDigest <: Digest {
public prop size: Int64 {
get() {
0
}
}
public prop blockSize: Int64 {
get() {
0
}
}
public prop algorithm: String {
get() {
""
}
}
public func write(buffer: Array<Byte>): Unit {
println("buffer = ${buffer}")
}
public func finish(to!: Array<Byte>): Unit {
println("to = ${to}")
}
public func finish(): Array<Byte> {
[3, 2, 1]
}
public func reset(): Unit {}
}
运行结果:
buffer = [1, 2, 3, 4, 5]
[3, 2, 1]
可以看到:write 收到完整数据 [1, 2, 3, 4, 5],随后 finish() 返回 [3, 2, 1] 作为摘要结果。
2. 面向输入流:digest(T, InputStream)
public func digest<T>(algorithm: T, input: InputStream): Array<Byte> where T <: Digest
该重载用于对流式数据做摘要,非常适合大文件、网络数据等无法一次性载入内存的场景。参数 input 的类型为 InputStream(定义见 stream.cj)。
一个重要的行为约定:当 digest 函数调用 input.read() 读取数据返回值为 0 时,digest 函数会认为 InputStream 已经读取完毕,不会继续读取。这一约定与 InputStream 接口自身的语义完全一致——stream.cj 中明确规定:read 返回值为实际读入缓冲区的字节数(永不返回 0,除非流已到末尾),返回 0 即表示流结束。
完整示例(文档自带,可直接运行):
import std.crypto.digest.*
import std.io.*
main() {
/* 将原始的字节数组 data 转换为一个输入流 BufferedInputStream */
let data: Array<Byte> = [1, 2, 3, 4, 5]
let byteBuffer = ByteBuffer(data)
let bufferedInputStream = BufferedInputStream(byteBuffer)
let mydigest = MyDigest()
let digestBytes = digest<MyDigest>(mydigest, bufferedInputStream)
println(digestBytes)
}
// 自定义 Digest
class MyDigest <: Digest {
public prop size: Int64 {
get() {
0
}
}
public prop blockSize: Int64 {
get() {
2
}
}
public prop algorithm: String {
get() {
""
}
}
public func write(buffer: Array<Byte>): Unit {
println("buffer = ${buffer}")
}
public func finish(to!: Array<Byte>): Unit {
println("to = ${to}")
}
public func finish(): Array<Byte> {
[3, 2, 1]
}
public func reset(): Unit {}
}
运行结果:
buffer = [1, 2]
buffer = [3, 4]
buffer = [5]
[3, 2, 1]
对比字节数组版本可以看到流式处理的关键差异:本例中 blockSize 为 2,因此数据 [1, 2, 3, 4, 5] 被拆分成 [1, 2]、[3, 4]、[5] 三个分块,依次通过 write 喂给算法,最后一次只剩余 1 个字节也照常处理。blockSize 直接影响流式读取的分块粒度,实现类应将其设为算法自身的分块长度。
3. 面向字符串:digest(T, String)(已废弃)
public func digest<T>(algorithm: T, data: String): Array<Byte> where T <: Digest
该重载对字符串数据进行摘要运算,但官方已明确标注 deprecated:未来版本即将废弃,建议使用 digest<T>(T, Array<Byte>) 替代(即先通过 String.toArray() 转成字节数组再计算)。在源码中,该函数通过 @Deprecated<a href="https://link.gitcode.com/i/52505d8a86975f68f753108ff25ed41d" target="_blank">message: "..."] 注解标记,并直接转调字节数组版本实现(见 [cryptolib.cj):
@Deprecated[message: "Use global function `public func digest<T>(algorithm: T, input: InputStream): Array<Byte> where T <: Digest` instead."]
public func digest<T>(algorithm: T, data: String): Array<Byte> where T <: Digest {
digest(algorithm, data.toArray())
}
完整示例(文档自带):
import std.crypto.digest.*
main() {
// 创建一些测试数据
let data = "Hello, World!"
// 创建一个自定义的摘要算法实例
let mydigest = MyDigest()
// 使用digest函数处理字符串数据
let digestBytes = digest<MyDigest>(mydigest, data)
println("Input string: '${data}'")
println("Digest result: ${digestBytes}")
}
// 自定义 Digest 算法
class MyDigest <: Digest {
public prop size: Int64 {
get() {
3
}
}
public prop blockSize: Int64 {
get() {
1
}
}
public prop algorithm: String {
get() {
"MyDigest"
}
}
public func write(buffer: Array<Byte>): Unit {
println("Processing buffer with ${buffer.size} bytes")
}
public func finish(to!: Array<Byte>): Unit {
to[0] = 1
to[1] = 2
to[2] = 3
}
public func finish(): Array<Byte> {
[1, 2, 3]
}
public func reset(): Unit {}
}
运行结果:
Processing buffer with 13 bytes
Input string: 'Hello, World!'
Digest result: [1, 2, 3]
本例展示了另一个值得学习的点:finish(to!) 的实现直接向目标数组 to 的 [0]、[1]、[2] 三个位置写入 1, 2, 3,而 size 属性返回 3——两者必须保持一致,因为 finish(): Array<Byte> 的默认实现正是按 size 大小分配目标数组后调用 finish(to!),若 size 与写入长度不符会导致数据错位或越界。
源码级剖析:digest 函数的完整调用链
理解 digest 泛型函数的内部实现,有助于把握算法实例的生命周期约束。三个重载的实现在 cryptolib.cj 中完整可见:
字节数组版本(cryptolib.cj):
public func digest<T>(algorithm: T, data: Array<Byte>): Array<Byte> where T <: Digest {
var algorithmMutable = algorithm
algorithmMutable.reset()
algorithmMutable.write(data)
let result = algorithmMutable.finish()
algorithmMutable.reset()
return result
}
输入流版本(cryptolib.cj):
public func digest<T>(algorithm: T, input: InputStream): Array<Byte> where T <: Digest {
var buffer = Array<Byte>(algorithm.blockSize, repeat: 0)
while (true) {
var len = input.read(buffer)
if (len == 0) {
break
}
algorithm.write(buffer[..len])
}
var result = algorithm.finish()
algorithm.reset()
return result
}
从中可以归纳出三条关键语义:
-
调用链固定为 reset → write → finish → reset。无论是字节数组还是输入流版本,函数都会在计算前先
reset()清理算法实例的残留状态(保证同一个实例可被重复使用),计算完成后再次reset()恢复初始状态。这意味着传入的算法实例会被函数"借用",调用方无需自行 reset,且函数内部不会因多次调用而累积脏数据。 -
输入流按 blockSize 分块读取。输入流版本以
algorithm.blockSize为长度分配读取缓冲区buffer,循环调用input.read(buffer),每次将读到的len字节(buffer[..len])通过write喂入算法;当read返回 0(流结束)时终止循环。因此,blockSize属性不仅是算法自身的分块长度,也直接决定了流式摘要时每次 I/O 读取的块大小。 -
finish 之后必须 reset 才能复用。这与接口文档中"调用 finish 后不可以再进行摘要计算,如重新计算需要执行 reset 函数重置上下文"的约束一一对应;
digest泛型函数在内部妥善处理了这一约束,因此对调用方是透明的。
实战要点与最佳实践
综合官方文档与源码实现,在实际使用 std.crypto.digest 时有以下几点值得注意:
- 面向接口编程:业务代码只依赖
Digest接口与digest泛型函数,具体的 MD5、SHA256、SM3 等算法实例由实现方注入。切换算法时只需更换digest<MyDigest>(...)中的泛型实参,调用逻辑零改动。 - 大文件优先走流式:对超大文件或网络流做摘要,应使用
digest<T>(T, InputStream)重载,配合 ByteBuffer、BufferedInputStream 等 std.io 流类型,避免将全部数据载入内存。注意流读取结束的判定依据是read()返回 0。 - 字符串数据用字节数组版本:字符串重载已废弃,新代码应先将
String转为字节数组(如data.toArray())再调用字节数组版本。 - 自定义算法需对齐 size 与 finish(to!):实现
Digest接口时,size(摘要长度)必须与finish(to!)实际写入的字节数一致;blockSize应返回算法真实的分块长度,它同时影响流式分块粒度。 - 算法实例可复用:由于
digest泛型函数内部已包含完整的 reset 生命周期,同一个算法实例可以安全地传入多次调用。
总结
std.crypto.digest 包通过一个 Digest 接口和三个 digest<T> 泛型函数,为仓颉程序提供了统一、简洁、可扩展的摘要计算入口。本文完整覆盖了官方文档(digest_package_overview.md、digest_package_funcs.md、digest_package_interfaces.md)的全部 API 说明与可运行示例,并结合 cryptolib.cj 源码揭示了 reset → write → finish → reset 的完整调用链、流式分块读取语义以及字符串重载的废弃原因。掌握了这套接口,你即可在仓颉项目中轻松接入 MD5、SHA 系列、HMAC、SM3 等摘要能力,或自行实现并注册新的摘要算法。