URL生成器 - UrlBuilder

简介

UrlBuilder 是 Hutool 提供的一个用于构建、解析和处理 URL 的工具类。它支持更灵活和人性化的 URL 操作，解决了 JDK 自带的 URL 类在处理复杂 URL 时的局限性，尤其在编码处理、非标准 URL 解析等方面表现突出。该类将 URL 分解为多个部分，并提供链式方法来构建或修改这些部分，从而实现对 URL 的灵活操作。

1. 使用场景

• 动态构建 URL：在需要根据用户输入或配置动态生成 URL 时，可以使用 UrlBuilder 提供的链式 API 来高效构建 URL。
• URL 解析与处理：在解析和处理复杂的 URL 时，如处理包含中文、特殊字符或不标准格式的 URL，UrlBuilder 可以准确地解析并重新编码这些 URL。
• HTTP 请求构建：在进行 HTTP 请求时，可以使用 UrlBuilder 来构建规范化的请求 URL，避免编码错误或格式问题。

2. 主要方法与示例

2.1 create - 创建一个新的 UrlBuilder 实例

create 方法用于创建一个新的 UrlBuilder 实例，并支持设置协议、主机等 URL 基本信息。

示例：创建一个基本的 URL

import cn.hutool.core.net.url.UrlBuilder;

public class UrlBuilderExample {
    public static void main(String[] args) {
        // 创建并构建基本的 URL
        String buildUrl = UrlBuilder.create()
            .setScheme("https")  // 设置协议为 https
            .setHost("www.hutool.cn")  // 设置主机
            .build();  // 构建最终的 URL

        System.out.println(buildUrl); // 输出: https://www.hutool.cn/
    }
}

• 方法签名：
  • public static UrlBuilder create()
• 参数说明：无参数
• 作用：用于创建一个新的 UrlBuilder 实例，并可通过链式调用设置 URL 的各部分。

2.2 setScheme、setHost、setPort - 设置 URL 的基本信息

这些方法用于设置 URL 的协议（scheme）、主机（host）和端口（port），支持灵活的 URL 构建。

示例：完整构建一个 URL

import cn.hutool.core.net.url.UrlBuilder;

public class UrlBuilderExample {
    public static void main(String[] args) {
        // 构建一个包含路径和查询参数的 URL
        String buildUrl = UrlBuilder.create()
            .setScheme("https")
            .setHost("www.hutool.cn")
            .setPort(443)  // 设置端口
            .addPath("aaa")  // 添加路径
            .addPath("bbb")
            .addQuery("ie", "UTF-8")  // 添加查询参数
            .addQuery("wd", "test")
            .build();  // 构建最终的 URL

        System.out.println(buildUrl); // 输出: https://www.hutool.cn:443/aaa/bbb?ie=UTF-8&wd=test
    }
}

• 方法签名：
  • public UrlBuilder setScheme(String scheme)
  • public UrlBuilder setHost(String host)
  • public UrlBuilder setPort(int port)
• 参数说明：
  • scheme：设置 URL 的协议，如 http、https。
  • host：设置 URL 的主机部分。
  • port：设置 URL 的端口号。
• 作用：用于灵活设置 URL 的各个基本部分，适用于需要根据条件动态生成 URL 的场景。

2.3 addPath - 添加 URL 路径

该方法用于在 URL 中添加路径片段，支持多个路径的逐步添加。

示例：动态添加 URL 路径

import cn.hutool.core.net.url.UrlBuilder;

public class UrlBuilderExample {
    public static void main(String[] args) {
        // 动态添加路径片段
        String buildUrl = UrlBuilder.create()
            .setScheme("https")
            .setHost("www.hutool.cn")
            .addPath("docs")  // 添加路径片段
            .addPath("index.html")
            .build();

        System.out.println(buildUrl); // 输出: https://www.hutool.cn/docs/index.html
    }
}

• 方法签名：
  • public UrlBuilder addPath(String segment)
• 参数说明：
  • segment：需要添加的路径片段。
• 作用：在构建 URL 时逐步添加路径，适用于构建动态路径或拼接复杂 URL 的场景。

2.4 addQuery - 添加查询参数

该方法用于在 URL 中添加查询参数，支持多个参数的逐步添加。

示例：添加中文编码的查询参数

import cn.hutool.core.net.url.UrlBuilder;
import cn.hutool.core.util.CharsetUtil;

public class UrlBuilderExample {
    public static void main(String[] args) {
        // 添加中文查询参数，自动进行编码
        String buildUrl = UrlBuilder.create()
            .setScheme("https")
            .setHost("www.hutool.cn")
            .addPath("s")
            .addQuery("ie", "UTF-8")
            .addQuery("wd", "测试")  // 添加中文参数，自动编码为 %E6%B5%8B%E8%AF%95
            .build();

        System.out.println(buildUrl); // 输出: https://www.hutool.cn/s?ie=UTF-8&wd=%E6%B5%8B%E8%AF%95
    }
}

• 方法签名：
  • public UrlBuilder addQuery(String key, String value)
• 参数说明：
  • key：查询参数的键。
  • value：查询参数的值。
• 作用：用于添加 URL 查询参数，并支持自动编码，适用于处理带有中文或特殊字符的 URL。

2.5 ofHttp - 解析现有 URL

该方法用于解析已有的 URL 字符串，支持处理编码不一致或特殊字符的 URL。

示例：解析带有混合编码的 URL

import cn.hutool.core.net.url.UrlBuilder;
import cn.hutool.core.util.CharsetUtil;

public class UrlBuilderExample {
    public static void main(String[] args) {
        // 解析包含混合编码的 URL
        UrlBuilder builder = UrlBuilder.ofHttp("https://www.hutool.cn/aaa/bbb/?a=张三&b=%e6%9d%8e%e5%9b%9b#frag1", CharsetUtil.CHARSET_UTF_8);

        // 获取解析后的查询参数
        System.out.println("参数 a: " + builder.getQuery().get("a")); // 输出: 参数 a: 张三
        System.out.println("参数 b: " + builder.getQuery().get("b")); // 输出: 参数 b: 李四
    }
}

• 方法签名：
  • public static UrlBuilder ofHttp(String url, Charset charset)
• 参数说明：
  • url：需要解析的 URL 字符串。
  • charset：解析 URL 时使用的字符编码。
• 作用：用于解析复杂或包含混合编码的 URL，并自动进行解码处理，适用于处理用户输入或外部获取的 URL 数据。

3. 实际应用场景

• API 请求构建：在构建 API 请求 URL 时，可以使用 UrlBuilder 动态拼接路径和查询参数，保证 URL 的规范性和正确编码。
• 复杂 URL 解析与处理：在需要解析外部 URL，处理特殊编码或格式的场景中，UrlBuilder 提供了强大的解析能力。
• URL 生成与管理：在需要动态生成、修改或管理 URL 的场景中，使用 UrlBuilder 可以显著提高开发效率。

4. 注意事项

• UrlBuilder 支持自动编码和解码，但在处理特别复杂的 URL 时仍需注意字符集的一致性。
• URL 的构建与解析可能受到编码和规范化的影响，建议在使用过程中明确指定编码。