java.lang.Object

org.miaixz.bus.http.UnoUrl

public class UnoUrl extends Object

HTTP 或 HTTPS 的统一资源定位器（URL）

提供对 URL 的构建、解析和编码处理，支持 HTTP 和 HTTPS 协议。避免使用检查型异常，解析无效 URL 时返回 null 或抛出 IllegalArgumentException。实例是不可变的，支持组件的编码和解码操作。

Since:: Java 17+
Author:: Kimi Liu

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static class

UnoUrl.Builder

URL 构建器
Field Summary

Fields

Modifier and Type

Field

Description

static final String

FORM_ENCODE_SET

表单编码字符集

static final String

FRAGMENT_ENCODE_SET

片段编码字符集

static final String

FRAGMENT_ENCODE_SET_URI

URI 片段编码字符集

static final String

PASSWORD_ENCODE_SET

密码编码字符集

static final String

PATH_SEGMENT_ENCODE_SET

路径段编码字符集

static final String

PATH_SEGMENT_ENCODE_SET_URI

URI 路径段编码字符集

static final String

QUERY_COMPONENT_ENCODE_SET

查询组件编码字符集

static final String

QUERY_COMPONENT_ENCODE_SET_URI

URI 查询组件编码字符集

static final String

QUERY_COMPONENT_REENCODE_SET

查询组件重新编码字符集

static final String

QUERY_ENCODE_SET

查询参数编码字符集

static final String

USERNAME_ENCODE_SET

用户名编码字符集
Method Summary

Modifier and Type

Method

Description

static String

canonicalize(String input, int pos, int limit, String encodeSet, boolean alreadyEncoded, boolean strict, boolean plusIsSpace, boolean asciiOnly, Charset charset)

规范化字符串

static String

canonicalize(String input, String encodeSet, boolean alreadyEncoded, boolean strict, boolean plusIsSpace, boolean asciiOnly)

规范化字符串（默认 UTF-8）

static String

canonicalize(String input, String encodeSet, boolean alreadyEncoded, boolean strict, boolean plusIsSpace, boolean asciiOnly, Charset charset)

规范化字符串（默认 UTF-8）

static void

canonicalize(org.miaixz.bus.core.io.buffer.Buffer out, String input, int pos, int limit, String encodeSet, boolean alreadyEncoded, boolean strict, boolean plusIsSpace, boolean asciiOnly, Charset charset)

规范化字符串到缓冲区

static int

defaultPort(String scheme)

获取默认端口号

String

encodedFragment()

获取编码后的片段 http://host/null http://host/#"" http://host/#abc"abc" http://host/#abc|def"abc|def"

String

encodedPassword()

获取编码后的密码 http://host/"" http://username@host/"" http://username:password@host/"password" http://a%20b:c%20d@host/"c%20d"

String

encodedPath()

获取编码后的路径 http://host// http://host/a/b/c"/a/b/c" http://host/a/b%20c/d"/a/b%20c/d"

List<String>

encodedPathSegments()

获取编码后的路径段列表 http://host/[""] http://host/a/b/c["a", "b", "c"] http://host/a/b%20c/d["a", "b%20c", "d"]

String

encodedQuery()

获取编码后的查询字符串 http://host/null http://host/?"" http://host/?a=apple&k=key+lime"a=apple&k=key+lime" http://host/?a=apple&a=apricot"a=apple&a=apricot" http://host/?a=apple&b"a=apple&b"

String

encodedUsername()

获取编码后的用户名

boolean

equals(Object other)

比较两个 UnoUrl 对象是否相等

String

fragment()

获取解码后的片段 http://host/null http://host/#"" http://host/#abc"abc" http://host/#abc|def"abc|def"

static UnoUrl

get(String url)

构建 UnoUrl 实例

static UnoUrl

get(URI uri)

从 URI 对象构建 UnoUrl 实例

static UnoUrl

get(URL url)

从 URL 对象构建 UnoUrl 实例

int

hashCode()

计算 URL 的哈希码

String

host()

获取主机名 A regular host name, like android.com.

boolean

isHttps()

检查是否为 HTTPS 协议

UnoUrl.Builder

newBuilder()

创建新的 Builder 实例

UnoUrl.Builder

newBuilder(String link)

创建相对链接的 Builder 实例

static UnoUrl

parse(String url)

解析 URL 字符串为 UnoUrl 实例

String

password()

获取解码后的密码 http://host/"" http://username@host/"" http://username:password@host/"password" http://a%20b:c%20d@host/"c d"

List<String>

pathSegments()

获取解码后的路径段列表 http://host/[""] http://host/a/b/c"["a", "b", "c"] http://host/a/b%20c/d"["a", "b c", "d"]

int

pathSize()

获取路径段数量 http://host/1 http://host/a/b/c3 http://host/a/b/c/4

static String

percentDecode(String encoded, boolean plusIsSpace)

解码百分比编码字符串

static String

percentDecode(String encoded, int pos, int limit, boolean plusIsSpace)

解码百分比编码字符串（指定范围）

static void

percentDecode(org.miaixz.bus.core.io.buffer.Buffer out, String encoded, int pos, int limit, boolean plusIsSpace)

解码百分比编码字符串到缓冲区

static boolean

percentEncoded(String encoded, int pos, int limit)

检查字符串是否为百分比编码

int

port()

获取端口号 http://host/80 http://host:8000/8000 https://host/443

String

query()

获取解码后的查询字符串 http://host/null http://host/?"" http://host/?a=apple&k=key+lime"a=apple&k=key lime" http://host/?a=apple&a=apricot"a=apple&a=apricot" http://host/?a=apple&b"a=apple&b"

String

queryParameter(String name)

获取指定名称的第一个查询参数值 http://host/null http://host/?null http://host/?a=apple&k=key+lime"apple" http://host/?a=apple&a=apricot"apple" http://host/?a=apple&b"apple"

String

queryParameterName(int index)

获取指定索引的查询参数名称 http://host/exceptionexception http://host/?""exception http://host/?a=apple&k=key+lime"a""k" http://host/?a=apple&a=apricot"a""a" http://host/?a=apple&b"a""b"

Set<String>

queryParameterNames()

获取查询参数名称集合 http://host/[] http://host/?[""] http://host/?a=apple&k=key+lime["a", "k"] http://host/?a=apple&a=apricot["a"] http://host/?a=apple&b["a", "b"]

String

queryParameterValue(int index)

获取指定索引的查询参数值 http://host/exceptionexception http://host/?nullexception http://host/?a=apple&k=key+lime"apple""key lime" http://host/?a=apple&a=apricot"apple""apricot" http://host/?a=apple&b"apple"null

List<String>

queryParameterValues(String name)

获取指定名称的所有查询参数值 http://host/[][] http://host/?[][] http://host/?a=apple&k=key+lime["apple"][] http://host/?a=apple&a=apricot["apple", "apricot"][] http://host/?a=apple&b["apple"][null]

int

querySize()

获取查询参数数量 http://host/0 http://host/?1 http://host/?a=apple&k=key+lime2 http://host/?a=apple&a=apricot2 http://host/?a=apple&b2

String

redact()

返回隐藏敏感信息的 URL

UnoUrl

resolve(String link)

解析相对链接

String

scheme()

获取协议

String

toString()

返回 URL 的字符串表示

URI

uri()

转换为 java.net.URI 对象

URL

url()

转换为 java.net.URL 对象

String

username()

获取解码后的用户名 http://host/"" http://username@host/"username" http://username:password@host/"username" http://a%20b:c%20d@host/"a b"

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details
- USERNAME_ENCODE_SET
  
  public static final String USERNAME_ENCODE_SET
  
  用户名编码字符集
  See Also:
  
  Constant Field Values
- PASSWORD_ENCODE_SET
  
  public static final String PASSWORD_ENCODE_SET
  
  密码编码字符集
  See Also:
  
  Constant Field Values
- PATH_SEGMENT_ENCODE_SET
  
  public static final String PATH_SEGMENT_ENCODE_SET
  
  路径段编码字符集
  See Also:
  
  Constant Field Values
- PATH_SEGMENT_ENCODE_SET_URI
  
  public static final String PATH_SEGMENT_ENCODE_SET_URI
  
  URI 路径段编码字符集
  See Also:
  
  Constant Field Values
- QUERY_ENCODE_SET
  
  public static final String QUERY_ENCODE_SET
  
  查询参数编码字符集
  See Also:
  
  Constant Field Values
- QUERY_COMPONENT_REENCODE_SET
  
  public static final String QUERY_COMPONENT_REENCODE_SET
  
  查询组件重新编码字符集
  See Also:
  
  Constant Field Values
- QUERY_COMPONENT_ENCODE_SET
  
  public static final String QUERY_COMPONENT_ENCODE_SET
  
  查询组件编码字符集
  See Also:
  
  Constant Field Values
- QUERY_COMPONENT_ENCODE_SET_URI
  
  public static final String QUERY_COMPONENT_ENCODE_SET_URI
  
  URI 查询组件编码字符集
  See Also:
  
  Constant Field Values
- FORM_ENCODE_SET
  
  public static final String FORM_ENCODE_SET
  
  表单编码字符集
  See Also:
  
  Constant Field Values
- FRAGMENT_ENCODE_SET
  
  public static final String FRAGMENT_ENCODE_SET
  
  片段编码字符集
  See Also:
  
  Constant Field Values
- FRAGMENT_ENCODE_SET_URI
  
  public static final String FRAGMENT_ENCODE_SET_URI
  
  URI 片段编码字符集
  See Also:
  
  Constant Field Values
Method Details
- defaultPort
  
  public static int defaultPort(String scheme)
  
  获取默认端口号
  返回 80（http）、443（https）或 -1（其他协议）。
  
  Parameters:
  
  scheme - 协议名称
  
  Returns:
  
  默认端口号
- parse
  
  public static UnoUrl parse(String url)
  
  解析 URL 字符串为 UnoUrl 实例
  如果 URL 格式有效，返回 UnoUrl 实例；否则返回 null。
  
  Parameters:
  
  url - URL 字符串
  
  Returns:
  
  UnoUrl 实例或 null
- get
  
  public static UnoUrl get(String url)
  
  构建 UnoUrl 实例
  如果 URL 格式无效，抛出 IllegalArgumentException。
  
  Parameters:
  
  url - URL 字符串
  
  Returns:
  
  UnoUrl 实例
  
  Throws:
  
  IllegalArgumentException - 如果 URL 格式无效
- get
  
  public static UnoUrl get(URL url)
  
  从 URL 对象构建 UnoUrl 实例
  仅支持 http 和 https 协议，非有效协议返回 null。
  
  Parameters:
  
  url - URL 对象
  
  Returns:
  
  UnoUrl 实例或 null
- get
  
  public static UnoUrl get(URI uri)
  
  从 URI 对象构建 UnoUrl 实例
  
  Parameters:
  
  uri - URI 对象
  
  Returns:
  
  UnoUrl 实例或 null
- percentDecode
  
  public static String percentDecode(String encoded, boolean plusIsSpace)
  
  解码百分比编码字符串
  
  Parameters:
  
  encoded - 编码字符串
  
  plusIsSpace - 是否将加号解码为空格
  
  Returns:
  
  解码后的字符串
- percentDecode
  
  public static String percentDecode(String encoded, int pos, int limit, boolean plusIsSpace)
  
  解码百分比编码字符串（指定范围）
  
  Parameters:
  
  encoded - 编码字符串
  
  pos - 起始位置
  
  limit - 结束位置
  
  plusIsSpace - 是否将加号解码为空格
  
  Returns:
  
  解码后的字符串
- percentDecode
  
  public static void percentDecode(org.miaixz.bus.core.io.buffer.Buffer out, String encoded, int pos, int limit, boolean plusIsSpace)
  
  解码百分比编码字符串到缓冲区
  
  Parameters:
  
  out - 输出缓冲区
  
  encoded - 编码字符串
  
  pos - 起始位置
  
  limit - 结束位置
  
  plusIsSpace - 是否将加号解码为空格
- percentEncoded
  
  public static boolean percentEncoded(String encoded, int pos, int limit)
  
  检查字符串是否为百分比编码
  
  Parameters:
  
  encoded - 编码字符串
  
  pos - 起始位置
  
  limit - 结束位置
  
  Returns:
  
  true 如果是有效的百分比编码
- canonicalize
  
  public static String canonicalize(String input, int pos, int limit, String encodeSet, boolean alreadyEncoded, boolean strict, boolean plusIsSpace, boolean asciiOnly, Charset charset)
  
  规范化字符串
  跳过控制字符，编码指定字符集中的字符，处理百分比编码和加号。
  
  Parameters:
  
  input - 输入字符串
  
  pos - 起始位置
  
  limit - 结束位置
  
  encodeSet - 编码字符集
  
  alreadyEncoded - 是否已编码
  
  strict - 是否严格编码
  
  plusIsSpace - 是否将加号编码为空格
  
  asciiOnly - 是否仅限 ASCII
  
  charset - 字符集（null 为 UTF-8）
  
  Returns:
  
  规范化字符串
- canonicalize
  
  public static void canonicalize(org.miaixz.bus.core.io.buffer.Buffer out, String input, int pos, int limit, String encodeSet, boolean alreadyEncoded, boolean strict, boolean plusIsSpace, boolean asciiOnly, Charset charset)
  
  规范化字符串到缓冲区
  
  Parameters:
  
  out - 输出缓冲区
  
  input - 输入字符串
  
  pos - 起始位置
  
  limit - 结束位置
  
  encodeSet - 编码字符集
  
  alreadyEncoded - 是否已编码
  
  strict - 是否严格编码
  
  plusIsSpace - 是否将加号编码为空格
  
  asciiOnly - 是否仅限 ASCII
  
  charset - 字符集（null 为 UTF-8）
- canonicalize
  
  public static String canonicalize(String input, String encodeSet, boolean alreadyEncoded, boolean strict, boolean plusIsSpace, boolean asciiOnly, Charset charset)
  
  规范化字符串（默认 UTF-8）
  
  Parameters:
  
  input - 输入字符串
  
  encodeSet - 编码字符集
  
  alreadyEncoded - 是否已编码
  
  strict - 是否严格编码
  
  plusIsSpace - 是否将加号编码为空格
  
  asciiOnly - 是否仅限 ASCII
  
  charset - 字符集（null 为 UTF-8）
  
  Returns:
  
  规范化字符串
- canonicalize
  
  public static String canonicalize(String input, String encodeSet, boolean alreadyEncoded, boolean strict, boolean plusIsSpace, boolean asciiOnly)
  
  规范化字符串（默认 UTF-8）
  
  Parameters:
  
  input - 输入字符串
  
  encodeSet - 编码字符集
  
  alreadyEncoded - 是否已编码
  
  strict - 是否严格编码
  
  plusIsSpace - 是否将加号编码为空格
  
  asciiOnly - 是否仅限 ASCII
  
  Returns:
  
  规范化字符串
- url
  
  public URL url()
  
  转换为 java.net.URL 对象
  
  Returns:
  
  URL 对象
  
  Throws:
  
  RuntimeException - 如果 URL 格式无效
- uri
  
  public URI uri()
  
  转换为 java.net.URI 对象
  注意：URI 比 UnoUrl 更严格，可能对某些字符进行转义或移除（如片段中的空白）。建议避免直接使用 URI，以免服务器解释差异。
  
  Returns:
  
  URI 对象
  
  Throws:
  
  RuntimeException - 如果 URI 格式无效
- scheme
  
  public String scheme()
  
  获取协议
  
  Returns:
  
  协议（http 或 https）
- isHttps
  
  public boolean isHttps()
  
  检查是否为 HTTPS 协议
  
  Returns:
  
  true 如果协议为 HTTPS
- encodedUsername
  
  public String encodedUsername()
  
  获取编码后的用户名
  
  Returns:
  
  编码后的用户名（空字符串如果未设置）
- username
  
  public String username()
  获取解码后的用户名
  
  http://host/""
  
  http://username@host/"username"
  
  http://username:password@host/"username"
  
  http://a%20b:c%20d@host/"a b"
  Returns:
  
  用户信息
- encodedPassword
  
  public String encodedPassword()
  获取编码后的密码
  
  http://host/""
  
  http://username@host/""
  
  http://username:password@host/"password"
  
  http://a%20b:c%20d@host/"c%20d"
  Returns:
  
  返回密码
- password
  
  public String password()
  获取解码后的密码
  
  http://host/""
  
  http://username@host/""
  
  http://username:password@host/"password"
  
  http://a%20b:c%20d@host/"c d"
  Returns:
  
  返回已解码的密码
- host
  
  public String host()
  获取主机名
  
  A regular host name, like android.com.
  An IPv4 address, like 127.0.0.1.
  An IPv6 address, like ::1.
  An encoded IDN, like xn--n3h.net.
  
  http://android.com/"android.com"
  
  http://127.0.0.1/"127.0.0.1"
  
  http://[::1]/"::1"
  
  http://xn--n3h.net/"xn--n3h.net"
  Returns:
  
  主机host
- port
  
  public int port()
  获取端口号
  
  http://host/80
  
  http://host:8000/8000
  
  https://host/443
  Returns:
  
  端口
- pathSize
  
  public int pathSize()
  获取路径段数量
  
  http://host/1
  
  http://host/a/b/c3
  
  http://host/a/b/c/4
  Returns:
  
  the size
- encodedPath
  
  public String encodedPath()
  获取编码后的路径
  
  http://host//
  
  http://host/a/b/c"/a/b/c"
  
  http://host/a/b%20c/d"/a/b%20c/d"
  Returns:
  
  URL的完整路径
- encodedPathSegments
  
  public List<String> encodedPathSegments()
  获取编码后的路径段列表
  
  http://host/[""]
  
  http://host/a/b/c["a", "b", "c"]
  
  http://host/a/b%20c/d["a", "b%20c", "d"]
  Returns:
  
  路径段列表
- pathSegments
  
  public List<String> pathSegments()
  获取解码后的路径段列表
  
  http://host/[""]
  
  http://host/a/b/c"["a", "b", "c"]
  
  http://host/a/b%20c/d"["a", "b c", "d"]
  Returns:
  
  the string
- encodedQuery
  
  public String encodedQuery()
  获取编码后的查询字符串
  
  http://host/null
  
  http://host/?""
  
  http://host/?a=apple&k=key+lime"a=apple&k=key+lime"
  
  http://host/?a=apple&a=apricot"a=apple&a=apricot"
  
  http://host/?a=apple&b"a=apple&b"
  Returns:
  
  the string
- query
  
  public String query()
  获取解码后的查询字符串
  
  http://host/null
  
  http://host/?""
  
  http://host/?a=apple&k=key+lime"a=apple&k=key lime"
  
  http://host/?a=apple&a=apricot"a=apple&a=apricot"
  
  http://host/?a=apple&b"a=apple&b"
  Returns:
  
  the string
- querySize
  
  public int querySize()
  获取查询参数数量
  
  http://host/0
  
  http://host/?1
  
  http://host/?a=apple&k=key+lime2
  
  http://host/?a=apple&a=apricot2
  
  http://host/?a=apple&b2
  Returns:
  
  the int
- queryParameter
  
  public String queryParameter(String name)
  获取指定名称的第一个查询参数值
  
  http://host/null
  
  http://host/?null
  
  http://host/?a=apple&k=key+lime"apple"
  
  http://host/?a=apple&a=apricot"apple"
  
  http://host/?a=apple&b"apple"
  Parameters:
  
  name - 名称
  
  Returns:
  
  the string
- queryParameterNames
  
  public Set<String> queryParameterNames()
  获取查询参数名称集合
  
  http://host/[]
  
  http://host/?[""]
  
  http://host/?a=apple&k=key+lime["a", "k"]
  
  http://host/?a=apple&a=apricot["a"]
  
  http://host/?a=apple&b["a", "b"]
  Returns:
  
  the set
- queryParameterValues
  
  public List<String> queryParameterValues(String name)
  获取指定名称的所有查询参数值
  
  http://host/[][]
  
  http://host/?[][]
  
  http://host/?a=apple&k=key+lime["apple"][]
  
  http://host/?a=apple&a=apricot["apple", "apricot"][]
  
  http://host/?a=apple&b["apple"][null]
  Parameters:
  
  name - 名称
  
  Returns:
  
  the list
- queryParameterName
  
  public String queryParameterName(int index)
  获取指定索引的查询参数名称
  
  http://host/exceptionexception
  
  http://host/?""exception
  
  http://host/?a=apple&k=key+lime"a""k"
  
  http://host/?a=apple&a=apricot"a""a"
  
  http://host/?a=apple&b"a""b"
  Parameters:
  
  index - 索引
  
  Returns:
  
  参数名称
  
  Throws:
  
  IndexOutOfBoundsException - 如果索引无效
- queryParameterValue
  
  public String queryParameterValue(int index)
  获取指定索引的查询参数值
  
  http://host/exceptionexception
  
  http://host/?nullexception
  
  http://host/?a=apple&k=key+lime"apple""key lime"
  
  http://host/?a=apple&a=apricot"apple""apricot"
  
  http://host/?a=apple&b"apple"null
  Parameters:
  
  index - 索引
  
  Returns:
  
  参数值
  
  Throws:
  
  IndexOutOfBoundsException - 如果索引无效
- encodedFragment
  
  public String encodedFragment()
  获取编码后的片段
  
  http://host/null
  
  http://host/#""
  
  http://host/#abc"abc"
  
  http://host/#abc|def"abc|def"
  Returns:
  
  编码后的片段（可能为 null）
- fragment
  
  public String fragment()
  获取解码后的片段
  
  http://host/null
  
  http://host/#""
  
  http://host/#abc"abc"
  
  http://host/#abc|def"abc|def"
  Returns:
  
  解码后的片段（可能为 null）
- redact
  
  public String redact()
  
  返回隐藏敏感信息的 URL
  
  Returns:
  
  隐藏用户名和密码的 URL 字符串
- resolve
  
  public UnoUrl resolve(String link)
  
  解析相对链接
  
  Parameters:
  
  link - 相对链接
  
  Returns:
  
  解析后的 UnoUrl 实例（无效时为 null）
- newBuilder
  
  public UnoUrl.Builder newBuilder()
  
  创建新的 Builder 实例
  
  Returns:
  
  Builder 实例
- newBuilder
  
  public UnoUrl.Builder newBuilder(String link)
  
  创建相对链接的 Builder 实例
  
  Parameters:
  
  link - 相对链接
  
  Returns:
  
  Builder 实例（无效时为 null）
- equals
  
  public boolean equals(Object other)
  
  比较两个 UnoUrl 对象是否相等
  
  Overrides:
  
  equals in class Object
  
  Parameters:
  
  other - 另一个对象
  
  Returns:
  
  true 如果两个 URL 相等
- hashCode
  
  public int hashCode()
  
  计算 URL 的哈希码
  
  Overrides:
  
  hashCode in class Object
  
  Returns:
  
  哈希码值
- toString
  
  public String toString()
  
  返回 URL 的字符串表示
  
  Overrides:
  
  toString in class Object
  
  Returns:
  
  URL 字符串

Class UnoUrl

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

USERNAME_ENCODE_SET

PASSWORD_ENCODE_SET

PATH_SEGMENT_ENCODE_SET

PATH_SEGMENT_ENCODE_SET_URI

QUERY_ENCODE_SET

QUERY_COMPONENT_REENCODE_SET

QUERY_COMPONENT_ENCODE_SET

QUERY_COMPONENT_ENCODE_SET_URI

FORM_ENCODE_SET

FRAGMENT_ENCODE_SET

FRAGMENT_ENCODE_SET_URI

Method Details

defaultPort

parse

get

get

get

percentDecode

percentDecode

percentDecode

percentEncoded

canonicalize

canonicalize

canonicalize

canonicalize

url

uri

scheme

isHttps

encodedUsername

username

encodedPassword

password

host

port

pathSize

encodedPath

encodedPathSegments

pathSegments

encodedQuery

query

querySize

queryParameter

queryParameterNames

queryParameterValues

queryParameterName

queryParameterValue

encodedFragment

fragment

redact

resolve

newBuilder

newBuilder

equals

hashCode

toString