Java Base64.Decoder 怎样区分普通与 URL 安全编码

Java 的 Base64.Decoder 不是“拿到 Base64 就随便解码”。先看输入使用哪套字母表：普通 Base64 使用 + 和 /，URL 与文件名安全 Base64 使用 - 和 _。前者调用 Base64.getDecoder()，后者调用 Base64.getUrlDecoder()；两种解码器都返回 Base64.Decoder，但不会替对方容忍另一套专用字符。

Oracle Java SE API 对 Basic、URL and Filename safe、MIME 三种形式分别定义了解码器。本文只处理前两种在接口参数、文件名和链接参数中最容易混淆的边界。

先按字母表选对 Decoder

判断规则可以压缩成一句话：数据协议里出现 +、/，优先按普通 Base64 处理；出现 -、_，按 URL 安全 Base64 处理。不要因为字符串来自 URL，就只对普通 Base64 做字符串替换后继续使用普通解码器，编码和解码应当使用同一套字母表。

下面的例子故意使用同一组字节，让两个编码结果只在字母表上体现差异。代码注释说明的是选择理由，不代表这里执行过本地验证。

import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class Base64DecoderChoice {
    public static void main(String[] args) {
        // 普通 Base64 的 + 和 / 可能在 URL 或文件名中有特殊含义。
        byte[] source = {(byte) 0xfb, (byte) 0xff};
        String basic = Base64.getEncoder().encodeToString(source);
        String urlSafe = Base64.getUrlEncoder().encodeToString(source);

        // 解码器必须匹配编码器：basic 对应 getDecoder，urlSafe 对应 getUrlDecoder。
        byte[] basicBytes = Base64.getDecoder().decode(basic);
        byte[] urlBytes = Base64.getUrlDecoder().decode(urlSafe);
        System.out.println(basic + " / " + urlSafe);
        System.out.println(basicBytes.length + " / " + urlBytes.length);
    }
}

普通 Base64 与 URL 安全 Base64 的差别在哪里

两套编码的主要差别是索引 62 和 63 对应的字符：Basic 使用 +、/，URL 与文件名安全形式改为 -、_。这样做是为了避免字符在 URL 查询参数、路径或文件名中承担分隔含义；它仍然是编码，不是加密。

如果上游明确约定了 URL 安全 Base64，Java 代码就应把这个约定写在方法名或参数说明里。仅凭“这是一段看起来像 Base64 的字符串”无法可靠推断协议，因为很多普通输入只包含两套字母表的公共字符。

import java.util.Base64;

public class Base64ProtocolBoundary {
    static byte[] decodeToken(String token, boolean urlSafe) {
        // urlSafe 必须来自协议约定，不能由一次偶然的字符扫描猜测。
        Base64.Decoder decoder = urlSafe
                ? Base64.getUrlDecoder()
                : Base64.getDecoder();
        try {
            // decode(String) 返回原始字节，后续再按业务约定选择字符集。
            return decoder.decode(token);
        } catch (IllegalArgumentException ex) {
            // 把格式错误转换成调用方可识别的输入失败，不要静默改字符。
            throw new IllegalArgumentException("Base64 字母表或格式不符合协议", ex);
        }
    }
}

如果解码结果代表文本，再使用明确的字符集，例如 new String(bytes, StandardCharsets.UTF_8)。Base64 只负责字节到 ASCII 文本的表示，不会告诉你原始字节应该按 UTF-8、GBK 还是二进制文件解释。

填充与非法字符要分开处理

= 是最后一个编码单元的填充字符。Java 的 Base64.Decoder 接受正确的填充，也接受末尾缺少填充的两字符或三字符编码单元，并按需要补齐；如果输入带了填充，数量不正确仍会在解码时抛出 IllegalArgumentException。

因此，收到没有 = 的字符串时，不要无条件追加两个等号。先确认它确实属于允许省略填充的 Base64 约定；如果协议要求标准填充，则应在协议边界补齐或拒绝输入。更不能把 URL 安全的 -、_ 改回 +、/ 来“抢救”普通解码。

import java.util.Base64;

public class Base64PaddingBoundary {
    public static void main(String[] args) {
        // 这两个输入表示同一段字节：一个带标准填充，一个省略了末尾等号。
        String padded = "SGVsbG8=";
        String unpadded = "SGVsbG8";
        byte[] first = Base64.getDecoder().decode(padded);
        byte[] second = Base64.getDecoder().decode(unpadded);

        // URL 安全输入必须交给 URL 解码器，字符表不匹配会进入异常分支。
        String urlToken = "-_8=";
        byte[] urlBytes = Base64.getUrlDecoder().decode(urlToken);
        System.out.println(first.length + " / " + second.length + " / " + urlBytes.length);
    }
}

异常处理也要分层：字母表不匹配、非法字符、错误填充属于输入格式问题；解码成功后把字节转成业务对象，则还可能出现字符集错误、长度不满足协议或字段校验失败。不要把这些不同阶段都包装成“Base64 解码失败”。

把编码约定固定在跨系统边界

在 HTTP 参数、Cookie、文件名或对象存储键中，建议把“普通还是 URL 安全”“是否省略填充”“原始字节如何解释”写进接口契约。解码方法接收一个清晰的协议类型，比根据字符内容自动猜测更稳定。

可以按下面的顺序落地：

1. 先确认上游编码器是 getEncoder() 还是 getUrlEncoder()。
2. 选择对应的 Decoder，并保留 IllegalArgumentException 的输入错误语义。
3. 确认协议是否允许省略填充，不能把补等号当作通用修复。
4. 解码得到字节后，再按协议约定处理字符集、JSON、文件头或二进制结构。

速查：普通 Base64 看 +、/，调用 getDecoder()；URL 安全 Base64 看 -、_，调用 getUrlDecoder()；缺少末尾填充不一定是错误，但错误填充和不属于当前字母表的字符应当按输入异常处理。

常见问题

URL 解码器能不能解码所有普通 Base64？

不能把它当作通用替代品。只含公共字符的字符串可能恰好能被两者解码，但一旦输入包含 + 或 /，就不符合 URL 与文件名安全字母表；应遵循上游协议，而不是依赖偶然兼容。

Base64 解码后乱码，是 Decoder 选错了吗？

不一定。先区分字母表错误和字符集解释错误：Decoder 只返回字节，文本展示需要使用协议指定的字符集。编码器、解码器和字符集三者都要在跨系统边界明确约定。