Hutool NumUtil 教程

NumUtil 是 Hutool 工具包中的数字工具类，提供了丰富的数字处理、校验、转换等方法。

Maven 依赖

XML 复制代码

<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.8.25</version>
</dependency>

常用方法详解

1. 类型判断

java 复制代码

import cn.hutool.core.util.NumberUtil;

// 判断是否为整数（包括Integer、Long、Byte、Short）
NumberUtil.isInteger(3.5);   // false
NumberUtil.isInteger(3);     // true

// 判断是否为浮点数
NumberUtil.isDouble(3.5);    // true
NumberUtil.isDouble(3);      // false

// 判断是否为数字（正则匹配）
NumberUtil.isNumber("123");    // true
NumberUtil.isNumber("12.3");   // true
NumberUtil.isNumber("12a");    // false

// 判断是否为空（null或NaN）
NumberUtil.isNull(null);       // true
NumberUtil.isNull(Double.NaN); // true

2. 四则运算

java 复制代码

// 加法（精确计算）
NumberUtil.add(0.1, 0.2);          // 0.3（避免 0.30000000000000004）
NumberUtil.add("0.1", "0.2");      // 0.3

// 减法
NumberUtil.sub(0.3, 0.1);          // 0.2

// 乘法
NumberUtil.mul(0.1, 0.2);          // 0.02

// 除法（需要指定精度）
NumberUtil.div(10, 3, 2);          // 3.33（保留2位小数）
NumberUtil.div(10, 3, 2, RoundingMode.HALF_UP); // 3.33

// 求余
NumberUtil.mod(10, 3);             // 1

3. 数字格式化

java 复制代码

// 保留小数位数
NumberUtil.round(3.14159, 2);      // 3.14
NumberUtil.roundStr(3.14159, 2);   // "3.14"

// 百分比
NumberUtil.toPercent(0.25);        // "25%"
NumberUtil.toPercent(0.256, 1);    // "25.6%"（保留1位小数）

// 千分位格式化
NumberUtil.decimalFormat("###,###", 1234567);     // "1,234,567"
NumberUtil.decimalFormat("#.##", 123.456);        // "123.46"

// 科学计数法转普通数字
NumberUtil.toStr(1.23E10);         // "12300000000"

4. 比较运算

java 复制代码

// 比较大小（支持多种类型）
NumberUtil.compare(5, 3);          // 1 (5 > 3)
NumberUtil.compare(3, 5);          // -1 (3 < 5)
NumberUtil.compare(5, 5);          // 0 (相等)

// 是否在区间内
NumberUtil.isIn(5, 1, 10);         // true（包含边界）
NumberUtil.isIn(0, 1, 10);         // false

// 范围内检查
NumberUtil.range(5, 1, 10);        // 5（正常返回）
NumberUtil.range(0, 1, 10);        // 1（超出下限返回下限）
NumberUtil.range(20, 1, 10);       // 10（超出上限返回上限）

// 等于（忽略精度）
NumberUtil.equals(0.1 + 0.2, 0.3); // true
NumberUtil.equals(3.14, 3.14);     // true

5. 进制转换

java 复制代码

// 十进制转其他进制
NumberUtil.toBinaryString(10);     // "1010"
NumberUtil.toOctalString(10);      // "12"
NumberUtil.toHexString(10);        // "a"

// 其他进制转十进制
NumberUtil.binaryToInt("1010");    // 10
NumberUtil.octalToInt("12");       // 10
NumberUtil.hexToInt("a");          // 10

6. 随机数生成

java 复制代码

// 生成随机整数 [min, max]
NumberUtil.generateRandomNumber(1, 100, 5);  // 生成5个不重复的随机数

// 生成随机整数列表
NumberUtil.generateBySet(1, 100, 10);        // Set<Integer>

// 简单随机数（Hutool 5.x 后建议使用 RandomUtil）
NumberUtil.randomInt(1, 100);      // 随机整数
NumberUtil.randomDouble(1, 100);   // 随机浮点数

7. 数字校验与解析

java 复制代码

// 验证是否为有效数字
NumberUtil.isValidNumber(123);      // true
NumberUtil.isValidNumber(Double.NaN); // false

// 解析数字（安全，不抛异常）
NumberUtil.parseNumber("123");      // 123
NumberUtil.parseNumber("abc");      // null

// 解析整数
NumberUtil.parseInt("123");         // 123
NumberUtil.parseInt("abc", 0);      // 0（默认值）

// 解析浮点数
NumberUtil.parseDouble("3.14");     // 3.14
NumberUtil.parseDouble("abc", 0.0); // 0.0

8. 其他实用方法

java 复制代码

// 计算阶乘
NumberUtil.factorial(5);            // 120

// 最大公约数
NumberUtil.gcd(12, 18);             // 6

// 最小公倍数
NumberUtil.lcm(4, 6);               // 12

// 判断奇偶数
NumberUtil.isOdd(5);                // true（奇数）
NumberUtil.isEven(4);               // true（偶数）

// 获取数字的位数
NumberUtil.digitLength(12345);      // 5
NumberUtil.digitLength(3.14);       // 2（整数部分位数）

// 保留N位有效数字
NumberUtil.roundStr(12.345, 3);     // "12.3"

完整示例

java 复制代码

import cn.hutool.core.util.NumberUtil;
import java.math.RoundingMode;

public class NumUtilDemo {
    public static void main(String[] args) {
        // 1. 精确计算
        double result = NumberUtil.add(0.1, 0.2);
        System.out.println("0.1 + 0.2 = " + result);  // 0.3
        
        // 2. 格式化
        String price = NumberUtil.roundStr(19.99 * 0.8, 2);
        System.out.println("折扣价：" + price);  // 15.99
        
        // 3. 百分比
        double passRate = 85.5 / 100;
        System.out.println("通过率：" + NumberUtil.toPercent(passRate, 1));  // 85.5%
        
        // 4. 区间限制
        int score = NumberUtil.range(105, 0, 100);
        System.out.println("限制后的分数：" + score);  // 100
        
        // 5. 数字校验
        boolean isValid = NumberUtil.isNumber("3.14159");
        System.out.println("是否为数字：" + isValid);  // true
    }
}

注意事项

浮点数计算 ：使用 add()、sub()、mul()、div() 避免精度丢失
除法精度：除法时必须指定小数位数，否则可能抛出异常
空值处理：大多数方法对 null 输入返回 null 或默认值，不会抛出 NPE
版本差异 ：部分方法在 Hutool 5.x 后移到 RandomUtil，建议查阅官方文档