Java URL 构建器使用文档

1. 安装指南

使用 Maven 安装

将以下依赖项添加到您的 pom.xml 文件中：

<dependencies>
    <dependency>
        <groupId>io.mikael</groupId>
        <artifactId>urlbuilder</artifactId>
        <version>2.0.9</version>
    </dependency>
</dependencies>

使用 Gradle 安装

在您的 build.gradle 或 build.gradle.kts 文件中添加以下依赖项：

implementation "io.mikael:urlbuilder:2.0.9"

或者 Kotlin 版本：

implementation("io.mikael:urlbuilder:2.0.9")

2. 项目的使用说明

UrlBuilder 是一个用于轻松创建和修改 URL 及其参数的构建器类。构建器实例是不可变的、线程安全的并且可重用。每个更改都会创建一个新的实例。

以下是一些使用 UrlBuilder 的示例：

UrlBuilder.fromString("http://www.google.com/")
    .addParameter("q", "charlie brown")
    .toString(); // 返回 "http://www.google.com/?q=charlie+brown"

支持不同字符集的编码转换：

UrlBuilder.fromString("http://foo/h%F6pl%E4", "ISO-8859-1")
    .encodeAs("UTF-8")
    .toString(); // 返回 "http://foo/h%C3%B6pl%C3%A4"

您可以创建一个空的构建器并逐步构建 URL：

final UrlBuilder ub1 = UrlBuilder.empty()
    .withScheme("http")
    .withHost("www.example.com")
    .withPath("/")
    .addParameter("foo", "bar");

final java.net.URI uri1 = ub1.toUri();

处理可能的异常：

try {
    final java.net.URI uri2 = ub1.toUriWithException();
} catch (java.net.URISyntaxException ex) {
    // 处理异常
}

try {
    final java.net.URL url2 = ub1.toUrlWithException();
} catch (java.net.MalformedURLException ex) {
    // 处理异常
}

3. 项目API使用文档

• UrlBuilder.fromString(String url): 从一个现有的 URL 字符串创建一个新的 UrlBuilder 实例。
• UrlBuilder.fromString(String url, String charset): 从一个现有的 URL 字符串和字符集创建一个新的 UrlBuilder 实例。
• UrlBuilder.empty(): 创建一个空的 UrlBuilder 实例，可以通过链式方法调用添加参数和其他属性。
• UrlBuilder.withScheme(String scheme): 设置 URL 的协议（如 http 或 https）。
• UrlBuilder.withHost(String host): 设置 URL 的主机名。
• UrlBuilder.withPath(String path): 设置 URL 的路径。
• UrlBuilder.addParameter(String key, String value): 添加一个 URL 参数。
• UrlBuilder.encodeAs(String charset): 将 URL 编码为指定的字符集。
• UrlBuilder.toString(): 返回构建的 URL 的字符串表示。
• UrlBuilder.toUri(): 将 UrlBuilder 转换为 java.net.URI 对象。
• UrlBuilder.toUriWithException(): 与 toUri() 类似，但会抛出 URISyntaxException 异常。
• UrlBuilder.toUrl(): 将 UrlBuilder 转换为 java.net.URL 对象。
• UrlBuilder.toUrlWithException(): 与 toUrl() 类似，但会抛出 MalformedURLException 异常。

4. 项目安装方式

请参考上文中的“安装指南”部分，选择适合您项目的构建工具（Maven 或 Gradle）进行安装。