Apache Commons Lang3 Pair 完整版实战详解

一、概述Pair是 Apache Commons Lang3 提供的二元元组工具类是 SpringBoot 项目中最常用的双值临时封装工具。核心作用一个方法需要返回两个不同结果不想新建 DTO/VO 时临时封装两个数据。区别于 JDK 无原生 Pair后端开发几乎统一使用org.apache.commons.lang3.tuple.Pair。二、项目依赖SpringBootSpringBoot 项目一般已自动引入若无则手动添加dependencygroupIdorg.apache.commons/groupIdartifactIdcommons-lang3/artifactId/dependency三、Pair 核心结构3.1 核心包与类关系核心抽象类org.apache.commons.lang3.tuple.Pair实现类ImmutablePair不可变默认推荐、线程安全MutablePair可变可修改左右值3.2 核心方法Pair.of(left, right)创建 Pair默认返回不可变对象getLeft()获取第一个元素getRight()获取第二个元素getKey()兼容 Map.Entry等价 getLeftgetValue()兼容 Map.Entry等价 getRight四、基础用法演示4.1 不可变 Pair项目 99% 场景使用一旦创建无法修改左右值线程安全规范推荐。importorg.apache.commons.lang3.tuple.Pair;publicclassPairDemo{publicstaticvoidmain(String[]args){// 创建二元组PairString,IntegeruserPair.of(张三,20);// 取值Stringnameuser.getLeft();Integerageuser.getRight();System.out.println(name);// 张三System.out.println(age);// 20}}4.2 可变 Pair特殊场景使用支持动态修改左右值非线程安全仅局部临时使用。importorg.apache.commons.lang3.tuple.MutablePair;publicclassMutablePairDemo{publicstaticvoidmain(String[]args){MutablePairString,IntegerpairMutablePair.of(初始,10);// 修改值pair.setLeft(修改后);pair.setRight(20);System.out.println(pair.getLeft());// 修改后System.out.println(pair.getRight());// 20}}五、企业级实战场景高频场景1方法返回「状态 提示信息」业务层校验、登录、参数校验经典用法。/** * 用户名校验 * return left: 是否成功 right: 提示信息 */publicPairBoolean,StringcheckUsername(Stringusername){if(usernamenull||username.isBlank()){returnPair.of(false,用户名不能为空);}if(username.length()2){returnPair.of(false,用户名长度不能小于2位);}returnPair.of(true,校验通过);}场景2分页返回「列表 总条数」无需新建分页临时 VO内部逻辑极简封装。publicPairListUser,LonggetUserPageList(){ListUseruserListuserMapper.selectList(null);LongtotaluserMapper.selectCount(null);returnPair.of(userList,total);}场景3集合批量封装二元数据ListPairString,IntegergoodsListnewArrayList();goodsList.add(Pair.of(苹果,10));goodsList.add(Pair.of(香蕉,20));// 遍历for(PairString,Integerpair:goodsList){System.out.println(商品pair.getLeft()数量pair.getRight());}六、核心对比Pair vs Map vs DTO/VO6.1 Pair vs Map重点对比项PairMap存储结构固定 2 个值left/rightKey-Value 动态多值集合类型安全泛型固定无需强转Value 为 Object需强转不安全可读性一般仅适合内部临时使用差依赖 key 字符串易写错性能轻量、无哈希结构开销重量级适合大量数据存储适用场景方法返回两个固定结果动态多键值、配置、字典数据6.2 Pair vs 自定义 DTO/VO开发核心规范对比项PairDTO/VO字段数量固定 2 个无法扩展支持任意字段可无限扩展语义性差left/right 无业务含义极强自定义字段名见名知意注解支持不支持校验、文档注解支持 Data、ApiModelProperty、校验注解复用性一次性临时使用全局复用统一业务规范对外暴露禁止在 Controller 返回接口返回、跨模块传递首选七、公司项目最佳实践硬性规范✅ 允许使用 Pair 的场景私有方法、内部工具方法临时返回两个值一次性逻辑无需复用、无需扩展快速计算、临时数据封装用完即弃❌ 禁止使用 Pair 的场景Controller 接口返回给前端公共方法、跨模块调用传参/返回值未来可能新增字段的业务数据需要文档、校验、序列化的正式数据 终极选型口诀内部临时双值、偷懒快速写 → Pair对外暴露、长期维护、可扩展 → DTO/VO多键值动态数据、配置存储 → Map八、常见坑点避坑指南默认 Pair 不可变Pair.of()返回 ImmutablePair无法 set 赋值需要修改必须用 MutablePair语义模糊团队协作禁止用 Pair 传递核心业务数据可读性极差不可扩展后续加字段必须重构代码不如直接初始建 DTO禁止接口返回前端无法解析 left/right无文档、无字段说明九、拓展Triple 三元组需要临时返回三个值可使用同包下的Tripleleft/middle/right规则和 Pair 完全一致同样只适合内部临时使用。