xxx.xxx.xxx.utils
├── CheckEmptyUtil.java          // 空值判斷工具（使用頻率最高）
├── DateUtil.java                // 日期工具（舊API，java.util.Date）
├── StringUtil.java              // 字符串/JSON工具（序列化+特殊字符處理）
├── JsonUtil.java                // JSON 序列化工具（支持 Snake Case）
├── Auth2SessionIdUtil.java      // OAuth2 會(huì)話上下文（ThreadLocal）
├── IpUtil.java                  // IP 地址工具
├── AesUtil.java                 // AES 加解密工具
├── Md5Utils.java                // MD5 摘要工具
├── xxxI18nUtil.java             // 國(guó)際化消息工具
├── FileUtil.java                // 文件操作工具
├── JasperUtil.java              // 報(bào)表導(dǎo)出工具（Jasper）
├── PdfUtil.java                 // PDF 生成工具
├── ClassNameUtil.java           // 類名處理工具
├── xxxSerializationUtils.java   // Java 序列化工具
├── PackageUtil.java             // 包掃描工具
├── UrlUtil.java                 // URL 處理工具
├── cloud/
│   ├── AdapterHeader.java       // 適配器 Header 工具
│   └── LoginToken.java          // 登錄 Token 封裝
└── time/
    ├── DateTimeUtil.java        // 日期時(shí)間工具（新API，java.time）
    ├── DateTimeFormat.java      // 日期格式枚舉（20+種預(yù)定義格式）
    ├── DateTimeConverter.java   // 日期轉(zhuǎn)換器
    └── ZoneEnums.java           // 時(shí)區(qū)枚舉

package com.example.utils;

import java.lang.reflect.Array;
import java.util.Collection;
import java.util.Map;
import java.util.Optional;

/**
 * 通用空值判斷工具.
 * 統(tǒng)一處理各種類型的空值判斷，替代業(yè)務(wù)代碼中的 != null && !isEmpty() 鏈?zhǔn)脚袛?
 * 
 * 支持類型：
 * - null
 * - String（空字符串）
 * - Collection（空集合）
 * - Map（空Map）
 * - Array（空數(shù)組）
 * - Optional（空Optional）
 * - 其他 Object（僅判null）
 */
public class CheckEmptyUtil {

    /**
     * 判斷對(duì)象是否為空.
     * 根據(jù)實(shí)際類型自動(dòng)選擇判空策略.
     */
    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;
    }

    /**
     * 判斷對(duì)象是否非空.
     */
    public static boolean isNotEmpty(Object obj) {
        return !isEmpty(obj);
    }

    /**
     * 任一參數(shù)為空返回true.
     * 常用于參數(shù)校驗(yàn)：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;
    }

    /**
     * 全部參數(shù)都為空返回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;
    }
}

package com.example.utils;

import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.Date;
import java.util.regex.Pattern;

/**
 * 日期工具類（基于 java.util.Date）.
 * 
 * 核心特性：
 * 1. 智能日期解析 - 根據(jù)字符串格式自動(dòng)識(shí)別
 * 2. 常用日期操作 - 月初/月末/日始/日終
 * 3. 日期格式化 - 標(biāo)準(zhǔn)格式輸出
 */
public class DateUtil {

    private static final Pattern UNIX_TIMESTAMP = Pattern.compile("^\\d{10}$");
    private static final Pattern JAVA_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";

    /**
     * 智能日期解析.
     * 支持：時(shí)間戳(10位/13位)、標(biāo)準(zhǔn)格式、斜杠格式.
     * 
     * @param text 日期字符串
     * @return Date 對(duì)象，解析失敗返回 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 時(shí)間戳 或 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:
                    // Java 時(shí)間戳
                    if (JAVA_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;
        }
    }

    /** 獲取日期的起始時(shí)刻（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();
    }

    /** 獲取日期的結(jié)束時(shí)刻（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();
    }

    /** 格式化為標(biāo)準(zhǔn)日期時(shí)間字符串. */
    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();
    }
}

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 java.util.regex.Pattern;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
 * 字符串和JSON工具類.
 * 
 * 核心功能：
 * 1. JSON 序列化/反序列化（容錯(cuò)模式）
 * 2. 特殊字符檢測(cè)和替換（中文/Emoji/符號(hào)）
 * 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);

    /**
     * 對(duì)象序列化為 JSON 字符串.
     * 異常時(shí)返回空字符串，不拋出異常.
     */
    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 字符串反序列化為對(duì)象.
     */
    public static <T> T parseJsonString(String json, Class<T> 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> T parseJsonString(String json, TypeReference<T> 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);
    }
}

package com.example.utils;

/**
 * OAuth2 請(qǐng)求級(jí)別上下文工具.
 * 通過 ThreadLocal 存儲(chǔ)當(dāng)前請(qǐng)求的用戶信息，在同一請(qǐng)求內(nèi)全局可訪問.
 * 
 * 使用場(chǎng)景：
 * - Filter/Interceptor 中設(shè)置（請(qǐng)求進(jìn)入時(shí)）
 * - Service 層中讀?。I(yè)務(wù)處理時(shí)）
 * - Filter 中清理（請(qǐng)求結(jié)束時(shí)）
 * 
 * 注意：必須在請(qǐng)求結(jié)束時(shí)調(diào)用 delete() 清理，防止線程池復(fù)用導(dǎo)致數(shù)據(jù)串線.
 */
public final class Auth2SessionIdUtil {

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

    /** 獲取當(dāng)前請(qǐng)求的會(huì)話ID. */
    public static String getSessionId() {
        return sessionIdLocal.get();
    }

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

    /** 獲取當(dāng)前請(qǐng)求的 OAuth2 Token. */
    public static String getToken() {
        return tokenLocal.get();
    }

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

    /** 獲取當(dāng)前登錄用戶名. */
    public static String getLoginName() {
        return loginNameLocal.get();
    }

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

    /**
     * 清理所有 ThreadLocal 數(shù)據(jù).
     * 必須在請(qǐng)求結(jié)束時(shí)調(diào)用！防止線程池復(fù)用導(dǎo)致數(shù)據(jù)泄露.
     */
    public static void delete() {
        sessionIdLocal.remove();
        tokenLocal.remove();
        loginNameLocal.remove();
    }
}

<project>
    <groupId>com.example</groupId>
    <artifactId>example-utils</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>
    <dependencies>
        <!-- JSON -->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <scope>provided</scope>
        </dependency>
        <!-- Servlet（獲取IP等） -->
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <scope>provided</scope>
        </dependency>
        <!-- Spring Context（國(guó)際化） -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-context</artifactId>
            <scope>provided</scope>
        </dependency>
        <!-- 日志 -->
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</project>

<dependency>
    <groupId>com.example</groupId>
    <artifactId>example-utils</artifactId>
    <version>1.0.0</version>
</dependency>

@Service
public class OrderService {

    public void processOrder(OrderDto dto) {
        // 參數(shù)校驗(yàn)
        if (CheckEmptyUtil.isOrEmpty(dto.getOrderCode(), dto.getMemberId())) {
            throw new IllegalArgumentException("參數(shù)不能為空");
        }

        // 日期處理
        Date deliveryDate = DateUtil.convertToDate(dto.getDeliveryTime());  // 自動(dòng)識(shí)別格式
        Date deadline = DateUtil.getDateAfter(deliveryDate, 3);            // 3天后

        // JSON 序列化（記日志）
        log.info("處理訂單入?yún)? {}", StringUtil.getJsonString(dto));

        // 空值安全操作
        if (CheckEmptyUtil.isNotEmpty(dto.getItemList())) {
            dto.getItemList().forEach(item -> {
                // 業(yè)務(wù)邏輯...
            });
        }
    }
}