Java URI.resolve 怎样避免相对路径误换主机

我第一次遇到 URI.resolve “换主机”，是在把一个服务返回的资源路径拼到 API 基地址上时。代码没有抛异常，结果也像一个合法 URL，但传入的引用只要以 / 或 // 开头，解析规则就可能让路径回到根目录，甚至直接采用新的 authority。解决办法不是手工补斜杠，而是把引用分成几类，并在继续发送请求前检查解析结果。

Java 的 URI.resolve 按 URI 引用规则合并组件，不是把两个字符串简单相加。普通相对路径通常沿用 base 的主机和目录；以单个斜杠开头的引用从根路径开始；以双斜杠开头的网络路径引用会替换 authority，因此可能得到另一个主机。

触发场景：先把 base 和引用的职责分开

base URI 提供默认的 scheme、authority 和目录上下文，引用 URI 只覆盖它明确写出的部分。下面这组示例刻意使用同一个 base，便于只观察引用形式的差异：

import java.net.URI;

public class UriResolveDemo {
    public static void main(String[] args) {
        URI base = URI.create("https://api.example.com/v1/users/list");

        // 普通相对引用沿用主机，并相对 base 的最后一段所在目录解析。
        print(base, "detail");
        // 根相对引用从主机的根路径开始，不再沿用 /v1/users/ 目录。
        print(base, "/health");
        // 网络路径引用显式提供新的 authority，主机可能因此改变。
        print(base, "//cdn.example.net/avatar.png");
    }

    private static void print(URI base, String reference) {
        // resolve 会按 URI 语义合并组件，不能替换成字符串拼接。
        URI resolved = base.resolve(reference);
        System.out.printf("%-28s -> %s%n", reference, resolved);
    }
}

结果分别会落在 https://api.example.com/v1/users/detail、https://api.example.com/health 和 https://cdn.example.net/avatar.png。第三种引用没有“继承原主机”，因为它的 // 已经携带了新的 authority。这里的图示只帮助理解组件关系，不是终端运行截图。

解析阶段：三种引用形式要分别判断

生产代码里最容易混淆的是“看起来都是字符串路径”。可以先按下面的边界判断：

• 普通相对路径：如 detail 或 ../avatar.png，一般沿用 base 的 scheme 和 authority，并对路径做相对合并。
• 根相对路径：如 /health，仍然使用 base 的 scheme 和 authority，但路径从根目录开始。
• 网络路径引用：如 //cdn.example.net/a.js，引用带有 authority，解析后可能换主机；它不适合被无条件当作“站内资源路径”。
• 绝对 URI：如 https://other.example/a，解析结果直接使用引用自身的绝对组件。

如果业务字段本来只允许站内相对路径，就应该在调用 resolve 前拒绝含有 scheme 或 authority 的引用，而不是解析后再猜测它是否安全。

门禁规则：解析后检查哪些字段

遇到外部输入时，我会把解析和检查放在同一个小函数里。重点不是“能不能解析”，而是结果是否还在业务允许的主机和路径范围内：

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

public final class SafeUriResolver {
    private SafeUriResolver() {}

    public static URI resolveSameHost(URI base, String reference)
            throws URISyntaxException {
        // 先解析字符串，让非法 URI 以明确异常暴露出来。
        URI candidate = base.resolve(new URI(reference));

        // 只允许解析结果保持绝对 URI，并且不改变预期主机。
        if (!candidate.isAbsolute()
                || !base.getScheme().equalsIgnoreCase(candidate.getScheme())
                || !base.getHost().equalsIgnoreCase(candidate.getHost())) {
            throw new URISyntaxException(reference, "解析结果改变了 scheme 或 host");
        }

        // normalize 只整理路径中的 . 和 ..，不能替代主机白名单检查。
        URI normalized = candidate.normalize();
        if (!normalized.getPath().startsWith("/v1/")) {
            throw new URISyntaxException(reference, "解析结果越过了允许的路径前缀");
        }
        return normalized;
    }
}

这个封装有三个故意保留的检查点：isAbsolute() 确认结果仍有 scheme；getHost() 防止网络路径引用换主机；normalize() 后再检查路径前缀，避免把路径整理和权限判断混为一谈。若 base 使用 IP、端口或非服务器 authority，还应按业务需要比较 getAuthority()，不能只依赖 getHost()。

失败处理：写成可复用的判断流程

实际接入时，可以按“输入限制—解析—字段检查—归一化—返回”的顺序组织代码：

1. 先确定字段约定：只接受站内相对路径，还是允许跨主机资源。
2. 用 new URI(reference) 捕获非法语法，不用字符串拼接掩盖问题。
3. 调用 base.resolve(referenceUri)，同时保留原始引用便于日志定位。
4. 比较 scheme、host、必要时比较 port 或 authority。
5. 对允许的路径调用 normalize()，再按业务前缀或资源目录判断。

常见误区是把 normalize() 当成安全过滤器，或者只检查结果字符串是否以某个前缀开头。前者解决不了 authority 变化，后者可能漏掉大小写、端口和编码差异。URI 负责语义解析，业务代码仍然要明确允许的 scheme、主机和路径集合。

通知复盘：什么时候会保留主机

对我来说，最稳的习惯是：把 resolve 当作 URI 规范的实现，把“允许访问哪里”留在业务层显式表达。只要先看清引用是否携带 authority，再检查解析后的 scheme、host 和 path，就不会把“解析成功”误当成“结果符合预期”。

相关问题

为什么 resolve("/x") 不会保留 base 的目录？ 因为单斜杠引用是根相对路径，它只继承 scheme 和 authority。

normalize() 能阻止换主机吗？ 不能。它处理的是层级 URI 的 path 段，主机检查必须单独完成。

只允许站内资源时检查什么？ 至少比较 scheme、host 和端口，并在 normalize 后检查业务允许的路径前缀。