提交

src/main/java/com/jiudian/manage/until/FileUtil.java

@@ -1,18 +1,44 @@
-package com.jiudian.manage.until;
+package com.jiudian.manage.until;  // 工具类包，存放系统通用工具方法
 
 import java.io.File;
 import java.io.FileOutputStream;
 
+/**
+ * 文件操作工具类
+ * 提供文件上传的通用方法，支撑系统中文件（如用户头像、凭证图片）的服务器存储功能
+ */
 public class FileUtil {
+
+    /**
+     * 上传文件到服务器指定路径
+     * @param file 待上传的文件字节数组（前端传递的文件会转为字节数组形式传输）
+     * @param filePath 服务器上的文件存储目录路径（如"D:/hotel_upload/avatar/"）
+     * @param fileName 上传后的文件名（建议包含唯一标识，避免文件名重复覆盖）
+     * @return 布尔值：true=上传成功，false=上传失败（实际逻辑中当前仅返回true，异常通过throws抛出）
+     * @throws Exception 抛出文件操作相关异常（如IO异常、权限异常），需调用方捕获处理
+     */
     public static boolean uploadFile(byte[] file, String filePath, String fileName) throws Exception {
+        // 1. 根据存储目录路径创建File对象
         File targetFile = new File(filePath);
-        if(!targetFile.exists()){
+
+        // 2. 判断存储目录是否存在，不存在则创建多级目录（mkdirs()支持创建嵌套目录，mkdir()不支持）
+        if (!targetFile.exists()) {
             targetFile.mkdirs();
         }
-        FileOutputStream out = new FileOutputStream(filePath+fileName);
+
+        // 3. 创建文件输出流，指定文件存储路径（目录路径 + 文件名）
+        FileOutputStream out = new FileOutputStream(filePath + fileName);
+
+        // 4. 将文件字节数组写入到输出流（即写入到服务器文件）
         out.write(file);
+
+        // 5. 刷新输出流，确保所有字节都被写入文件
         out.flush();
+
+        // 6. 关闭输出流，释放IO资源（避免资源泄漏）
         out.close();
+
+        // 7. 文件写入完成，返回上传成功
         return true;
     }
-}
+}

src/main/java/com/jiudian/manage/until/ImageCode.java

@@ -9,33 +9,77 @@ import java.io.IOException;
 import java.io.OutputStream;
 import java.util.Random;
 
+/**
+ * 验证码生成工具类
+ * 用于生成图形验证码，支撑用户登录时的安全校验，防止恶意登录或自动化脚本攻击
+ */
 public class ImageCode {
-    public static final String CODENAME="ImageCode";
+    // 验证码在HttpSession中的存储键名（固定值，登录时需通过该键名获取Session中的验证码）
+    public static final String CODENAME = "ImageCode";
+
+    /**
+     * 生成图形验证码并响应给前端，同时将验证码存入Session
+     * @param response HttpServletResponse，用于向前端输出验证码图片
+     * @param session HttpSession，用于存储生成的验证码（供登录时校验）
+     * @throws IOException 图片写入响应流时可能抛出IO异常，需调用方处理
+     */
     public static void createImage(HttpServletResponse response, HttpSession session) throws IOException {
+        // 1. 创建 BufferedImage 对象（验证码图片载体）：宽80px、高30px，RGB色彩模式
         BufferedImage image = new BufferedImage(80, 30, BufferedImage.TYPE_INT_RGB);
+
+        // 2. 获取 Graphics 对象（用于在图片上绘制内容：背景、验证码文字、干扰元素等）
         Graphics g = image.getGraphics();
+
+        // 3. 创建随机数对象（用于生成随机颜色、干扰元素位置等，增强验证码安全性）
         Random r = new Random();
+
+        // 4. 绘制验证码背景：随机颜色填充矩形（覆盖整个图片区域，宽80px、高20px）
         g.setColor(new Color(r.nextInt(255), r.nextInt(255), r.nextInt(255)));
         g.fillRect(0, 0, 80, 20);
-        //获取生成的验证码
+
+        // 5. 生成4位随机验证码（数字+大写字母组合）
         String code = getNumber();
-        //绑定验证码
+
+        // 6. 将生成的验证码存入Session：键为CODENAME，值为验证码，供后续登录校验使用
         session.setAttribute(CODENAME, code);
+
+        // 7. 设置验证码文字样式：无衬线字体、加粗、字号25px
         g.setFont(new Font(Font.SANS_SERIF, Font.BOLD, 25));
+
+        // 8. 设置验证码文字颜色：随机RGB颜色（与背景色区分，确保清晰可见）
         g.setColor(new Color(r.nextInt(255), r.nextInt(255), r.nextInt(255)));
+
+        // 9. 绘制验证码文字到图片：起始位置（x=5px，y=25px），避免文字超出图片边界
         g.drawString(code, 5, 25);
-        //设置消息头
+
+        // 10. 设置响应头：指定返回内容类型为image/jpeg（告诉前端这是图片数据）
         response.setContentType("image/jpeg");
+
+        // 11. 获取响应输出流，将验证码图片以jpeg格式写入流，响应给前端
         OutputStream os = response.getOutputStream();
         ImageIO.write(image, "jpeg", os);
     }
-    public static String getNumber(){
+
+    /**
+     * 生成4位随机验证码（包含数字0-9和大写字母A-Z，增强验证码复杂度）
+     * @return 4位随机字符串（验证码内容）
+     */
+    public static String getNumber() {
+        // 1. 定义验证码字符池：包含数字和大写字母，共36个字符
         String str = "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+        // 2. 初始化验证码字符串（用于拼接最终结果）
         String code = "";
-        for(int i= 0;i<4;i++){
-            int index = (int)(Math.random()*str.length());
-            code+=str.charAt(index);
+
+        // 3. 循环4次，每次从字符池中随机选取1个字符，组成4位验证码
+        for (int i = 0; i < 4; i++) {
+            // 生成0到str长度-1的随机索引（确保不越界）
+            int index = (int) (Math.random() * str.length());
+            // 根据索引获取字符，拼接到验证码中
+            code += str.charAt(index);
         }
+
+        // 4. 返回生成的4位验证码
         return code;
     }
 }

src/main/java/com/jiudian/manage/until/State.java

@@ -1,23 +1,41 @@
 package com.jiudian.manage.until;
 
-public enum  State {
-    SuccessCode("code","0"),SuccessMessage("message","成功"),
-    ErrorCode("code","-1"),ErrorMessage("message","失败")
-    ;
+/**
+ * 系统统一状态枚举类
+ * 定义接口响应的标准状态码和提示信息，确保所有接口返回格式一致，简化前后端交互逻辑
+ */
+public enum State {
+    // 成功状态：code=0，message=成功（用于所有业务操作成功的响应，如订单创建成功、用户登录成功）
+    SuccessCode("code", "0"),
+    SuccessMessage("message", "成功"),
 
+    // 失败状态：code=-1，message=失败（用于所有业务操作失败的通用响应，如参数错误、数据库操作失败）
+    ErrorCode("code", "-1"),
+    ErrorMessage("message", "失败");
 
+
+    // 状态对应的键名（如"code"表示状态码的键，"message"表示提示信息的键）
     public String name;
+    // 状态对应的键值（如"0"是成功状态码的值，"成功"是成功提示的值）
     public String message;
-    State(String name,String message) {
+
+    /**
+     * 枚举构造方法（枚举的构造方法默认私有，仅在枚举内部创建实例时使用）
+     * @param name 状态键名（如"code"、"message"）
+     * @param message 状态键值（如"0"、"成功"）
+     */
+    State(String name, String message) {
         this.name = name;
         this.message = message;
     }
+
+    // 获取状态键名的getter方法（供外部访问枚举的name属性）
     public String getName() {
         return name;
     }
 
+    // 获取状态键值的getter方法（供外部访问枚举的message属性）
     public String getMessage() {
         return message;
     }
-
-}
+}

src/main/java/com/jiudian/manage/until/StateSignal.java

@@ -2,15 +2,39 @@ package com.jiudian.manage.until;
 
 import java.util.HashMap;
 
+/**
+ * 接口响应结果封装工具类
+ * 配合State枚举，统一封装接口返回的状态码、提示信息和业务数据，确保前后端交互格式一致
+ */
 public class StateSignal {
-    HashMap<String,Object> result = new HashMap<String,Object>();
+    // 存储响应结果的核心容器（HashMap）：key为字段名（如"code"、"message"、"data"），value为对应值
+    HashMap<String, Object> result = new HashMap<String, Object>();
 
-    public void put(State state){
-        result.put(state.name,state.message);
+    /**
+     * 传入State枚举，快速添加状态码或提示信息到响应结果
+     * 用于标准化添加"成功/失败"的核心状态字段（避免手动写key，减少错误）
+     * @param state 状态枚举（如State.SuccessCode、State.SuccessMessage）
+     */
+    public void put(State state) {
+        // 将枚举的name（键名，如"code"）和message（键值，如"0"）存入result
+        result.put(state.name, state.message);
     }
-    public void put(String name,Object val){
-        result.put(name,val);
+
+    /**
+     * 自定义添加键值对到响应结果
+     * 用于添加业务数据（如订单列表、用户信息）或自定义提示（如"验证码错误"）
+     * @param name 自定义键名（如"data"、"errorMsg"）
+     * @param val 对应的值（如订单List、"验证码错误，请重新输入"）
+     */
+    public void put(String name, Object val) {
+        result.put(name, val);
     }
+
+    /**
+     * 获取完整的响应结果容器
+     * 供Controller层调用，直接将结果返回给前端（Spring会自动转为JSON格式）
+     * @return 包含状态码、提示信息、业务数据的HashMap
+     */
     public HashMap<String, Object> getResult() {
         return result;
     }

src/main/java/com/jiudian/manage/until/TimeUtil.java

@@ -6,38 +6,67 @@ import java.util.Calendar;
 import java.util.Date;
 import java.util.GregorianCalendar;
 
+/**
+ * 时间操作工具类
+ * 提供时间格式转换、日期差值计算的通用方法，支撑系统中时间相关业务（如订单入住天数计算、时间格式统一）
+ */
 public class TimeUtil {
+
     /**
-     * 获取两个时间段的天数从date2-date1
-     * @param date1
-     * @param date2
-     * @return
+     * 计算两个日期之间的天数差（结果为 date2 - date1 的天数，支持跨年份计算）
+     * 用于订单金额计算（入住天数 × 房间单价 = 订单总金额）
+     * @param date1 起始日期字符串（格式：yyyy-MM-dd，如"2024-05-01"）
+     * @param date2 结束日期字符串（格式：yyyy-MM-dd，如"2024-05-05"）
+     * @return 两个日期的天数差（如上述示例返回4，表示入住4天）
      */
-    public static int getBetweenDay(String  date1, String date2) {
+    public static int getBetweenDay(String date1, String date2) {
+        // 1. 创建GregorianCalendar实例（日历对象），用于处理日期计算
         Calendar d1 = new GregorianCalendar();
-        d1.setTime(formatterTime(date1));
         Calendar d2 = new GregorianCalendar();
+
+        // 2. 将传入的日期字符串转为Date类型，再设置到日历对象中
+        d1.setTime(formatterTime(date1));
         d2.setTime(formatterTime(date2));
+
+        // 3. 先计算同一年份内的天数差（结束日期的年天数 - 起始日期的年天数）
         int days = d2.get(Calendar.DAY_OF_YEAR) - d1.get(Calendar.DAY_OF_YEAR);
-        int y2 = d2.get(Calendar.YEAR);
-        if (d1.get(Calendar.YEAR) != y2) {
+
+        // 4. 获取结束日期的年份，判断是否跨年份（起始年份 != 结束年份）
+        int endYear = d2.get(Calendar.YEAR);
+        if (d1.get(Calendar.YEAR) != endYear) {
+            // 5. 跨年份时，累加起始年份到结束年份之间每一年的总天数
             do {
+                // 累加当前起始年份的总天数（如2023年有365天）
                 days += d1.getActualMaximum(Calendar.DAY_OF_YEAR);
+                // 起始年份加1，继续计算下一年，直到起始年份等于结束年份
                 d1.add(Calendar.YEAR, 1);
-            } while (d1.get(Calendar.YEAR) != y2);
+            } while (d1.get(Calendar.YEAR) != endYear);
         }
+
+        // 6. 返回最终的天数差
         return days;
     }
 
-    public static Date formatterTime(String date){
+    /**
+     * 将字符串格式的日期转为Date类型（固定格式：yyyy-MM-dd）
+     * 解决前端传递的日期字符串与后端Date类型不兼容的问题，统一日期格式
+     * @param date 日期字符串（格式必须为yyyy-MM-dd，否则会抛出ParseException并打印异常栈）
+     * @return 转换后的Date对象，转换失败时返回null
+     */
+    public static Date formatterTime(String date) {
+        // 1. 创建SimpleDateFormat实例，指定目标日期格式（yyyy-MM-dd）
         SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd");
-        Date newDate=null;
+        Date newDate = null;
+
+        // 2. 尝试解析日期字符串，捕获ParseException（格式不匹配时抛出）
         try {
-            newDate= formatter.parse(date);
+            newDate = formatter.parse(date);
         } catch (ParseException e) {
+            // 3. 解析失败时打印异常栈，便于排查问题（如前端传递错误格式的日期）
             e.printStackTrace();
         }
+
+        // 4. 返回转换后的Date对象（失败时为null）
         return newDate;
     }
-
-}
+}

src/main/java/com/jiudian/manage/until/UUIDUtil.java

@@ -2,7 +2,12 @@ package com.jiudian.manage.until;
 
 import java.util.UUID;
 
+/**
+ * UUID工具类
+ * 提供短UUID生成功能，解决原生UUID过长的问题，适用于需要短唯一标识的场景（如临时ID、默认字段值）
+ */
 public class UUIDUtil {
+    // 短UUID的字符池：包含小写字母、数字、大写字母，共62个字符（确保生成的标识多样性）
     public static String[] chars = new String[] { "a", "b", "c", "d", "e", "f",
             "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s",
             "t", "u", "v", "w", "x", "y", "z", "0", "1", "2", "3", "4", "5",
@@ -11,17 +16,30 @@ public class UUIDUtil {
             "W", "X", "Y", "Z" };
 
     /**
-     * 生成8位UUID
-     * @return 8位UUID
+     * 生成8位长度的短UUID（基于原生UUID压缩，确保全局唯一性）
+     * 相比原生36位UUID更简洁，适合存储或展示在界面上
+     * @return 8位随机唯一字符串（如"xY3a7B9z"）
      */
     public static String generateShortUuid() {
+        // 1. 创建StringBuffer，用于拼接最终的8位短UUID
         StringBuffer shortBuffer = new StringBuffer();
+
+        // 2. 生成原生UUID（36位，含"-"），并去除"-"符号，得到32位纯字母数字字符串
         String uuid = UUID.randomUUID().toString().replace("-", "");
+
+        // 3. 循环8次，每次从32位UUID中截取4位，转换为字符池中的字符，组成8位短UUID
         for (int i = 0; i < 8; i++) {
+            // 截取4位字符串（如第1次截取0-4位，第2次截取4-8位，以此类推）
             String str = uuid.substring(i * 4, i * 4 + 4);
+
+            // 将4位16进制字符串转为整数（16进制转10进制）
             int x = Integer.parseInt(str, 16);
-            shortBuffer.append(chars[x % 0x3E]);
+
+            // 取整数对62取余（对应字符池长度），获取字符池中的索引，拼接字符
+            shortBuffer.append(chars[x % 0x3E]); // 0x3E即62，与字符池长度一致
         }
+
+        // 4. 返回最终的8位短UUID
         return shortBuffer.toString();
     }
-}
+}