Class UrlBuilder

java.lang.Object
cloud.opencode.base.web.url.UrlBuilder
public final class UrlBuilder extends Object
URL Builder - Fluent URL Constructor URL 构建器 - 流畅的 URL 构造器

This class provides a fluent builder for constructing URLs with scheme, host, port, path, and query parameters.

此类提供流畅的构建器用于构建包含协议、主机、端口、路径和查询参数的 URL。

Example | 示例:

// Build complete URL
String url = UrlBuilder.create()
    .scheme("https")
    .host("api.example.com")
    .port(8080)
    .path("/users/{id}")
    .pathParam("id", "123")
    .queryParam("page", "1")
    .queryParam("size", "20")
    .build(); // "https://api.example.com:8080/users/123?page=1&size=20"

// From existing URL
String newUrl = UrlBuilder.from("https://example.com/api")
    .path("/users")
    .queryParam("active", "true")
    .build();

Features | 主要功能:

  • Fluent URL construction - 流式URL构建
  • Path parameter substitution - 路径参数替换
  • Query parameter building - 查询参数构建
  • Path traversal protection - 路径遍历保护

Usage Examples | 使用示例:

String url = UrlBuilder.create()
    .scheme("https").host("api.example.com")
    .path("/users/{id}").pathParam("id", "123")
    .queryParam("page", "1").build();

Security | 安全性:

  • Thread-safe: No (mutable builder) - 否（可变构建器）
  • Null-safe: Partial (handles null paths) - 部分（处理null路径）

Performance | 性能特性:

  • Time complexity: O(n) where n = URL components - O(n), n为URL组件数
  • Space complexity: O(n) for URL string - URL字符串 O(n)
Since:
JDK 25, opencode-base-web V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • create

      public static UrlBuilder create()
      Creates a new URL builder. 创建新的 URL 构建器。
      Returns:
      the builder - 构建器

    • from

      public static UrlBuilder from(String url)
      Creates a URL builder from existing URL. 从现有 URL 创建构建器。
      Parameters:
      url - the base URL - 基础 URL
      Returns:
      the builder - 构建器

    • from

      public static UrlBuilder from(URI uri)
      Creates a URL builder from URI. 从 URI 创建构建器。
      Parameters:
      uri - the URI - URI
      Returns:
      the builder - 构建器

    • scheme

      public UrlBuilder scheme(String scheme)
      Sets the scheme. Only http and https are accepted (case-insensitive); other schemes — notably javascript: and data: — are rejected to defend against open-redirect / XSS payload construction when the scheme value reaches this builder from external input. Use http() / https() for the common case. 设置协议。仅接受 http 与 https（不区分大小写）；其他协议（特别是 javascript: 与 data:）一律拒绝，避免 scheme 来自外部输入时被构造为 开放重定向 / XSS payload。常用情形请使用 http() / https()。
      Parameters:
      scheme - the scheme (http or https) - 协议
      Returns:
      this builder - 此构建器
      Throws:
      IllegalArgumentException - if scheme is null, blank, or not one of {http, https} | scheme 为 null/空或不在 {http, https} 中时抛出

    • http

      public UrlBuilder http()
      Uses HTTP scheme. 使用 HTTP 协议。
      Returns:
      this builder - 此构建器

    • https

      public UrlBuilder https()
      Uses HTTPS scheme. 使用 HTTPS 协议。
      Returns:
      this builder - 此构建器

    • host

      public UrlBuilder host(String host)
      Sets the host. 设置主机。
      Parameters:
      host - the host - 主机
      Returns:
      this builder - 此构建器

    • port

      public UrlBuilder port(int port)
      Sets the port. 设置端口。
      Parameters:
      port - the port (-1 for default) - 端口
      Returns:
      this builder - 此构建器

    • path

      public UrlBuilder path(String path)
      Sets the path. 设置路径。
      Parameters:
      path - the path - 路径
      Returns:
      this builder - 此构建器

    • appendPath

      public UrlBuilder appendPath(String segment)
      Appends to the path. 追加路径。
      Parameters:
      segment - the path segment - 路径段
      Returns:
      this builder - 此构建器

    • pathParam

      public UrlBuilder pathParam(String name, String value)
      Sets a path parameter. 设置路径参数。
      Parameters:
      name - the parameter name - 参数名
      value - the parameter value - 参数值
      Returns:
      this builder - 此构建器

    • pathParams

      public UrlBuilder pathParams(Map<String,String> params)
      Sets path parameters. 设置路径参数。
      Parameters:
      params - the parameters - 参数
      Returns:
      this builder - 此构建器

    • queryParam

      public UrlBuilder queryParam(String name, String value)
      Adds a query parameter. 添加查询参数。
      Parameters:
      name - the parameter name - 参数名
      value - the parameter value - 参数值
      Returns:
      this builder - 此构建器

    • queryParamIfNotNull

      public UrlBuilder queryParamIfNotNull(String name, String value)
      Adds a query parameter if value is not null. 如果值不为 null，添加查询参数。
      Parameters:
      name - the parameter name - 参数名
      value - the parameter value - 参数值
      Returns:
      this builder - 此构建器

    • queryParamIfNotEmpty

      public UrlBuilder queryParamIfNotEmpty(String name, String value)
      Adds a query parameter if value is not empty. 如果值不为空，添加查询参数。
      Parameters:
      name - the parameter name - 参数名
      value - the parameter value - 参数值
      Returns:
      this builder - 此构建器

    • queryParams

      public UrlBuilder queryParams(Map<String,String> params)
      Adds query parameters. 添加查询参数。
      Parameters:
      params - the parameters - 参数
      Returns:
      this builder - 此构建器

    • queryString

      public UrlBuilder queryString(QueryString queryString)
      Sets query string. 设置查询字符串。
      Parameters:
      queryString - the query string - 查询字符串
      Returns:
      this builder - 此构建器

    • fragment

      public UrlBuilder fragment(String fragment)
      Sets the fragment. 设置片段。
      Parameters:
      fragment - the fragment - 片段
      Returns:
      this builder - 此构建器

    • build

      public String build()
      Builds the URL string. 构建 URL 字符串。
      Returns:
      the URL string - URL 字符串

    • buildUri

      public URI buildUri()
      Builds as URI. 构建为 URI。
      Returns:
      the URI - URI

    • toString

      public String toString()
      Overrides:
      toString in class Object