Java URI.create 怎样解析相对 URI 并处理非法输入

我在把配置里的路径交给 Java 代码时，最容易先入为主地把“没有 http://”理解成解析失败。其实 java.net.URI 同时支持绝对 URI 和相对 URI，URI.create(String) 只负责按 URI 语法解析字符串，不要求一定存在 scheme。

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

如果字符串是程序内已经确定合法的常量，可以用 URI.create 快速得到不可变的 URI；如果字符串来自用户、配置文件或外部接口，应使用 new URI(String) 显式处理 URISyntaxException。相对 URI 是否成立，关键看它有没有 scheme，而不是看它像不像网址。

URI.create 解析后能读取哪些结构

URI 的字符串结构可以看成可选的 scheme、authority、path、query 和 fragment。官方文档把带 scheme 的 URI 称为 absolute URI，没有 scheme 的称为 relative URI。因此 docs/index.html 是合法的相对 URI，https://docs.example.com/index.html 是绝对 URI。

import java.net.URI;

public class UriPartsDemo {
    public static void main(String[] args) {
        // 相对 URI 不需要 scheme，适合表示文档内部路径或资源片段。
        URI relative = URI.create("docs/index.html?lang=zh#intro");

        // 绝对 URI 带有 scheme，可以通过 isAbsolute() 直接判断。
        URI absolute = URI.create("https://docs.example.com/guide/index.html");

        // 组件读取只做语法层面的拆分，不会访问域名或发起网络请求。
        System.out.println(relative.getPath());
        System.out.println(relative.getQuery());
        System.out.println(relative.getFragment());
        System.out.println(absolute.getScheme());
        System.out.println(absolute.isAbsolute());
    }
}

这个例子里，相对 URI 的 getScheme() 返回 null，isAbsolute() 返回 false；绝对 URI 的 scheme 是 https，isAbsolute() 返回 true。不要用 startsWith("/") 代替这个判断，因为 docs/index.html 和 /docs/index.html 都是相对 URI，只是路径形式不同。

相对 URI 合法，不等于可以直接访问

URI 是一个结构化的 URI 引用。它可以做规范化、解析、相对化和组件读取，但本身不会查 DNS，也不会创建网络连接。换句话说，URI.create("docs/index.html") 成功，只能说明这个字符串符合 Java URI 的语法约束。

如果业务需要把相对 URI 变成完整地址，应把它和明确的 base URI 交给 resolve；这个动作仍是字符串和组件层面的计算，不是网络请求。

import java.net.URI;

public class UriResolveDemo {
    public static void main(String[] args) {
        // base URI 以斜杠结尾，表示相对路径要挂到该目录下。
        URI base = URI.create("https://example.com/docs/");
        URI relative = URI.create("guide/start.html");

        // resolve 只返回新的 URI，不会访问 example.com。
        URI resolved = base.resolve(relative);
        System.out.println(resolved);
    }
}

这里要把“解析”与“访问”分开：URI 的职责是语法和组件，URL 或 HTTP 客户端才涉及资源访问。即使 scheme 写成一个当前没有网络处理器的名字，URI 也仍然可以作为语法对象存在。

URI.create 遇到非法输入会抛什么异常

URI.create 是便捷工厂方法。Java SE API 说明它的行为相当于调用单参数 URI 构造器，并把构造器抛出的 URISyntaxException 包装成 IllegalArgumentException。这就是它适合“我已经知道字符串合法”的原因，也是它不适合直接吞下外部脏数据的原因。

import java.net.URI;

public class UriCreateErrorDemo {
    public static void main(String[] args) {
        String value = "https://example.com/a path";

        try {
            // 空格不是这里可直接接受的 URI 字符；create 会包装解析异常。
            URI uri = URI.create(value);
            System.out.println(uri);
        } catch (IllegalArgumentException ex) {
            // 对外部输入至少记录失败原因，避免把非法值继续传给下游。
            System.out.println("URI 格式非法：" + ex.getMessage());
        }
    }
}

这里捕获的是 IllegalArgumentException，不是 URISyntaxException。如果你需要把“输入不合法”作为可检查分支交给调用方，就不要用这个快捷入口。

外部输入优先使用 URI 构造器

来自 HTTP 参数、配置文件、数据库或消息队列的字符串，通常不能假设已经符合 URI 语法。单参数构造器会直接声明 URISyntaxException，调用方可以决定返回提示、使用备用值，还是记录一条可定位的业务错误。

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

public class UriParseBoundary {
    static URI parseExternal(String value) {
        try {
            // 构造器保留 URISyntaxException，适合把输入错误交给上层处理。
            return new URI(value);
        } catch (URISyntaxException ex) {
            // 不把原始非法字符串继续向下游传播，返回明确的业务异常。
            throw new IllegalArgumentException("URI 参数不合法", ex);
        }
    }

    public static void main(String[] args) {
        // 调用方可以统一处理 parseExternal 抛出的业务异常。
        System.out.println(parseExternal("docs/index.html").isAbsolute());
    }
}

这不是说构造器会把输入“修好”。它只提供更细的异常边界，编码时仍应根据业务决定是否先做白名单、编码或长度限制。不要把 URL 编码、路径清理和 URI 语法解析混成一个动作。

几个容易混淆的边界

• 绝对 URI 与绝对路径不同：https://example.com/a 有 scheme，是绝对 URI；/a 只是绝对路径，仍然没有 scheme。
• URI 与 URL 不同：URI 对主机只做语法解析，不保证主机存在，也不会自动联网。
• 解析成功与业务可用不同：合法 URI 仍可能不符合你的协议、租户、域名或路径白名单。
• 空字符串也要单独考虑：它可以表示一个空的相对 URI 引用，是否允许应由业务规则决定。

怎么选 URI.create 与 new URI

常见问题

URI.create 能解析相对路径吗？

能。只要字符串符合 URI 语法，没有 scheme 的字符串也可以成为相对 URI；用 isAbsolute() 可以区分两者。

为什么 URI.create 捕获不到 URISyntaxException？

因为便捷工厂方法把构造器异常包装成了 IllegalArgumentException。需要检查型异常边界时改用 new URI(String)。

URI.create 会访问域名吗？

不会。它只解析字符串，不做 DNS 查询或网络连接。

含空格的路径能直接传给 URI.create 吗？

不能把空格当作普通 URI 字符直接依赖解析器“自动修复”。先按业务规则处理编码，再交给 URI API，并把非法输入当作可处理的错误分支。

把 URI.create 当成“已知合法字符串的快捷入口”，把 new URI 当成“需要把输入错误交给上层处理的解析入口”，这个区分基本能覆盖大多数 Java URI 场景。至于相对 URI 是否能被业务接受，还要继续检查协议、白名单和最终访问策略。