Hutool
  • 指南
  • 核心(hutool-core)
  • 网络(net)
Hutool
2026-01-23
目录

URL工具-UrlUtil

UrlUtil是Hutool中用于处理URL（Uniform Resource Locator）统一资源定位符的工具类，提供了URL的创建、转换、标准化、解析等功能。

# URL组成

URL的基本组成结构：

协议://主机名[:端口]/ 路径/[:参数] [?查询]#Fragment
protocol :// hostname[:port] / path / [:parameters][?query]#fragment

# 主要功能

  • URL对象的创建和转换
  • URL的标准化处理
  • 相对路径的补全
  • URL组成部分的获取
  • Map转换为URL查询字符串
  • Data URI的构建
  • URL数据长度的获取
  • 表单数据与URL的拼接

# 常量说明

常量名 值 描述
CLASSPATH_URL_PREFIX "classpath:" 针对ClassPath路径的伪协议前缀（兼容Spring）
PROJECT_URL_PREFIX "project:" 针对project路径的伪协议前缀
FILE_URL_PREFIX "file:" URL前缀表示文件
JAR_URL_PREFIX "jar:" URL前缀表示jar
WAR_URL_PREFIX "war:" URL前缀表示war
JAR_URL_SEPARATOR "!/" Jar路径以及内部文件路径的分界符
WAR_URL_SEPARATOR "*/" WAR路径及内部文件路径分界符

# 主要方法

# URL对象创建与转换

# url(URI uri)

将URI转换为URL对象。

# url(String url)

通过字符串形式的URL地址创建URL对象。

# url(String url, URLStreamHandler handler)

通过字符串形式的URL地址创建URL对象，可指定URLStreamHandler。

# toUrlForHttp(String urlStr)

将URL字符串转换为URL对象，并做必要验证。

# toUrlForHttp(String urlStr, URLStreamHandler handler)

将URL字符串转换为URL对象，并做必要验证，可指定URLStreamHandler。

# getStringURI(CharSequence content)

获取string协议的URL，类似于string:///xxxxx。

# toURI(String location)

转字符串为URI。

# toURI(String location, boolean isEncode)

转字符串为URI，可指定是否编码参数中的特殊字符。

# toURI(URL url)

转URL为URI。

# toURI(URL url, boolean isEncode)

转URL为URI，可指定是否编码参数中的特殊字符。

# URL标准化

# normalize(String url)

标准化URL字符串。

  • 自动补齐“http://”头
  • 去除开头的\或者/
  • 替换\为/

# normalize(String url, boolean isEncodePath)

标准化URL字符串，可指定是否对URL中path部分的中文和特殊字符做转义。

# normalize(String url, boolean isEncodePath, boolean replaceSlash)

标准化URL字符串，可指定是否对URL中path部分的中文和特殊字符做转义，以及是否替换多个/为一个。

# 相对路径补全

# completeUrl(String baseUrl, String relativePath)

补全相对路径。

# URL组成部分获取

# getPath(String uriStr)

获得URL中的path部分。

# getDecodedPath(URL url)

从URL对象中获取不被编码的路径Path。

  • 对于本地路径，URL对象的getPath方法对于包含中文或空格时会被编码，导致路径读取错误
  • 此方法将URL转为URI后获取路径用于解决路径被编码的问题

# getHost(URL url)

获取URL中域名部分，只保留URL中的协议（Protocol）、Host，其它为null。

# Map转换为URL查询字符串

# buildQuery(Map<String, ?> paramMap, Charset charset)

将Map形式的表单数据转换为Url参数形式。

  • paramMap中如果key为空（null和""）会被忽略，如果value为null，会被做为空白符（""）
  • 会自动url编码键和值

# Data URI构建

# getDataUriBase64(String mimeType, String data)

Data URI Scheme封装，数据格式为Base64。

  • data URI scheme 允许我们使用内联（inline-code）的方式在网页中包含数据
  • 常用于将图片嵌入网页

# getDataUri(String mimeType, String encoding, String data)

Data URI Scheme封装，可指定编码方式。

# getDataUri(String mimeType, Charset charset, String encoding, String data)

Data URI Scheme封装，可指定MIME类型、字符集、编码方式和数据。

# URL数据长度获取

# size(URL url)

获取URL对应数据长度。

  • 如果URL为文件，转换为文件获取文件长度
  • 其它情况获取URLConnection的getContentLengthLong()

# 表单数据与URL拼接

# urlWithFormUrlEncoded(String url, Map<String, Object> form, Charset charset)

将表单数据加到URL中（用于GET表单提交），使用FormUrlEncoded模式。

  • 表单的键值对会被url编码，但是url中原参数不会被编码
  • 空格会编码为'+'

# urlWithForm(String url, Map<String, Object> form, Charset charset, boolean isEncodeParams)

将表单数据加到URL中（用于GET表单提交），可指定是否对键和值做转义处理。

# urlWithForm(String url, String queryString, Charset charset, boolean isEncodeParams)

将表单数据字符串加到URL中（用于GET表单提交）。

# URL流操作

# getStream(URL url)

从URL中获取流。

# getReader(URL url, Charset charset)

获得URL对应的BufferedReader。

# 资源URL获取

# getURL(String pathBaseClassLoader)

获得URL，常用于使用相对路径时的情况。

# getURL(String path, Class<?> clazz)

获得URL，相对于给定class所在的路径。

# getURL(File file)

获得URL，常用于使用绝对路径时的情况。

# getURL(URL url, String relativePath)

获取相对于给定URL的新的URL。

# getURLs(File... files)

获得URL数组，常用于使用绝对路径时的情况。

# 示例代码

# URL对象创建

// 通过字符串创建URL
URL url = UrlUtil.url("https://www.example.com");

// 通过URI创建URL
URI uri = URI.create("https://www.example.com");
URL urlFromUri = UrlUtil.url(uri);

# URL标准化

String url = "www.example.com/path\\to\\resource?param=value";
String normalizedUrl = UrlUtil.normalize(url);
// 输出：http://www.example.com/path/to/resource?param=value

// 带编码的标准化
String urlWithChinese = "www.example.com/测试路径?param=测试值";
String normalizedUrlWithEncode = UrlUtil.normalize(urlWithChinese, true);
// 输出：http://www.example.com/%E6%B5%8B%E8%AF%95%E8%B7%AF%E5%BE%84?param=测试值

# 补全相对路径

String baseUrl = "https://www.example.com/path1/path2/";
String relativePath = "../newpath/resource.txt";
String completeUrl = UrlUtil.completeUrl(baseUrl, relativePath);
// 输出：https://www.example.com/path1/newpath/resource.txt

# 获取URL组成部分

URL url = UrlUtil.url("https://www.example.com:8080/path/to/resource?param1=value1&param2=value2#fragment");

// 获取协议
String protocol = url.getProtocol(); // https

// 获取主机和端口
String host = url.getHost(); // www.example.com
int port = url.getPort(); // 8080

// 获取路径
String path = UrlUtil.getPath(url.toString()); // /path/to/resource

// 获取解码后的路径
String decodedPath = UrlUtil.getDecodedPath(url); // /path/to/resource

// 获取主机URI
URI hostUri = UrlUtil.getHost(url); // https://www.example.com

# Map转换为URL查询字符串

Map<String, Object> paramMap = new HashMap<>();
paramMap.put("key1", "value1");
paramMap.put("key2", "value2");
paramMap.put("key3", null);

String queryString = UrlUtil.buildQuery(paramMap, CharsetUtil.UTF_8);
// 输出：key1=value1&key2=value2&key3=

# 构建Data URI

// 构建Base64编码的Data URI
String base64Data = "SGVsbG8sIFdvcmxkIQ==";
String dataUri = UrlUtil.getDataUriBase64("text/plain", base64Data);
// 输出：data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==

// 构建普通编码的Data URI
String plainData = "Hello, World!";
String plainDataUri = UrlUtil.getDataUri("text/plain", "charset=utf-8", "", plainData);
// 输出：data:text/plain;charset=utf-8,,Hello, World!

# 获取URL数据长度

// 文件URL
URL fileUrl = UrlUtil.url("file:///C:/example.txt");
long fileSize = UrlUtil.size(fileUrl); // 文件的实际大小

// 网络URL
URL webUrl = UrlUtil.url("https://www.example.com");
long webSize = UrlUtil.size(webUrl); // 网页内容的长度

# 表单数据与URL拼接

String baseUrl = "https://www.example.com/search";
Map<String, Object> formData = new HashMap<>();
formData.put("keyword", "hutool");
formData.put("page", 1);
formData.put("size", 10);

// 使用FormUrlEncoded模式拼接
String urlWithForm = UrlUtil.urlWithFormUrlEncoded(baseUrl, formData, CharsetUtil.UTF_8);
// 输出：https://www.example.com/search?keyword=hutool&page=1&size=10

// 自定义编码模式拼接
String urlWithFormCustom = UrlUtil.urlWithForm(baseUrl, formData, CharsetUtil.UTF_8, true);
// 输出：https://www.example.com/search?keyword=hutool&page=1&size=10

# 从URL获取流

URL url = UrlUtil.url("https://www.example.com");

// 获取输入流
try (InputStream is = UrlUtil.getStream(url)) {
    // 处理流
}

// 获取Reader
try (BufferedReader reader = UrlUtil.getReader(url, CharsetUtil.UTF_8)) {
    String line;
    while ((line = reader.readLine()) != null) {
        // 处理行数据
    }
}
URL查询工具-UrlQueryUtil
对象池

← 对象池→

Theme by Vdoing | Copyright © 2025-2026 Hutool | Apache-2.0