Java URI.getRawPath 怎样保留路径中的百分号转义

在 Java 中处理带百分号编码的 URI 路径时，最容易混淆的是“原始文本”和“解码后的值”。结论很直接：需要保留 %E4%B8%AD 这类转义文本时使用 URI.getRawPath()；需要按业务字符判断路径时使用 URI.getPath()。前者不解释 escaped octets，后者会把转义序列解码。

官方 API 地址：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/net/URI.html

先把两种路径表示分开

假设 URI 中的路径是 /docs/%E4%B8%AD%E6%96%87。这段文字里的百分号编码代表 UTF-8 字节序列，但它仍然是 URI 的原始表示。getRawPath() 返回 /docs/%E4%B8%AD%E6%96%87，getPath() 则返回 /docs/中文。

这不是两个不同的 URI，而是同一个路径组件的两种读取视图。做签名、保留请求原文或重新拼接 URI 时，编码字符不能被提前还原；做业务匹配、显示或判断目录名时，通常要使用解码后的值。

用 getRawPath 保留百分号转义

下面的示例只创建 URI 并读取两个访问器，代码本身不把图片当作运行证据。关键点是：getRawPath() 的结果可以原样放回 URI 文本语境，而 getPath() 的结果已经完成解码，不应再次当作原始编码串处理。

import java.net.URI;

public class UriPathView {
    public static void main(String[] args) {
        // 使用已经包含 UTF-8 百分号转义的路径，比较两种读取视图。
        URI uri = URI.create("https://example.com/docs/%E4%B8%AD%E6%96%87?tab=raw");

        // raw 视图保留 %E4%B8%AD%E6%96%87，适合保留 URI 文本表示。
        String rawPath = uri.getRawPath();
        // decoded 视图得到中文字符，适合业务层做路径判断。
        String decodedPath = uri.getPath();

        System.out.println("raw=" + rawPath);
        System.out.println("decoded=" + decodedPath);
    }
}

如果上游要校验签名原文、记录代理转发前的路径，优先传递 rawPath。如果要判断路径是否以 /docs/中文 开头，使用 decodedPath 更直观。两种值不要在同一层混用，否则很容易出现重复编码或比较不相等。

非法转义应在 URI 构造处处理

getRawPath() 不负责修复非法输入。URI 对象创建成功后，路径组件已经符合 URI 语法；如果输入含有不完整的百分号转义，例如 /docs/%E4%B8，应在构造阶段捕获异常并记录原始输入。

import java.net.URI;
import java.net.URISyntaxException;

public class UriParseBoundary {
    static URI parseWithCheckedError(String text) throws URISyntaxException {
        // 构造器保留受检异常，调用方可以把语法错误纳入明确的错误分支。
        return new URI(text);
    }

    static URI parseWithRuntimeError(String text) {
        try {
            // URI.create 适合输入已由上层保证格式的场景。
            return URI.create(text);
        } catch (IllegalArgumentException ex) {
            // 把非法 URI 转成当前业务自己的输入错误，不要继续读取路径。
            throw new IllegalArgumentException("URI 格式无效", ex);
        }
    }
}

两种入口表达的是同一类语法失败，但异常模型不同：new URI(text) 抛出 URISyntaxException，URI.create(text) 在解析失败时抛出 IllegalArgumentException。不要先调用 getPath() 再期待它报告构造错误；对象都没有创建成功时，访问器没有机会执行。

按使用场景选择输出值

还要注意空值边界：路径组件可能未定义，访问器会返回 null；层级 URI 的路径通常存在，但不应把“空字符串”和“未定义”当成同一状态。跨层传递时最好保留一个明确的数据结构，同时记录采用的是 raw 还是 decoded 语义。

常见问题

getRawPath 和 getPath 哪个更适合拼接日志？

如果日志要还原收到的 URI 文本，使用 getRawPath()；如果日志是给业务人员阅读并需要看到中文路径，可以记录 getPath()，但应明确字段含义。

getPath 得到中文后还能再调用 URLEncoder 编码吗？

不要把路径编码和查询参数编码混为一谈。若确实需要生成新的 URI，应按 URI 构造器和对应组件规则编码，避免把已有的百分号转义重复编码成 %25。

URI.create 失败后还能读取 raw path 吗？

不能。创建失败不会产生可用的 URI 对象，应在异常分支记录输入、返回业务错误或交给上层处理。