SpringBoot中通用工具类库(Utils)封装与使用实践

一、涉及的技术知识点

在实际的SpringBoot项目里，工具类库的封装几乎是每个团队都会遇到的命题。一套设计得当的工具类，能显著减少重复代码，让业务逻辑更清爽。下面我们就从几个核心维度来拆解常见的封装思路。

1.1 空值判断与防御性编程

1.2 日期时间处理

1.3 JSON 序列化/反序列化

1.4 加密工具

1.5 线程上下文管理

1.6 国际化（i18n）

1.7 网络工具

二、包结构

xxx.xxx.xxx.utils
├── CheckEmptyUtil.ja va          // 空值判断工具（使用频率最高）
├── DateUtil.ja va                // 日期工具（旧API，ja va.util.Date）
├── StringUtil.ja va              // 字符串/JSON工具（序列化+特殊字符处理）
├── JsonUtil.ja va                // JSON 序列化工具（支持 Snake Case）
├── Auth2SessionIdUtil.ja va      // OAuth2 会话上下文（ThreadLocal）
├── IpUtil.ja va                  // IP 地址工具
├── AesUtil.ja va                 // AES 加解密工具
├── Md5Utils.ja va                // MD5 摘要工具
├── xxxI18nUtil.ja va             // 国际化消息工具
├── FileUtil.ja va                // 文件操作工具
├── JasperUtil.ja va              // 报表导出工具（Jasper）
├── PdfUtil.ja va                 // PDF 生成工具
├── ClassNameUtil.ja va           // 类名处理工具
├── xxxSerializationUtils.ja va   // Ja va 序列化工具
├── PackageUtil.ja va             // 包扫描工具
├── UrlUtil.ja va                 // URL 处理工具
├── cloud/
│   ├── AdapterHeader.ja va       // 适配器 Header 工具
│   └── LoginToken.ja va          // 登录 Token 封装
└── time/
    ├── DateTimeUtil.ja va        // 日期时间工具（新API，ja va.time）
    ├── DateTimeFormat.ja va      // 日期格式枚举（20+种预定义格式）
    ├── DateTimeConverter.ja va   // 日期转换器
    └── ZoneEnums.ja va           // 时区枚举

无 spring.factories：纯工具类库，不涉及自动配置，直接引入静态方法调用。

三、通用示例代码

3.1 CheckEmptyUtil（空值判断工具）

package com.example.utils;

import ja va.lang.reflect.Array;
import ja va.util.Collection;
import ja va.util.Map;
import ja va.util.Optional;

/**
 * 通用空值判断工具.
 * 统一处理各种类型的空值判断，替代业务代码中的 != null && !isEmpty() 链式判断.
 * 
 * 支持类型：
 * - null
 * - String（空字符串）
 * - Collection（空集合）
 * - Map（空Map）
 * - Array（空数组）
 * - Optional（空Optional）
 * - 其他 Object（仅判null）
 */
public class CheckEmptyUtil {

    /**
     * 判断对象是否为空.
     * 根据实际类型自动选择判空策略.
     */
    public static boolean isEmpty(Object obj) {
        if (obj == null) {
            return true;
        }
        if (obj instanceof String) {
            return ((String) obj).trim().isEmpty();
        }
        if (obj instanceof Collection) {
            return ((Collection) obj).isEmpty();
        }
        if (obj instanceof Map) {
            return ((Map) obj).isEmpty();
        }
        if (obj.getClass().isArray()) {
            return Array.getLength(obj) == 0;
        }
        if (obj instanceof Optional) {
            return !((Optional) obj).isPresent();
        }
        return false;
    }

    /**
     * 判断对象是否非空.
     */
    public static boolean isNotEmpty(Object obj) {
        return !isEmpty(obj);
    }

    /**
     * 任一参数为空返回true.
     * 常用于参数校验：if (isOrEmpty(a, b)) throw ...
     */
    public static boolean isOrEmpty(Object... objs) {
        if (objs == null) {
            return true;
        }
        for (Object obj : objs) {
            if (isEmpty(obj)) {
                return true;
            }
        }
        return false;
    }

    /**
     * 全部参数都为空返回true.
     * 常用于条件判断：if (isAndEmpty(a, b)) 都没传
     */
    public static boolean isAndEmpty(Object... objs) {
        if (objs == null) {
            return true;
        }
        for (Object obj : objs) {
            if (isNotEmpty(obj)) {
                return false;
            }
        }
        return true;
    }
}

3.2 DateUtil（旧版日期工具）

package com.example.utils;

import ja va.text.SimpleDateFormat;
import ja va.util.Calendar;
import ja va.util.Date;
import ja va.util.regex.Pattern;

/**
 * 日期工具类（基于 ja va.util.Date）.
 * 
 * 核心特性：
 * 1. 智能日期解析 - 根据字符串格式自动识别
 * 2. 常用日期操作 - 月初/月末/日始/日终
 * 3. 日期格式化 - 标准格式输出
 */
public class DateUtil {

    private static final Pattern UNIX_TIMESTAMP = Pattern.compile("^\d{10}$");
    private static final Pattern JA VA_TIMESTAMP = Pattern.compile("^\d{13}$");
    private static final String STANDARD_DATETIME = "yyyy-MM-dd HH:mm:ss";
    private static final String STANDARD_DATE = "yyyy-MM-dd";

    /**
     * 智能日期解析.
     * 支持：时间戳(10位/13位)、标准格式、斜杠格式.
     * 
     * @param text 日期字符串
     * @return Date 对象，解析失败返回 null
     */
    public static Date convertToDate(String text) {
        if (text == null || text.trim().isEmpty()) {
            return null;
        }
        text = text.trim();
        try {
            switch (text.length()) {
                case 10:
                    // Unix 时间戳 或 yyyy-MM-dd
                    if (UNIX_TIMESTAMP.matcher(text).matches()) {
                        return new Date(Long.parseLong(text) * 1000);
                    }
                    return new SimpleDateFormat(STANDARD_DATE).parse(text);
                case 13:
                    // Ja va 时间戳
                    if (JA VA_TIMESTAMP.matcher(text).matches()) {
                        return new Date(Long.parseLong(text));
                    }
                    return null;
                case 19:
                    // yyyy-MM-dd HH:mm:ss
                    return new SimpleDateFormat(STANDARD_DATETIME).parse(text);
                case 23:
                    // yyyy-MM-dd HH:mm:ss.SSS
                    return new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS").parse(text);
                default:
                    return new SimpleDateFormat(STANDARD_DATETIME).parse(text);
            }
        } catch (Exception e) {
            return null;
        }
    }

    /** 获取日期的起始时刻（00:00:00.000）. */
    public static Date getDayBegin(Date date) {
        Calendar cal = Calendar.getInstance();
        cal.setTime(date);
        cal.set(Calendar.HOUR_OF_DAY, 0);
        cal.set(Calendar.MINUTE, 0);
        cal.set(Calendar.SECOND, 0);
        cal.set(Calendar.MILLISECOND, 0);
        return cal.getTime();
    }

    /** 获取日期的结束时刻（23:59:59.999）. */
    public static Date getDayEnd(Date date) {
        Calendar cal = Calendar.getInstance();
        cal.setTime(date);
        cal.set(Calendar.HOUR_OF_DAY, 23);
        cal.set(Calendar.MINUTE, 59);
        cal.set(Calendar.SECOND, 59);
        cal.set(Calendar.MILLISECOND, 999);
        return cal.getTime();
    }

    /** 格式化为标准日期时间字符串. */
    public static String formatStandardDateTime(Date date) {
        if (date == null) return null;
        return new SimpleDateFormat(STANDARD_DATETIME).format(date);
    }

    /** 获取 N 天后的日期. */
    public static Date getDateAfter(Date date, int days) {
        Calendar cal = Calendar.getInstance();
        cal.setTime(date);
        cal.add(Calendar.DAY_OF_MONTH, days);
        return cal.getTime();
    }
}

3.3 StringUtil（字符串/JSON 工具）

package com.example.utils;

import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import ja va.util.regex.Pattern;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
 * 字符串和JSON工具类.
 * 
 * 核心功能：
 * 1. JSON 序列化/反序列化（容错模式）
 * 2. 特殊字符检测和替换（中文/Emoji/符号）
 * 3. 驼峰拆分
 */
public class StringUtil {

    private static final Logger logger = LoggerFactory.getLogger(StringUtil.class);
    private static final Pattern CHINESE_CHAR = Pattern.compile("[\u4e00-\u9fa5]");
    private static final Pattern EMOJI_CHAR = Pattern.compile("[\ud800-\udfff]");

    // 全局单例 ObjectMapper（线程安全）
    private static final ObjectMapper READ_MAPPER = new ObjectMapper()
        .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
    private static final ObjectMapper WRITE_MAPPER = new ObjectMapper()
        .configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false);

    /**
     * 对象序列化为 JSON 字符串.
     * 异常时返回空字符串，不抛出异常.
     */
    public static String getJsonString(Object obj) {
        if (obj == null) {
            return "";
        }
        if (obj instanceof String) {
            return (String) obj;
        }
        try {
            return WRITE_MAPPER.writeValueAsString(obj);
        } catch (Exception e) {
            logger.error("JSON序列化失败", e);
            return "";
        }
    }

    /**
     * JSON 字符串反序列化为对象.
     */
    public static  T parseJsonString(String json, Class clazz) {
        if (json == null || json.isEmpty()) {
            return null;
        }
        try {
            return READ_MAPPER.readValue(json, clazz);
        } catch (Exception e) {
            logger.error("JSON反序列化失败", e);
            return null;
        }
    }

    /**
     * JSON 字符串反序列化（泛型支持）.
     */
    public static  T parseJsonString(String json, TypeReference typeRef) {
        if (json == null || json.isEmpty()) {
            return null;
        }
        try {
            return READ_MAPPER.readValue(json, typeRef);
        } catch (Exception e) {
            logger.error("JSON反序列化失败", e);
            return null;
        }
    }

    /** 是否包含中文字符. */
    public static boolean containsChinese(String str) {
        return str != null && CHINESE_CHAR.matcher(str).find();
    }

    /** 是否包含 Emoji 字符. */
    public static boolean containsEmoji(String str) {
        return str != null && EMOJI_CHAR.matcher(str).find();
    }

    /** 替换 Emoji 为指定字符. */
    public static String replaceEmoji(String str, String replacement) {
        if (str == null) return null;
        return EMOJI_CHAR.matcher(str).replaceAll(replacement);
    }
}

3.4 Auth2SessionIdUtil（请求上下文工具）

package com.example.utils;

/**
 * OAuth2 请求级别上下文工具.
 * 通过 ThreadLocal 存储当前请求的用户信息，在同一请求内全局可访问.
 * 
 * 使用场景：
 * - Filter/Interceptor 中设置（请求进入时）
 * - Service 层中读取（业务处理时）
 * - Filter 中清理（请求结束时）
 * 
 * 注意：必须在请求结束时调用 delete() 清理，防止线程池复用导致数据串线.
 */
public final class Auth2SessionIdUtil {

    private static final ThreadLocal sessionIdLocal = new ThreadLocal<>();
    private static final ThreadLocal tokenLocal = new ThreadLocal<>();
    private static final ThreadLocal loginNameLocal = new ThreadLocal<>();

    /** 获取当前请求的会话ID. */
    public static String getSessionId() {
        return sessionIdLocal.get();
    }

    public static void setSessionId(String sessionId) {
        sessionIdLocal.set(sessionId);
    }

    /** 获取当前请求的 OAuth2 Token. */
    public static String getToken() {
        return tokenLocal.get();
    }

    public static void setToken(String token) {
        tokenLocal.set(token);
    }

    /** 获取当前登录用户名. */
    public static String getLoginName() {
        return loginNameLocal.get();
    }

    public static void setLoginName(String loginName) {
        loginNameLocal.set(loginName);
    }

    /**
     * 清理所有 ThreadLocal 数据.
     * 必须在请求结束时调用！防止线程池复用导致数据泄露.
     */
    public static void delete() {
        sessionIdLocal.remove();
        tokenLocal.remove();
        loginNameLocal.remove();
    }
}

3.5 pom.xml（工具库）

    com.example
    example-utils
    1.0.0
    jar
    
        
        
            com.fasterxml.jackson.core
            jackson-databind
            provided
        
        
        
            ja vax.servlet
            ja vax.servlet-api
            provided
        
        
        
            org.springframework
            spring-context
            provided
        
        
        
            org.slf4j
            slf4j-api
            provided
        
    

四、引入方使用

4.1 添加依赖

    com.example
    example-utils
    1.0.0

4.2 使用示例

@Service
public class OrderService {

    public void processOrder(OrderDto dto) {
        // 参数校验
        if (CheckEmptyUtil.isOrEmpty(dto.getOrderCode(), dto.getMemberId())) {
            throw new IllegalArgumentException("参数不能为空");
        }

        // 日期处理
        Date deliveryDate = DateUtil.convertToDate(dto.getDeliveryTime());  // 自动识别格式
        Date deadline = DateUtil.getDateAfter(deliveryDate, 3);            // 3天后

        // JSON 序列化（记日志）
        log.info("处理订单入参: {}", StringUtil.getJsonString(dto));

        // 空值安全操作
        if (CheckEmptyUtil.isNotEmpty(dto.getItemList())) {
            dto.getItemList().forEach(item -> {
                // 业务逻辑...
            });
        }
    }
}

五、关键设计总结