完善不同加密方法的使用

md5x/md5x.go

@@ -1,40 +1,99 @@
+// Package md5x 提供 MD5 摘要计算，以及十六进制/Base64 编码与流式、文件接口。
+//
+// # 安全警告
+//
+// MD5 已被证明无法抵抗碰撞攻击，攻击者可以构造出摘要完全相同的两份不同数据。
+// 本包仅用于兼容旧系统或非安全用途（如文件校验和、缓存键、内容指纹），
+// 不可用于口令存储、口令派生、消息认证或数字签名。
+// 新代码请使用 sha256x、sha512x、sha3x 或 blake2x。
 package md5x
 
 import (
 	"crypto/md5"
+	"encoding/base64"
 	"encoding/hex"
+	"fmt"
+	"hash"
 	"io"
 	"os"
 )
 
-// 字符串的md5
-func Md5String(value string) string {
-	return Md5Byte([]byte(value))
+const (
+	// Size 是 MD5 摘要的字节数（16）。
+	Size = md5.Size
+	// BlockSize 是 MD5 分组的字节数（64）。
+	BlockSize = md5.BlockSize
+)
+
+// New 返回一个计算 MD5 摘要的 hash.Hash，可反复 Write 以流式处理数据。
+//
+// 安全警告：MD5 不安全，仅用于兼容旧系统或非安全用途（如校验和），不可用于口令或签名。
+func New() hash.Hash {
+	return md5.New()
 }
 
-func Md5Byte(b []byte) string {
-	m := md5.New()
-	m.Write(b)
-	return hex.EncodeToString(m.Sum(nil))
+// Sum 返回 data 的 MD5 摘要（Size 字节原始数据）。
+//
+// 安全警告：MD5 不安全，仅用于兼容旧系统或非安全用途（如校验和），不可用于口令或签名。
+func Sum(data []byte) []byte {
+	h := md5.New()
+	_, _ = h.Write(data)
+	return h.Sum(nil)
 }
 
-// 文件的md5
-func Md5File(path string) (string, error) {
-	file, err := os.Open(path)
+// Hex 返回 data 的 MD5 摘要的小写十六进制字符串。
+//
+// 安全警告：MD5 不安全，仅用于兼容旧系统或非安全用途（如校验和），不可用于口令或签名。
+func Hex(data []byte) string {
+	return hex.EncodeToString(Sum(data))
+}
+
+// Base64 返回 data 的 MD5 摘要的标准 Base64 字符串。
+//
+// 安全警告：MD5 不安全，仅用于兼容旧系统或非安全用途（如校验和），不可用于口令或签名。
+func Base64(data []byte) string {
+	return base64.StdEncoding.EncodeToString(Sum(data))
+}
+
+// SumReader 读取 r 中的全部数据并返回其 MD5 摘要；读取失败时返回包装后的 error。
+//
+// 安全警告：MD5 不安全，仅用于兼容旧系统或非安全用途（如校验和），不可用于口令或签名。
+func SumReader(r io.Reader) ([]byte, error) {
+	if r == nil {
+		return nil, fmt.Errorf("md5x: 读取器为 nil")
+	}
+	h := md5.New()
+	if _, err := io.Copy(h, r); err != nil {
+		return nil, fmt.Errorf("md5x: 读取数据失败: %w", err)
+	}
+	return h.Sum(nil), nil
+}
+
+// HexReader 读取 r 中的全部数据并返回其 MD5 摘要的小写十六进制字符串。
+//
+// 安全警告：MD5 不安全，仅用于兼容旧系统或非安全用途（如校验和），不可用于口令或签名。
+func HexReader(r io.Reader) (string, error) {
+	sum, err := SumReader(r)
 	if err != nil {
 		return "", err
 	}
-	defer file.Close()
-
-	return Md5Stream(file)
+	return hex.EncodeToString(sum), nil
 }
 
-// 流式的md5
-func Md5Stream(reader io.Reader) (string, error) {
-	hash := md5.New()
-	_, err := io.Copy(hash, reader)
+// HexFile 计算 path 所指向文件的 MD5 摘要并返回小写十六进制字符串；
+// 文件不存在或读取失败时返回包装后的 error，不 panic。
+//
+// 安全警告：MD5 不安全，仅用于兼容旧系统或非安全用途（如校验和），不可用于口令或签名。
+func HexFile(path string) (string, error) {
+	f, err := os.Open(path)
 	if err != nil {
-		return "", err
+		return "", fmt.Errorf("md5x: 打开文件 %q 失败: %w", path, err)
 	}
-	return hex.EncodeToString(hash.Sum(nil)), nil
+	defer f.Close()
+
+	sum, err := SumReader(f)
+	if err != nil {
+		return "", fmt.Errorf("md5x: 计算文件 %q 摘要失败: %w", path, err)
+	}
+	return hex.EncodeToString(sum), nil
 }