Java中如何正确编码包含特殊字符的图片URL路径？

问题根源 #

• URLEncoder.encode() 是为HTTP表单的application/x-www-form-urlencoded格式设计的，并非用于URL路径段编码，因此会把空格编码为+，不符合路径段的空格编码要求。
• Guava的UrlEscapers.urlPathSegmentEscaper() 遵循RFC 3986规范，默认将分号;视为路径段合法保留字符（用于矩阵参数场景），因此不会对其编码，不符合业务要求。

可行实现方案 #

方案1：URLEncoder 二次处理（实现最简单） #

URLEncoder默认已完成分号等特殊字符的编码，仅需将代表空格的+替换为路径段标准的%20即可，该操作不会影响文件名本身包含的+字符（原生+会被URLEncoder预先编码为%2B）。
代码示例：

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public static String encodeImageFileName(String fileName) {
    return URLEncoder.encode(fileName, StandardCharsets.UTF_8)
            .replace("+", "%20");
}

方案2：自定义Guava转义器（更符合路径编码规范） #

基于Guava的PercentEscaper自定义转义规则，移除原路径段安全字符中的分号;，即可实现分号自动编码，同时保留其他特殊字符的正确编码逻辑。
代码示例：

import com.google.common.net.PercentEscaper;

// 初始化自定义转义器，去掉原路径段安全字符中的分号;
private static final PercentEscaper IMAGE_NAME_ESCAPER = new PercentEscaper(
        "-._~!$&'()*+,=:@",
        false
);

// 调用转义
public static String encodeImageFileName(String fileName) {
    return IMAGE_NAME_ESCAPER.escape(fileName);
}

两种方案对示例文件名Some special Characters;.jpg的编码结果均为Some%20special%20Characters%3B.jpg，拼接路径后完全匹配需求。

内容的提问来源于stack exchange，提问作者Fynn