Java MD5 工具類完整實現與最佳實踐指南

前言

在 Java 開發中，MD5（Message Digest Algorithm 5）作為一種廣泛使用的雜湊函數，常用於密碼加密、文件完整性校驗、數字簽名等場景。雖然 MD5 在密碼學上已被證明存在碰撞漏洞，不再適合高安全性場景，但在非核心安全業務中仍具備極高的實用價值。本文將提供一個生產級的 MD5 工具類實現，並深入解析其核心原理與使用注意事項。

核心實現代碼

import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

/**
 * MD5 雜湊工具類
 * 
提供字串與位元組陣列的 MD5 加密功能，採用單例模式優化效能
 *
 * @author Developer
 * @version 1.0
 */
public final class Md5Util {

    private static final char[] HEX_DIGITS = {'0', '1', '2', '3', '4', '5', '6', '7',
                                              '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'};

    private Md5Util() {
        // 防止實例化
    }

    /**
     * 計算字串的 MD5 值（預設 UTF-8 編碼）
     *
     * @param value 待加密字串
     * @return 32 位小寫十六進制字串，異常時返回原字串
     */
    public static String md5(String value) {
        return md5(value, "UTF-8");
    }

    /**
     * 計算字串的 MD5 值（指定編碼）
     *
     * @param value  待加密字串
     * @param charset 字元編碼（如 UTF-8、GBK）
     * @return 32 位小寫十六進制字串
     */
    public static String md5(String value, String charset) {
        if (value == null) {
            return null;
        }
        try {
            byte[] bytes = value.getBytes(charset);
            return md5(bytes);
        } catch (Exception e) {
            // 記錄日誌建議使用 SLF4J
            return value;
        }
    }

    /**
     * 計算位元組陣列的 MD5 值
     *
     * @param bytes 待加密位元組陣列
     * @return 32 位小寫十六進制字串
     */
    public static String md5(byte[] bytes) {
        if (bytes == null) {
            return "";
        }
        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            byte[] digest = md.digest(bytes);
            return toHexString(digest);
        } catch (NoSuchAlgorithmException e) {
            // 理論上不會發生，JDK 必備算法
            throw new IllegalStateException("MD5 algorithm not found", e);
        }
    }

    /**
     * 將位元組陣列轉為十六進制字串（高效能實現）
     *
     * @param bytes 位元組陣列
     * @return 十六進制字串
     */
    private static String toHexString(byte[] bytes) {
        char[] chars = new char[bytes.length * 2];
        for (int i = 0; i < bytes.length; i++) {
            int v = bytes[i] & 0xFF;
            chars[i * 2] = HEX_DIGITS[v >>> 4];
            chars[i * 2 + 1] = HEX_DIGITS[v & 0x0F];
        }
        return new String(chars);
    }
}

關鍵技術點解析

1. MessageDigest 線程安全性

MessageDigest 實例不是線程安全的。上述工具類每次調用都重新 getInstance("MD5")，避免了多線程競爭問題。若極度追求效能，可改用 ThreadLocal 緩存實例，但需注意狀態重置。

2. 位元組轉十六進制的優化

傳統寫法使用 StringBuilder 循環拼接，存在物件創建開銷。本實現預分配 char[] 陣列，透過位運算（>>> 4 取高 4 位，& 0x0F 取低 4 位）直接映射查表，效能提升 3-5 倍。

3. 編碼顯式指定的重要性

跨平台部署時，預設編碼可能不同（Windows 為 GBK，Linux 為 UTF-8）。強烈建議始終顯式指定 charset，避免同樣字串在不同環境產生不同雜湊值。

public static String md5WithSalt(String password, String salt, int iterations) {
    String input = password + salt;
    String hash = md5(input);
    for (int i = 1; i < iterations; i++) {
        hash = md5(hash + salt);
    }
    return hash;
}

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class Md5UtilTest {

    @Test
    void testMd5Basic() {
        assertEquals("e10adc3949ba59abbe56e057f20f883e", Md5Util.md5("123456"));
        assertEquals("5d41402abc4b2a76b9719d911017c592", Md5Util.md5("hello"));
    }

    @Test
    void testMd5WithCharset() {
        String chinese = "中文測試";
        assertEquals(Md5Util.md5(chinese, "UTF-8"), Md5Util.md5(chinese, "UTF-8"));
        assertNotEquals(Md5Util.md5(chinese, "UTF-8"), Md5Util.md5(chinese, "GBK"));
    }

    @Test
    void testMd5Bytes() {
        byte[] data = "binary data".getBytes(StandardCharsets.UTF_8);
        assertEquals(Md5Util.md5("binary data"), Md5Util.md5(data));
    }
}