Hutool 库中使用 Pair类返回键值对

一、Pair 是什么？

Pair<K, V>是 Hutool库 提供的一个通用键值对（Key-Value）对象，它的作用就是把两个相关的数据临时封装到一个对象中，避免为了返回两个值而专门创建一个 Java Bean。

它位于：

cn.hutool.core.lang.Pair

它内部实际上非常简单，只包含两个字段：key和value。创建后就是一个不可变（Immutable）的键值对（不能修改 key/value，只能读取）。(Hutool Plus)

二、最简单的例子

例如：

Pair<String,Integer>pair=Pair.of("Tom",18);System.out.println(pair.getKey());System.out.println(pair.getValue());

输出

Tom 18

也可以直接 new：

Pair<String,Integer>pair=newPair<>("Tom",18);

不过官方更推荐：

Pair.of(key,value)

因为类型推导更方便。(Hutool Plus)

三、它有什么作用？

很多时候，一个方法想返回两个值。

例如：

假设我们有一个方法，需要返回：

• 用户ID
• 用户姓名

如果没有 Pair，你只能：

方案一：创建对象

classUserInfo{privateLongid;privateStringname;}

然后：

returnnewUserInfo(id,name);

如果这个对象以后再也不用，就会觉得比较麻烦。

于是 Pair 就可以这样：

publicPair<Long,String>getUser(){returnPair.of(1001L,"张三");}

调用：

Pair<Long,String>user=getUser();Longid=user.getKey();Stringname=user.getValue();

四、为什么叫 Pair（一对）

因为它就是：

(key,value)

例如：

("Tom",18) ("Apple",8.5) ("北京",2150) ("手机号","181****8888")

就是一对数据。

五、和 Map 有什么区别？

很多初学者都会疑惑：

Map 也是 Key -> Value，为什么还要 Pair？

区别非常大。

Pair

只表示：

一个 Key 一个 Value

例如：

("Tom",18)

只有这一组。

Map

Map 保存的是：

很多 Pair

例如：

Tom -> 18 Jack -> 20 Lucy -> 22

实际上可以理解成：

Map │ ├── Pair("Tom",18) ├── Pair("Jack",20) ├── Pair("Lucy",22)

所以：

Pair 表示一条数据，而 Map 表示很多条 Pair。

六、实际开发中的使用场景

场景1：返回两个值

例如：

查询数据库：

需要返回：

• 成功数量
• 失败数量

publicPair<Integer,Integer>count(){returnPair.of(120,5);}

调用：

Pair<Integer,Integer>result=count();System.out.println(result.getKey());//120System.out.println(result.getValue());//5

场景2：遍历时临时保存两个对象

例如：

订单

订单号 订单金额

可以写：

Pair<String,BigDecimal>order=Pair.of("NO10001",newBigDecimal("99.8"));

场景3：方法之间传递两个关联数据

例如：

登录成功后：

需要返回：

token user

可以：

Pair<String,User>login(){returnPair.of(token,user);}

场景4：排序

例如：

统计词频：

apple -> 10 banana -> 6 cat -> 9

可以转成：

List<Pair<String,Integer>>

然后根据 value 排序。

七、Pair 不是 Map.Entry

很多人第一次看会误认为：

Pair == Map.Entry

其实不是。

例如：

Map<String,Integer>map=newHashMap<>();

遍历：

for(Map.Entry<String,Integer>entry:map.entrySet()){}

这里得到的是：

Map.Entry

不是：

Pair

虽然：

Map.Entry Pair

都表示：

key value

但是它们属于两个不同的类。

八、Hutool Pair 提供的方法

常用方法非常少：

Pair.of(key,value)

创建对象。

getKey()

获取 Key。

getValue()

获取 Value。

equals()

判断两个 Pair 是否相同。

例如：

Pair.of("A",1)

和

Pair.of("A",1)

相等。

hashCode()

用于 HashMap、HashSet 等集合。

toString()

打印字符串。

九、与 MutablePair 的区别

Hutool 还有一个：

MutablePair

顾名思义：

Mutable = 可修改

例如：

MutablePair<String,Integer>pair=newMutablePair<>("Tom",18);pair.setKey("Jack");pair.setValue(20);

而普通Pair创建以后：

Pair<String,Integer>pair=Pair.of("Tom",18);

只能：

pair.getKey();pair.getValue();

不能修改内部的值，因此更安全。(Hutool Plus)

十、在实际项目中是否推荐使用？

推荐使用Pair的场景：

• ✔ 方法临时返回两个值
• ✔ Stream 流处理中临时组合两个对象
• ✔ 排序、中间计算过程中的数据封装
• ✔ 工具类内部使用

不推荐使用的场景：

• ❌ Controller 返回值（接口响应应该使用明确的 DTO）
• ❌ Service 对外接口长期暴露（返回UserInfoDTO等语义明确的对象更好）
• ❌ 数据库实体（Entity）
• ❌ 业务对象（VO、DTO、BO）

例如：

// ✔ 合适Pair<BigDecimal,BigDecimal>calculateTax();// ❌ 不推荐Pair<String,Object>queryUser();

第二种代码可读性很差，别人很难知道：

key

到底代表什么？

是：

• 用户ID？
• 用户名？
• 手机号？

还是：

• Token？

如果改成：

UserInfoDTO

就一目了然。

总结一句话：

Pair<K, V>本质上就是一个轻量级的二元组（Tuple），用于临时封装两个有关联的对象。它非常适合工具类、算法和中间计算过程，但不适合作为复杂业务对象的长期替代品。