URL构建器-UrlBuilder
UrlBuilder是Hutool中用于构建URL的工具类，实现了Builder接口，用于生成符合URI规范的URL字符串。它支持协议、主机、端口、路径、查询参数和片段标识符的灵活设置。
# 主要功能
- 从URL字符串、URL对象或URI对象创建UrlBuilder
- 灵活设置URL的各个组成部分（协议、主机、端口、路径、查询参数、片段）
- 支持路径的追加和路径段的添加
- 支持查询参数的添加
- 支持URL编码和解码
- 可以转换为URL对象或URI对象
# URL格式
URL构建器支持的格式形如：
[scheme:]scheme-specific-part[#fragment]
[scheme:][//authority][path][?query][#fragment]
[scheme:][//host:port][path][?query][#fragment]
其中：
| 组成部分 | 说明 | 示例 |
|---|---|---|
| scheme | 协议 | http、https |
| scheme-specific-part | 协议特定部分，包含主机、端口、路径、查询参数和片段 | - |
| authority | 主机和端口 | 127.0.0.1:8080 |
| host | 主机 | 127.0.0.1、www.example.com |
| port | 端口，默认-1表示使用协议默认端口 | 8080 |
| path | 路径 | /hello/world |
| query | 查询参数 | key1=value1&key2=value2 |
| fragment | 标识符 | #section1 |
# 主要方法
# 创建UrlBuilder
# of()
创建空的UrlBuilder实例。
# ofHttp(String httpUrl)
从HTTP URL字符串创建UrlBuilder，默认使用UTF-8编码。
# ofHttp(String httpUrl, Charset charset)
从HTTP URL字符串创建UrlBuilder，可指定编码。
# of(String url)
从URL字符串创建UrlBuilder，默认使用UTF-8编码。
# of(String url, Charset charset)
从URL字符串创建UrlBuilder，可指定编码。
# of(URL url, Charset charset)
从URL对象创建UrlBuilder。
# of(URI uri, Charset charset)
从URI对象创建UrlBuilder。
# 设置URL组成部分
# setScheme(String scheme)
设置协议，例如http、https。
# setHost(String host)
设置主机，例如127.0.0.1、www.example.com。
# setPort(int port)
设置端口，默认-1表示使用协议默认端口。
# setPath(UrlPath path)
设置路径，将覆盖之前所有的path相关设置。
# addPath(CharSequence path)
在现有路径基础上追加路径。
# addPathSegment(CharSequence segment)
增加路径节点，路径节点中的"/"会被转义为"%2F"。
# setWithEndTag(boolean withEngTag)
设置是否在path末尾加"/"。
# setQuery(UrlQuery query)
设置查询语句，将覆盖之前所有的query相关设置。
# addQuery(String key, Object value)
添加查询项，支持重复键，默认非严格模式。
# setFragment(String fragment)
设置标识符，例如#后边的部分。
# setCharset(Charset charset)
设置编码，用于URLEncode和URLDecode。
# 构建URL
# build()
创建URL字符串。
# toURL()
转换为URL对象。
# toURL(URLStreamHandler handler)
转换为URL对象，可指定URLStreamHandler。
# toURI()
转换为URI对象。
# 获取URL组成部分
# getScheme()
获取协议。
# getSchemeWithDefault()
获取协议，如果未定义则返回默认的http协议。
# getHost()
获取主机。
# getPort()
获取端口，默认-1。
# getPortWithDefault()
获取端口，如果未自定义则返回协议默认端口。
# getAuthority()
获取authority部分，格式为host:port。
# getPath()
获取路径，返回UrlPath对象。
# getPathStr()
获取路径字符串。
# getQuery()
获取查询语句，返回UrlQuery对象。
# getQueryStr()
获取查询字符串。
# getFragment()
获取标识符。
# getFragmentEncoded()
获取编码后的标识符。
# getCharset()
获取编码。
# 示例代码
# 基本URL构建
// 创建空的UrlBuilder并设置各个部分
String url = UrlBuilder.of()
.setScheme("https")
.setHost("www.example.com")
.setPort(443)
.addPath("api")
.addPathSegment("users")
.addQuery("id", 123)
.addQuery("name", "test")
.setFragment("section1")
.build();
// 输出：https://www.example.com:443/api/users?id=123&name=test#section1
# 从现有URL创建
// 从URL字符串创建
UrlBuilder builder = UrlBuilder.ofHttp("https://www.example.com/api/users?id=123");
// 添加新的查询参数
builder.addQuery("age", 25);
// 构建新的URL
String newUrl = builder.build();
// 输出：https://www.example.com/api/users?id=123&age=25
# 路径操作
// 创建UrlBuilder
UrlBuilder builder = UrlBuilder.of()
.setScheme("http")
.setHost("localhost")
.setPort(8080);
// 添加路径
builder.addPath("api/v1");
// 添加路径段
builder.addPathSegment("users");
builder.addPathSegment("profile");
// 设置路径末尾加/
builder.setWithEndTag(true);
String url = builder.build();
// 输出：http://localhost:8080/api/v1/users/profile/
# 查询参数操作
// 创建UrlBuilder
UrlBuilder builder = UrlBuilder.of()
.setScheme("http")
.setHost("localhost")
.setPath("/search");
// 添加多个查询参数
builder.addQuery("keyword", "hutool");
builder.addQuery("category", "tool");
builder.addQuery("page", 1);
builder.addQuery("size", 10);
String url = builder.build();
// 输出：http://localhost/search?keyword=hutool&category=tool&page=1&size=10
# 转换为URL和URI对象
// 创建UrlBuilder
UrlBuilder builder = UrlBuilder.ofHttp("https://www.example.com");
// 转换为URL对象
URL url = builder.toURL();
// 转换为URI对象
URI uri = builder.toURI();