仓颉 std.crypto.digest 包详解:Digest 通用接口与 digest 泛型函数实战指南

原创2026-10-14 17:01:041,680 阅读
文章标签:编程语言语言运行时标准库内存管理OpenHarmony

仓颉 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,其中 Byte 类型定义见 core_package_types.md。

完整示例(文档自带,可直接运行):

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
}

从中可以归纳出三条关键语义:

  1. 调用链固定为 reset → write → finish → reset。无论是字节数组还是输入流版本,函数都会在计算前先 reset() 清理算法实例的残留状态(保证同一个实例可被重复使用),计算完成后再次 reset() 恢复初始状态。这意味着传入的算法实例会被函数"借用",调用方无需自行 reset,且函数内部不会因多次调用而累积脏数据。

  2. 输入流按 blockSize 分块读取。输入流版本以 algorithm.blockSize 为长度分配读取缓冲区 buffer,循环调用 input.read(buffer),每次将读到的 len 字节(buffer[..len])通过 write 喂入算法;当 read 返回 0(流结束)时终止循环。因此,blockSize 属性不仅是算法自身的分块长度,也直接决定了流式摘要时每次 I/O 读取的块大小。

  3. 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 等摘要能力,或自行实现并注册新的摘要算法。

登录后查看全文
cangjie_runtime