111

snailmall-user-service/src/main/java/com/njupt/swg/cache/CommonCacheUtil.java

@@ -8,73 +8,96 @@ import redis.clients.jedis.Jedis;
 import redis.clients.jedis.JedisPool;
 
 /**
+ * 该类CommonCacheUtil是一个工具类，用于与Redis缓存进行交互操作，提供了如缓存数据、获取缓存数据、设置带过期时间的缓存以及删除缓存等常用功能。
+ * 它依赖于JedisPoolWrapper来获取JedisPool对象，进而操作Redis缓存，并且在操作过程中如果出现异常会抛出SnailmallException异常，同时记录相关的日志信息用于排查问题。
+ * 此类被标记为Spring的@Component组件，方便在Spring容器中进行管理和注入使用。
  * @Author swg.
  * @Date 2019/1/1 15:03
  * @CONTACT 317758022@qq.com
  * @DESC
  */
 @Component
+// 该注解表明这个类是Spring框架中的一个组件，Spring会自动扫描并将其纳入到容器管理中，使其可以被其他需要使用的类进行依赖注入。
 @Slf4j
+// 使用lombok的@Slf4j注解，自动生成一个名为log的日志记录对象，方便在类中记录日志信息，便于后续调试和查看与Redis交互过程中出现的问题情况。
 public class CommonCacheUtil {
 
     @Autowired
+    // 使用Spring的依赖注入功能，自动注入JedisPoolWrapper的实例，通过它来获取JedisPool，从而能够获取Jedis客户端连接到Redis服务器进行操作。
     private JedisPoolWrapper jedisPoolWrapper;
 
-
     /**
-     * 缓存永久key
+     * 缓存永久key的方法，用于将指定的键值对存储到Redis缓存中，且该缓存数据没有设置过期时间（永久有效，除非手动删除）。
+     *
+     * @param key   要存储到Redis中的键，用于唯一标识缓存数据，后续可以通过该键来获取对应的缓存值。
+     * @param value 要存储到Redis中的值，对应键所关联的数据内容，可以是各种序列化后的字符串形式的数据（如JSON字符串等）。
      */
     public void cache(String key, String value) {
         try {
             JedisPool pool = jedisPoolWrapper.getJedisPool();
-            if (pool != null) {
-                try (Jedis Jedis = pool.getResource()) {
-                    Jedis.select(0);
-                    Jedis.set(key, value);
+            if (pool!= null) {
+                try (Jedis jedis = pool.getResource()) {
+                    jedis.select(0);
+                    // 使用Jedis客户端将指定的键值对存储到Redis中，默认存储到Redis的第0个数据库（Redis可以有多个数据库，通过select方法选择）。
+                    jedis.set(key, value);
                 }
             }
         } catch (Exception e) {
             log.error("redis存值失败", e);
+            // 如果在存储过程中出现异常，记录错误日志，并抛出SnailmallException异常，提示“redis报错”，由全局异常处理机制进行处理。
             throw new SnailmallException("redis报错");
         }
     }
 
     /**
-     * 获取缓存key
+     * 获取缓存key对应的缓存值的方法，用于从Redis缓存中根据指定的键获取对应的值。
+     *
+     * @param key 要从Redis中获取值的键，通过该键来查找之前存储在Redis中的对应缓存数据。
+     * @return 返回从Redis中获取到的对应键的值，如果键不存在则返回null，若获取过程中出现异常会抛出相应异常。
      */
     public String getCacheValue(String key) {
         String value = null;
         try {
             JedisPool pool = jedisPoolWrapper.getJedisPool();
-            if (pool != null) {
-                try (Jedis Jedis = pool.getResource()) {
-                    Jedis.select(0);
-                    value = Jedis.get(key);
+            if (pool!= null) {
+                try (Jedis jedis = pool.getResource()) {
+                    jedis.select(0);
+                    // 使用Jedis客户端根据指定的键从Redis中获取对应的值，默认从Redis的第0个数据库中查找。
+                    value = jedis.get(key);
                 }
             }
         } catch (Exception e) {
             log.error("redis获取指失败", e);
+            // 如果在获取过程中出现异常，记录错误日志，并抛出SnailmallException异常，提示“redis报错”，由全局异常处理机制进行处理。
             throw new SnailmallException("redis报错");
         }
         return value;
     }
 
     /**
-     * 过期key
+     * 过期key的方法，用于将指定的键值对存储到Redis缓存中，并同时设置该缓存数据的过期时间，且只有在键不存在时才设置成功（原子操作）。
+     *
+     * @param key    要存储到Redis中的键，用于唯一标识缓存数据，后续可以通过该键来获取对应的缓存值以及判断其是否过期等情况。
+     * @param value  要存储到Redis中的值，对应键所关联的数据内容，可以是各种序列化后的字符串形式的数据（如JSON字符串等）。
+     * @param expire 要设置的缓存数据的过期时间，单位为秒，表示从存储该缓存数据开始，经过指定的秒数后，该缓存数据将自动从Redis中删除。
+     * @return 返回一个长整型结果，表示设置操作是否成功，若返回1表示设置成功（键不存在，成功设置了键值对并设置了过期时间），若返回0表示设置失败（键已存在）。
      */
     public long cacheNxExpire(String key, String value, int expire) {
         long result = 0;
         try {
             JedisPool pool = jedisPoolWrapper.getJedisPool();
-            if (pool != null) {
+            if (pool!= null) {
                 try (Jedis jedis = pool.getResource()) {
                     jedis.select(0);
+                    // 先使用Jedis的setnx方法尝试设置键值对，只有在键不存在时才会设置成功，返回1；若键已存在则设置失败，返回0。这是一个原子操作。
                     result = jedis.setnx(key, value);
+                    // 如果设置键值对成功（即setnx返回1），再使用expire方法设置该键对应的缓存数据的过期时间，单位为秒。
                     jedis.expire(key, expire);
                 }
             }
         } catch (Exception e) {
             log.error("redis塞值和设置缓存时间失败", e);
+            // 如果在设置过程中出现异常，记录错误日志，并抛出SnailmallException异常，提示“redis报错”，由全局异常处理机制进行处理。
             throw new SnailmallException("redis报错");
         }
 
@@ -82,23 +105,24 @@ public class CommonCacheUtil {
     }
 
     /**
-     * 删除缓存key
+     * 删除缓存key的方法，用于从Redis缓存中删除指定的键及其对应的数据。
+     *
+     * @param key 要从Redis中删除的键，通过该键来定位并删除对应的缓存数据。
      */
     public void delKey(String key) {
         JedisPool pool = jedisPoolWrapper.getJedisPool();
-        if (pool != null) {
+        if (pool!= null) {
             try (Jedis jedis = pool.getResource()) {
                 jedis.select(0);
                 try {
+                    // 使用Jedis客户端根据指定的键从Redis中删除对应的缓存数据，默认从Redis的第0个数据库中删除。
                     jedis.del(key);
                 } catch (Exception e) {
                     log.error("从redis中删除失败", e);
+                    // 如果在删除过程中出现异常，记录错误日志，并抛出SnailmallException异常，提示“redis报错”，由全局异常处理机制进行处理。
                     throw new SnailmallException("redis报错");
                 }
             }
         }
     }
-
-
-
-}
+}

snailmall-user-service/src/main/java/com/njupt/swg/cache/JedisPoolWrapper.java

@@ -5,38 +5,57 @@ import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Component;
 import redis.clients.jedis.JedisPool;
 import redis.clients.jedis.JedisPoolConfig;
-
 import javax.annotation.PostConstruct;
 
 /**
+ * 该类JedisPoolWrapper是对JedisPool的一个包装类，主要用于初始化和管理JedisPool对象，以便在项目中方便地获取JedisPool来连接Redis服务器。
+ * 它通过依赖注入Parameters对象获取相关的Redis配置参数，在类初始化时（通过@PostConstruct注解标记的方法）构建JedisPool，并且提供了获取JedisPool的方法供其他类使用。
+ * 虽然当前代码只实现了单个Redis的连接池配置，但注释中提到课程中有涉及Redis客户端集群以及一致性哈希算法相关内容需要掌握，意味着后续可能有更复杂的Redis使用场景拓展。
  * @Author swg.
  * @Date 2019/1/1 15:00
  * @CONTACT 317758022@qq.com
  * @DESC 只做了单个redis，但是课程中实现的redis客户端集群，要掌握一致性hash算法
  */
 @Component
+// 该注解表明这个类是Spring框架中的一个组件，Spring会自动扫描并将其纳入到容器管理中，使其可以被其他需要使用的类进行依赖注入。
 @Slf4j
+// 使用lombok的@Slf4j注解，自动生成一个名为log的日志记录对象，方便在类中记录日志信息，便于后续调试和查看与Redis连接池初始化等相关的情况。
 public class JedisPoolWrapper {
     @Autowired
+    // 使用Spring的依赖注入功能，自动注入Parameters对象，该对象应该包含了如Redis的最大连接数、最大空闲连接数、最大等待时间等配置参数相关信息，用于构建JedisPool。
     private Parameters parameters;
 
     private JedisPool jedisPool = null;
 
+    /**
+     * @PostConstruct注解标记的方法会在类实例化之后、依赖注入完成之后自动执行，用于进行一些初始化操作。
+     * 在这里该方法主要用于初始化JedisPool对象，通过获取Parameters中的配置参数来构建JedisPool，使得后续可以通过该连接池获取Jedis客户端连接到Redis服务器。
+     */
     @PostConstruct
-    public void init(){
+    public void init() {
         try {
             JedisPoolConfig config = new JedisPoolConfig();
+            // 设置JedisPool中最大的连接总数，从Parameters对象中获取对应的配置参数，用于控制同时可以从连接池获取的Jedis客户端的最大数量，避免过多连接导致资源耗尽等问题。
             config.setMaxTotal(parameters.getRedisMaxTotal());
+            // 设置JedisPool中最大的空闲连接数，从Parameters对象中获取对应的配置参数，空闲连接是指在连接池中暂时未被使用的连接，合理设置可提高连接复用效率。
             config.setMaxIdle(parameters.getRedisMaxIdle());
+            // 设置获取连接时的最大等待时间（单位为毫秒），从Parameters对象中获取对应的配置参数，当连接池中的连接都被占用时，新的获取连接请求会等待，超过该时间则抛出异常，避免长时间阻塞。
             config.setMaxWaitMillis(parameters.getRedisMaxWaitMillis());
-            jedisPool = new JedisPool(config,parameters.getRedisHost(),parameters.getRedisPort(),2000,"xxx");
+            // 创建JedisPool对象，传入配置信息、Redis服务器的主机地址、端口号以及连接超时时间（这里设置为2000毫秒）和密码（示例中密码为"xxx"，实际中应替换为真实密码）等参数，
+            // 这样就构建好了一个可以连接到指定Redis服务器的连接池对象，后续可以通过它获取Jedis客户端进行Redis操作。
+            jedisPool = new JedisPool(config, parameters.getRedisHost(), parameters.getRedisPort(), 2000, "xxx");
             log.info("【初始化redis连接池成功】");
-        }catch (Exception e){
-            log.error("【初始化redis连接池失败】",e);
+        } catch (Exception e) {
+            log.error("【初始化redis连接池失败】", e);
         }
     }
 
+    /**
+     * 该方法用于对外提供获取JedisPool对象的功能，使得其他类可以通过该方法获取到已经初始化好的JedisPool，
+     * 进而能够从连接池中获取Jedis客户端来进行与Redis服务器的交互操作，比如执行缓存数据的读写、删除等操作。
+     * @return 返回已经初始化好的JedisPool对象，如果初始化失败（即init方法执行出现异常导致jedisPool仍为null）则返回null。
+     */
     public JedisPool getJedisPool() {
         return jedisPool;
     }
-}
+}

snailmall-user-service/src/main/java/com/njupt/swg/cache/Parameters.java

@@ -5,29 +5,43 @@ import org.springframework.beans.factory.annotation.Value;
 import org.springframework.stereotype.Component;
 
 /**
+ * 该类Parameters是一个用于存储配置参数的组件类，它通过使用Spring的@Value注解从配置文件（如application.properties或application.yml等）中读取相应的配置值，
+ * 并将这些值注入到对应的属性中，方便在整个项目中使用这些配置参数。例如，它获取了Redis相关的配置参数（如主机地址、端口号、连接池相关参数等）以及Zookeeper相关的配置参数（主机地址等），
+ * 同时使用了Lombok的@Data注解来自动生成Getter、Setter等方法，简化代码编写，便于对这些配置参数进行访问和操作。
  * @Author swg.
  * @Date 2019/1/1 14:27
  * @CONTACT 317758022@qq.com
  * @DESC
  */
 @Component
+// 该注解表明这个类是Spring框架中的一个组件，Spring会自动扫描并将其纳入到容器管理中，使其可以被其他需要使用的类进行依赖注入，方便获取配置参数。
 @Data
+// 使用Lombok的@Data注解，会自动为类中的所有非静态、非final属性生成Getter、Setter方法，同时还会生成toString、equals、hashCode等方法，方便对配置参数对象进行操作和使用。
 public class Parameters {
     /*****redis config start*******/
+    // 使用Spring的@Value注解，从配置文件中读取名为"redis.host"的配置项的值，并将其注入到redisHost属性中，该属性用于存储Redis服务器的主机地址，方便后续连接Redis时使用。
     @Value("${redis.host}")
     private String redisHost;
+    // 使用Spring的@Value注解，从配置文件中读取名为"redis.port"的配置项的值，并将其注入到redisPort属性中，该属性用于存储Redis服务器的端口号，以便在创建连接时指定正确的端口进行通信。
     @Value("${redis.port}")
     private int redisPort;
+    // 此处可能存在属性名的配置错误（通常max-idle应该对应MaxIdle，max-total对应MaxTotal），但按照代码逻辑，该属性用于从配置文件中读取名为"redis.max-idle"的配置项的值，
+    // 并注入到redisMaxTotal属性中，本意可能是存储Redis连接池的最大空闲连接数相关参数（需确认配置项与属性的正确对应关系）。
     @Value("${redis.max-idle}")
     private int redisMaxTotal;
+    // 此处同样可能存在属性名的配置错误（通常max-total应该对应MaxTotal，max-idle对应MaxIdle），按照代码逻辑，该属性用于从配置文件中读取名为"redis.max-total"的配置项的值，
+    // 并注入到redisMaxIdle属性中，本意可能是存储Redis连接池的最大连接总数相关参数（需确认配置项与属性的正确对应关系）。
     @Value("${redis.max-total}")
     private int redisMaxIdle;
+    // 使用Spring的@Value注解，从配置文件中读取名为"redis.max-wait-millis"的配置项的值，并将其注入到redisMaxWaitMillis属性中，该属性用于存储获取Redis连接时的最大等待时间（单位为毫秒），
+    // 控制当连接池无可用连接时的等待时长，避免长时间阻塞。
     @Value("${redis.max-wait-millis}")
     private int redisMaxWaitMillis;
     /*****redis config end*******/
 
     /*****curator config start*******/
+    // 使用Spring的@Value注解，从配置文件中读取名为"zk.host"的配置项的值，并将其注入到zkHost属性中，该属性用于存储Zookeeper服务器的主机地址，方便后续与Zookeeper进行交互时使用。
     @Value("${zk.host}")
     private String zkHost;
     /*****curator config end*******/
-}
+}

snailmall-user-service/src/main/java/com/njupt/swg/common/constants/Constants.java

@@ -1,46 +1,89 @@
 package com.njupt.swg.common.constants;
 
 /**
+ * 该类Constants用于定义项目中常用的各种常量，这些常量涵盖了不同业务场景下的固定值，例如自定义的状态码、与Redis缓存相关的用户信息前缀、用户登录缓存过期时间、
+ * 用户注册重复判断的参数类型、用户角色对应的数值以及用户注册分布式锁路径等，通过将这些常量集中定义在此类中，方便在整个项目中统一使用，提高代码的可维护性和可读性。
  * @Author swg.
  * @Date 2019/1/1 13:19
  * @CONTACT 317758022@qq.com
  * @DESC
  */
 public class Constants {
-    /**自定义状态码 start**/
+    /**
+     * 自定义状态码相关的常量定义开始标识，以下几个常量用于定义不同含义的自定义状态码，方便在接口响应等场景中统一使用，用于表示请求处理的不同结果状态。
+     */
+    /**
+     * 表示请求成功的状态码，对应HTTP状态码中的200，意味着客户端发起的请求被服务器成功处理，操作顺利完成，常用于返回正确的业务响应时使用该状态码。
+     */
     public static final int RESP_STATUS_OK = 200;
 
+    /**
+     * 表示未授权的状态码，对应HTTP状态码中的401，说明客户端发起的请求没有经过授权，通常在需要用户登录或者具备特定权限才能访问的接口，而用户未满足这些条件时返回该状态码，提示客户端需要进行身份验证等操作来获取权限。
+     */
     public static final int RESP_STATUS_NOAUTH = 401;
 
+    /**
+     * 表示服务器内部错误的状态码，对应HTTP状态码中的500，意味着服务器在处理请求的过程中发生了内部错误，无法正确完成请求的处理，一般用于捕获到未预期的异常等情况时返回给客户端，告知客户端服务器出现问题，需要稍后再试等。
+     */
     public static final int RESP_STATUS_INTERNAL_ERROR = 500;
 
+    /**
+     * 表示请求参数错误的状态码，对应HTTP状态码中的400，用于客户端发送的请求参数不符合要求的场景，例如参数格式错误、缺少必要参数等情况，服务器接收到这类不符合要求的请求时，返回该状态码提示客户端检查并修正请求参数。
+     */
     public static final int RESP_STATUS_BADREQUEST = 400;
 
-    /**自定义状态码 end**/
+    /**
+     * 自定义状态码相关的常量定义结束标识
+     */
 
-    /***redis user相关的key以这个打头**/
+    /**
+     * 定义了一个字符串常量，用于表示在Redis中存储用户相关信息时的键（key）的前缀，后续存储用户相关数据（如用户登录的token等）在Redis中的键都会以这个前缀开头，方便进行统一管理和区分不同类型的数据。
+     */
     public static final String TOKEN_PREFIX = "user_";
 
     /**
-     * 用户登陆redis的过期时间
+     * 定义了一个内部接口RedisCacheExtime，用于封装与Redis缓存中用户登录相关的过期时间常量，通过接口的形式可以将相关的缓存时间配置集中管理，并且可以在代码中以一种语义化的方式来引用。
      */
-    public interface RedisCacheExtime{
-        int REDIS_SESSION_EXTIME = 60 * 60 * 10;//30分钟
+    public interface RedisCacheExtime {
+        /**
+         * 定义了用户登录信息在Redis中的过期时间，单位为秒，这里设置为60 * 60 * 10，即10个小时（原注释写的30分钟有误，实际计算应为10小时），
+         * 表示用户登录成功后，其相关登录信息（如登录凭证等存储在Redis中的数据）在缓存中保留的时长，超过这个时间，缓存数据将自动失效，需要重新进行登录等操作来更新缓存。
+         */
+        int REDIS_SESSION_EXTIME = 60 * 60 * 10;
     }
 
-    /** 用户注册判断重复的参数类型 start **/
+    /**
+     * 用户注册判断重复的参数类型相关的常量定义开始标识，以下几个常量用于定义在用户注册过程中，判断哪些参数是否重复时使用的标识类型，方便统一进行参数重复校验逻辑的处理。
+     */
+    /**
+     * 表示用于判断用户注册时电子邮箱是否重复的参数类型标识，在进行用户注册相关的业务逻辑中，通过该标识来区分当前是针对电子邮箱进行重复性检查，例如检查数据库中是否已经存在相同的电子邮箱地址。
+     */
     public static final String EMAIL = "email";
 
+    /**
+     * 表示用于判断用户注册时用户名是否重复的参数类型标识，在用户注册流程里，可依据该标识确定是对用户名进行唯一性验证，查看数据库中是否已有相同的用户名被注册使用。
+     */
     public static final String USERNAME = "username";
-    /** 用户注册判断重复的参数类型 end **/
+    /**
+     * 用户注册判断重复的参数类型相关的常量定义结束标识
+     */
 
-    /** 用户角色 **/
-    public interface Role{
-        int ROLE_CUSTOME = 0;//普通用户
-        int ROLE_ADMIN = 1;//管理员用户
+    /**
+     * 定义了一个内部接口Role，用于封装用户角色相关的常量数值，以一种更清晰、语义化的方式来表示不同的用户角色，便于在权限判断、业务逻辑处理等场景中根据角色进行不同的操作。
+     */
+    public interface Role {
+        /**
+         * 表示普通用户角色对应的数值，在项目中可以通过该数值来标识用户为普通用户身份，例如在权限分配、功能访问限制等业务逻辑中，根据这个数值来判断用户是否具有相应的操作权限，普通用户通常权限相对受限。
+         */
+        int ROLE_CUSTOME = 0;
+        /**
+         * 表示管理员用户角色对应的数值，通过该数值来区分用户为管理员身份，管理员在系统中一般拥有较高的操作权限，能够进行更多的系统管理相关操作，比如管理用户、配置系统参数等。
+         */
+        int ROLE_ADMIN = 1;
     }
 
-    /**用户注册分布式锁路径***/
+    /**
+     * 定义了一个字符串常量，用于表示用户注册分布式锁的路径，在涉及到分布式环境下处理用户注册操作时，通过使用分布式锁来保证同一时间只有一个线程或节点可以进行用户注册相关的关键操作（如写入数据库等），避免并发冲突，该路径用于标识这个分布式锁在相应的分布式协调服务（如Zookeeper等）中的具体位置。
+     */
     public static final String USER_REGISTER_DISTRIBUTE_LOCK_PATH = "/user_reg";
-
-}
+}

snailmall-user-service/src/main/java/com/njupt/swg/common/exception/ExceptionHandlerAdvice.java

@@ -1,6 +1,5 @@
 package com.njupt.swg.common.exception;
 
-
 import com.njupt.swg.common.constants.Constants;
 import com.njupt.swg.common.resp.ServerResponse;
 import lombok.extern.slf4j.Slf4j;
@@ -9,25 +8,50 @@ import org.springframework.web.bind.annotation.ExceptionHandler;
 import org.springframework.web.bind.annotation.ResponseBody;
 
 /**
+ * 该类 `ExceptionHandlerAdvice` 是一个全局异常处理类，用于在 Spring 框架下统一捕获并处理应用程序中出现的异常情况。
+ * 它通过使用 `@ControllerAdvice`、`@ResponseBody` 和 `@Slf4j` 等注解，结合 `@ExceptionHandler` 注解定义的异常处理方法，
+ * 能够将异常信息记录到日志中，并根据不同类型的异常返回相应合适的错误响应给客户端，提高应用程序的健壮性和用户体验。
+ *
  * @Author swg.
  * @Date 2019/1/1 13:21
  * @CONTACT 317758022@qq.com
  * @DESC 全局异常处理
  */
 @ControllerAdvice
+// `@ControllerAdvice` 注解表明这个类是一个全局的异常处理组件，它可以对整个应用程序中的控制器（Controller）层抛出的异常进行统一处理。
 @ResponseBody
+// `@ResponseBody` 注解表示该类中处理异常的方法返回的结果会直接作为响应体返回给客户端，而不是进行视图解析等操作，通常用于返回 JSON 格式等数据给客户端。
 @Slf4j
+// `@Slf4j` 注解使用了 Lombok 提供的日志功能，会自动生成一个名为 `log` 的日志记录对象，方便在类中记录异常相关的日志信息，便于后续排查问题。
 public class ExceptionHandlerAdvice {
+    /**
+     * 该方法使用 `@ExceptionHandler(Exception.class)` 注解进行标注，用于处理所有类型为 `Exception`（即最通用的异常类型）的异常情况。
+     * 当应用程序中任何地方抛出 `Exception` 及其子类异常时，都会被这个方法捕获。
+     * 它首先会将异常信息记录到日志中（方便后续开发人员查看具体的异常原因和堆栈信息进行问题排查），
+     * 然后返回一个表示服务器内部错误的响应信息给客户端，告知客户端系统出现异常，让其稍后再试。
+     * 响应中使用了在 `Constants` 类中定义的表示服务器内部错误的状态码（`RESP_STATUS_INTERNAL_ERROR`）。
+     *
+     * @param e 捕获到的 `Exception` 类型的异常对象，包含了具体的异常信息和堆栈跟踪等内容。
+     * @return 返回一个 `ServerResponse` 类型的对象，该对象是项目自定义的通用响应封装类，包含了错误状态码和对应的提示信息，用于告知客户端异常情况。
+     */
     @ExceptionHandler(Exception.class)
-    public ServerResponse handleException(Exception e){
-        log.error(e.getMessage(),e);
-        return ServerResponse.createByErrorCodeMessage(Constants.RESP_STATUS_INTERNAL_ERROR,"系统异常，请稍后再试");
+    public ServerResponse handleException(Exception e) {
+        log.error(e.getMessage(), e);
+        return ServerResponse.createByErrorCodeMessage(Constants.RESP_STATUS_INTERNAL_ERROR, "系统异常，请稍后再试");
     }
 
+    /**
+     * 该方法使用 `@ExceptionHandler(SnailmallException.class)` 注解进行标注，用于专门处理 `SnailmallException` 类型的异常情况。
+     * `SnailmallException` 应该是项目自定义的特定业务异常类型，当业务逻辑中抛出这种异常时，会被此方法捕获。
+     * 同样，它会先将异常信息记录到日志中，然后返回一个包含该异常对象中定义的异常状态码（通过 `e.getExceptionStatus()` 获取）以及异常消息（`e.getMessage()`）的响应信息给客户端，
+     * 这样针对特定业务的异常可以更精准地反馈给客户端相应的错误情况，而不是统一返回通用的服务器内部错误提示。
+     *
+     * @param e 捕获到的 `SnailmallException` 类型的异常对象，包含了业务相关的异常信息、状态码以及堆栈跟踪等内容。
+     * @return 返回一个 `ServerResponse` 类型的对象，包含对应异常的状态码和消息，用于向客户端准确传达业务异常的具体情况。
+     */
     @ExceptionHandler(SnailmallException.class)
-    public ServerResponse handleException(SnailmallException e){
-        log.error(e.getMessage(),e);
-        return ServerResponse.createByErrorCodeMessage(e.getExceptionStatus(),e.getMessage());
+    public ServerResponse handleException(SnailmallException e) {
+        log.error(e.getMessage(), e);
+        return ServerResponse.createByErrorCodeMessage(e.getExceptionStatus(), e.getMessage());
     }
-
-}
+}

snailmall-user-service/src/main/java/com/njupt/swg/common/exception/SnailmallException.java

@@ -4,22 +4,43 @@ import com.njupt.swg.common.resp.ResponseEnum;
 import lombok.Getter;
 
 /**
+ * 该类 `SnailmallException` 是自定义的运行时异常类，继承自 `java.lang.RuntimeException`。
+ * 主要用于在项目的业务逻辑处理过程中，当出现特定的、需要向上层抛出的异常情况时使用，它能够携带自定义的异常状态码以及异常消息，方便进行更精准的异常处理和反馈。
+ *
  * @Author swg.
  * @Date 2019/1/1 13:18
  * @CONTACT 317758022@qq.com
  * @DESC
  */
 @Getter
-public class SnailmallException extends RuntimeException{
+// 使用 Lombok 的 `@Getter` 注解，会自动为类中的 `exceptionStatus` 属性生成对应的 `get` 方法，方便外部获取该异常状态码的值，遵循了 Java 的封装原则，同时简化了代码编写。
+public class SnailmallException extends RuntimeException {
+    // 定义一个用于存储异常状态码的属性，初始值设置为从 `ResponseEnum.ERROR` 中获取的状态码，
+    // `ResponseEnum` 应该是一个枚举类，用于定义各种响应状态的枚举值，这里默认使用 `ERROR` 对应的状态码作为异常状态码的初始值，
+    // 意味着在没有显式指定异常状态码时，将采用这个默认值来表示异常情况。
     private int exceptionStatus = ResponseEnum.ERROR.getCode();
 
-    public SnailmallException(String msg){
+    /**
+     * 构造方法，用于创建一个 `SnailmallException` 实例，接收一个字符串类型的参数 `msg`，该参数表示异常消息内容。
+     * 调用父类（`RuntimeException`）的构造方法，将传入的 `msg` 作为异常消息传递给父类，此时异常状态码使用默认值（即 `ResponseEnum.ERROR.getCode()`）。
+     * 适用于只需要传递异常消息，而使用默认错误状态码来表示异常的场景，例如在业务逻辑中某些通用的、不太需要细分状态码的错误情况时可以使用此构造方法抛出异常。
+     *
+     * @param msg 异常消息内容，用于描述异常发生的具体情况，方便后续查看日志或者反馈给客户端知晓异常原因。
+     */
+    public SnailmallException(String msg) {
         super(msg);
     }
 
-    public SnailmallException(int code,String msg){
+    /**
+     * 另一个构造方法，接收两个参数，一个整数类型的 `code` 表示自定义的异常状态码，一个字符串类型的 `msg` 表示异常消息。
+     * 先调用父类（`RuntimeException`）的构造方法，将 `msg` 作为异常消息传递给父类，然后将传入的 `code` 赋值给 `exceptionStatus` 属性，
+     * 这样就可以根据具体业务需求灵活自定义异常状态码以及异常消息，更精准地表示不同的业务异常情况，例如针对不同业务模块、不同类型的错误可以分别设置不同的状态码和消息进行区分。
+     *
+     * @param code 自定义的异常状态码，用于在项目中更细致地区分不同的异常类型或者异常严重程度等情况，方便进行针对性的异常处理和响应。
+     * @param msg 异常消息内容，同上面构造方法中的 `msg` 参数作用一样，用于描述异常发生的具体情况。
+     */
+    public SnailmallException(int code, String msg) {
         super(msg);
         exceptionStatus = code;
     }
-
-}
+}

snailmall-user-service/src/main/java/com/njupt/swg/common/resp/ResponseEnum.java

@@ -3,23 +3,44 @@ package com.njupt.swg.common.resp;
 import lombok.Getter;
 
 /**
+ * 该枚举类 `ResponseEnum` 用于定义项目中基本的返回状态描述，它列举了几种常见的业务操作返回状态情况，
+ * 通过不同的枚举常量来表示，每个枚举常量都包含了对应的状态码和状态描述信息，方便在整个项目中统一使用这些标准化的返回状态标识，
+ * 使得不同模块之间在处理和传递操作结果时更加清晰、规范。
+ *
  * @Author swg.
  * @Date 2018/12/31 20:15
  * @CONTACT 317758022@qq.com
  * @DESC 基本的返回状态描述
  */
 @Getter
+// 使用 Lombok 的 `@Getter` 注解，会自动为枚举中的 `code` 和 `desc` 属性生成对应的获取方法，方便外部代码获取这些属性值，
+// 这样其他类在需要使用返回状态的状态码或者描述信息时，可以直接调用相应的获取方法，遵循了 Java 的封装原则，同时减少了代码冗余。
 public enum ResponseEnum {
-    SUCCESS(0,"SUCCESS"),
-    ERROR(1,"ERROR"),
-    ILLEGAL_ARGUMENTS(2,"ILLEGAL_ARGUMENTS"),
-    NEED_LOGIN(10,"NEED_LOGIN");
+    // 表示业务操作成功的枚举常量，状态码为 `0`，对应的描述信息为 `"SUCCESS"`，通常用于标识业务操作顺利完成的情况，
+    // 例如查询操作成功获取到了期望的数据、新增数据成功插入到数据库等场景下，可以使用该枚举常量来表示操作成功的返回状态。
+    SUCCESS(0, "SUCCESS"),
+    // 表示业务操作出现错误的枚举常量，状态码为 `1`，对应的描述信息为 `"ERROR"`，这是一个比较笼统的错误标识，
+    // 可用于一般性的业务操作失败情况，比如在执行某个业务逻辑时发生了未预期的异常、或者满足了某种错误条件但不需要细分具体错误类型时，可以使用该枚举常量返回给调用者表示操作失败。
+    ERROR(1, "ERROR"),
+    // 表示参数非法的枚举常量，状态码为 `2`，对应的描述信息为 `"ILLEGAL_ARGUMENTS"`，主要用于客户端传入的参数不符合要求的场景，
+    // 例如参数格式错误、缺少必要参数、参数取值超出合法范围等情况，服务端在进行参数校验后发现参数不合法时，就可以返回该枚举常量对应的状态来告知调用者参数存在问题。
+    ILLEGAL_ARGUMENTS(2, "ILLEGAL_ARGUMENTS"),
+    // 表示需要登录的枚举常量，状态码为 `10`，对应的描述信息为 `"NEED_LOGIN"`，用于提示客户端当前操作需要先进行登录认证的场景，
+    // 比如客户端尝试访问某些需要登录权限才能操作的接口，但却未提供有效的登录凭证时，服务端就可以返回该枚举常量对应的状态，告知客户端需要先登录再进行后续操作。
+    NEED_LOGIN(10, "NEED_LOGIN");
 
     private int code;
     private String desc;
 
-    ResponseEnum(int code,String desc){
+    /**
+     * 枚举的构造方法，用于初始化每个枚举常量对应的状态码和描述信息。
+     * 在定义每个枚举常量（如 `SUCCESS`、`ERROR` 等）时会调用该构造方法来传入相应的 `code` 和 `desc` 值，以此来构建完整的返回状态描述。
+     *
+     * @param code 状态码，用于在程序中区分不同的返回状态情况，不同的业务场景对应不同的状态码值，方便调用者根据状态码来判断具体的返回结果类型。
+     * @param desc 状态描述信息，通常用于向客户端展示具体的状态含义，便于客户端理解操作结果，一般是一些具有明确语义的字符串描述。
+     */
+    ResponseEnum(int code, String desc) {
         this.code = code;
         this.desc = desc;
     }
-}
+}

snailmall-user-service/src/main/java/com/njupt/swg/common/resp/ServerResponse.java

@@ -5,75 +5,167 @@ import com.fasterxml.jackson.databind.annotation.JsonSerialize;
 import lombok.AllArgsConstructor;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
-
 import java.io.Serializable;
 
 /**
+ * 该类 `ServerResponse` 是本项目的通用的返回封装类，用于将服务端的操作结果统一进行封装后返回给客户端。
+ * 它可以包含操作的状态码、提示消息以及具体的数据内容（泛型 `T` 表示具体的数据类型），并且通过使用一些 Jackson 相关的注解以及定义的多个静态方法，
+ * 方便创建不同状态（成功或失败）下的响应实例，同时实现了 `Serializable` 接口，使得该类的对象可以在网络传输、对象持久化等场景下进行序列化和反序列化操作。
+ *
  * @Author swg.
  * @Date 2018/12/31 20:11
  * @CONTACT 317758022@qq.com
  * @DESC 作为本项目的通用的返回封装类
  */
 @Getter
+// 使用 Lombok 的 `@Getter` 注解，会自动为类中的 `status`、`msg` 和 `data` 属性生成对应的 `get` 方法，方便外部获取这些属性的值，遵循了 Java 的封装原则，简化了代码编写。
 @JsonSerialize(include = JsonSerialize.Inclusion.NON_NULL)
+// 使用 Jackson 的 `@JsonSerialize` 注解，配置序列化时的行为，这里指定了只包含非 `null` 的属性进行序列化，
+// 也就是说在将 `ServerResponse` 对象转换为 JSON 格式（例如返回给客户端时），如果 `msg` 或者 `data` 等属性为 `null`，则不会包含在序列化后的 JSON 数据中，减少不必要的数据传输。
 public class ServerResponse<T> implements Serializable {
+    // 用于存储操作的状态码，通过与 `ResponseEnum` 枚举类中的状态码进行对比，可以判断操作是成功还是失败以及具体的状态类型，例如 `0` 表示成功等情况。
     private int status;
+    // 用于存储提示消息，一般是对操作结果的文字描述，比如操作成功时可以是 "操作成功"，失败时可以是具体的错误原因等，方便客户端理解服务端返回的结果含义。
     private String msg;
+    // 泛型属性，用于存储具体的业务数据内容，类型根据实际业务场景而定，可以是单个对象、对象列表或者其他复杂的数据结构等，比如查询用户信息时可以是 `User` 对象，查询用户列表时可以是 `List<User>` 类型的数据。
     private T data;
 
-    public ServerResponse(){}
+    public ServerResponse() {}
 
-    private ServerResponse(int status){
+    // 私有构造方法，接收一个状态码参数，用于创建只包含状态码的 `ServerResponse` 对象实例，通常在一些内部初始化或者特定场景下使用，
+    // 外部一般通过静态方法来创建完整的响应对象，该构造方法主要是为了代码复用和方便在类内部构建不同情况的对象。
+    private ServerResponse(int status) {
         this.status = status;
     }
-    private ServerResponse(int status,String msg){
+
+    // 私有构造方法，接收状态码和提示消息两个参数，用于创建包含状态码和提示消息的 `ServerResponse` 对象实例，
+    // 方便在已知操作状态码和对应的提示消息时构建响应对象，比如在出现错误时，传入错误状态码和具体的错误消息来创建相应的返回对象。
+    private ServerResponse(int status, String msg) {
         this.status = status;
         this.msg = msg;
     }
-    private ServerResponse(int status,T data){
+
+    // 私有构造方法，接收状态码和业务数据两个参数，用于创建包含状态码和具体数据的 `ServerResponse` 对象实例，
+    // 常用于操作成功且有具体数据需要返回给客户端的场景，例如查询操作成功获取到了数据，就可以通过传入成功状态码和查询到的数据来构建响应对象。
+    private ServerResponse(int status, T data) {
         this.status = status;
         this.data = data;
     }
-    private ServerResponse(int status,String msg,T data){
+
+    // 私有构造方法，接收状态码、提示消息和业务数据三个参数，用于创建包含完整信息（状态码、提示消息、业务数据）的 `ServerResponse` 对象实例，
+    // 适用于需要详细反馈操作结果，既包含状态、提示又有具体数据的各种复杂场景，比如部分更新操作，成功时可以传入成功状态码、更新成功的提示以及更新后的数据等情况来构建返回对象。
+    private ServerResponse(int status, String msg, T data) {
         this.status = status;
         this.msg = msg;
         this.data = data;
     }
 
+    /**
+     * 使用 `@JsonIgnore` 注解标记该方法，意味着在将 `ServerResponse` 对象进行序列化（如转换为 JSON 格式）时，这个方法不会被包含在内，
+     * 它用于判断当前响应对象是否表示操作成功，通过对比状态码和 `ResponseEnum.SUCCESS` 枚举常量对应的状态码（通常 `0` 表示成功）来返回布尔值结果，
+     * 方便外部代码快速判断操作是否成功，无需再去获取状态码后手动对比，提高了代码的可读性和便捷性。
+     *
+     * @return 返回 `true` 表示操作成功（状态码与成功状态码一致），返回 `false` 表示操作失败。
+     */
     @JsonIgnore
-    public boolean isSuccess(){
+    public boolean isSuccess() {
         return this.status == ResponseEnum.SUCCESS.getCode();
     }
 
     /**
-     * 成功的方法
+     * 以下是一系列静态方法，用于创建表示操作成功的 `ServerResponse` 对象实例，方便在不同的成功场景下快速构建合适的返回对象。
      */
-    public static <T>ServerResponse<T> createBySuccess(){
-        return new ServerResponse<>(ResponseEnum.SUCCESS.getCode(),ResponseEnum.SUCCESS.getDesc());
-    }
-    public static <T>ServerResponse<T> createBySuccessMessage(String message){
-        return new ServerResponse<>(ResponseEnum.SUCCESS.getCode(),message);
-    }
-    public static <T>ServerResponse<T> createBySuccess(T data){
-        return new ServerResponse<>(ResponseEnum.SUCCESS.getCode(),data);
-    }
-    public static <T>ServerResponse<T> createBySuccess(String message,T data){
-        return new ServerResponse<>(ResponseEnum.SUCCESS.getCode(),message,data);
+
+    /**
+     * 创建一个表示操作成功且只包含默认成功提示消息（从 `ResponseEnum.SUCCESS.getDesc()` 获取）的 `ServerResponse` 对象实例，
+     * 适用于不需要额外提供详细提示消息，仅告知客户端操作成功的简单场景，例如简单的查询操作成功，无其他特殊说明时可以使用该方法创建返回对象。
+     *
+     * @param <T> 泛型类型参数，由调用者指定具体的数据类型，使得该方法可以灵活适应不同业务数据类型的返回情况。
+     * @return 返回创建好的 `ServerResponse` 对象实例，状态码为成功状态码，提示消息为默认的成功描述信息。
+     */
+    public static <T> ServerResponse<T> createBySuccess() {
+        return new ServerResponse<>(ResponseEnum.SUCCESS.getCode(), ResponseEnum.SUCCESS.getDesc());
     }
 
     /**
-     * 失败的方法
+     * 创建一个表示操作成功且包含自定义提示消息的 `ServerResponse` 对象实例，
+     * 通过传入自定义的 `message` 参数来指定具体的提示消息内容，适用于需要向客户端传达更详细的成功相关信息的场景，
+     * 比如新增数据成功后，可以传入 "数据新增成功，已保存到数据库" 这样的提示消息，让客户端更清楚具体的操作结果情况。
+     *
+     * @param <T> 泛型类型参数，由调用者指定具体的数据类型，与其他静态方法一样，可灵活适配不同业务数据返回情况。
+     * @param message 自定义的提示消息内容，用于替换默认的成功提示消息，更精准地告知客户端操作成功的相关细节。
+     * @return 返回创建好的 `ServerResponse` 对象实例，状态码为成功状态码，提示消息为传入的自定义消息。
      */
-    public static <T>ServerResponse<T> createByError(){
-        return new ServerResponse<>(ResponseEnum.ERROR.getCode(),ResponseEnum.ERROR.getDesc());
+    public static <T> ServerResponse<T> createBySuccessMessage(String message) {
+        return new ServerResponse<>(ResponseEnum.SUCCESS.getCode(), message);
     }
-    public static <T>ServerResponse<T> createByErrorMessage(String msg){
-        return new ServerResponse<>(ResponseEnum.ERROR.getCode(),msg);
+
+    /**
+     * 创建一个表示操作成功且包含具体业务数据的 `ServerResponse` 对象实例，
+     * 通过传入具体的数据对象 `data`（类型为泛型 `T`）来将业务数据封装到返回对象中，适用于查询等操作成功并获取到具体数据需要返回给客户端的场景，
+     * 例如查询用户信息成功后，将查询到的 `User` 对象作为参数传入，构建包含用户信息数据的返回对象传递给客户端。
+     *
+     * @param <T> 泛型类型参数，由调用者指定具体的数据类型，对应要返回的业务数据的实际类型。
+     * @param data 具体的业务数据对象，将被封装到 `ServerResponse` 对象的 `data` 属性中，作为操作成功的结果数据返回给客户端。
+     * @return 返回创建好的 `ServerResponse` 对象实例，状态码为成功状态码，数据为传入的具体业务数据。
+     */
+    public static <T> ServerResponse<T> createBySuccess(T data) {
+        return new ServerResponse<>(ResponseEnum.SUCCESS.getCode(), data);
     }
-    public static <T>ServerResponse<T> createByErrorCodeMessage(int code,String msg){
-        return new ServerResponse<>(code,msg);
+
+    /**
+     * 创建一个表示操作成功且包含自定义提示消息和具体业务数据的 `ServerResponse` 对象实例，
+     * 同时传入 `message` 和 `data` 参数，分别用于指定详细的提示消息和具体的业务数据内容，适用于既需要告知客户端操作成功的详细情况，又有具体数据需要返回的复杂场景，
+     * 比如更新用户信息成功后，可以传入 "用户信息更新成功" 这样的提示消息以及更新后的 `User` 对象数据，构建完整的返回对象反馈给客户端。
+     *
+     * @param <T> 泛型类型参数，由调用者指定具体的数据类型，对应实际业务数据的类型以及返回对象中 `data` 属性的类型。
+     * @param message 自定义的提示消息内容，用于丰富操作成功的提示信息，让客户端更全面地了解操作结果情况。
+     * @param data 具体的业务数据对象，将被封装到 `ServerResponse` 对象的 `data` 属性中，作为操作成功的业务数据结果返回给客户端。
+     * @return 返回创建好的 `ServerResponse` 对象实例，状态码为成功状态码，包含传入的自定义提示消息和具体业务数据。
+     */
+    public static <T> ServerResponse<T> createBySuccess(String message, T data) {
+        return new ServerResponse<>(ResponseEnum.SUCCESS.getCode(), message, data);
     }
 
+    /**
+     * 以下是一系列静态方法，用于创建表示操作失败的 `ServerResponse` 对象实例，方便在不同的失败场景下快速构建合适的返回对象，向客户端反馈操作失败的情况及原因。
+     */
 
+    /**
+     * 创建一个表示操作失败且只包含默认错误提示消息（从 `ResponseEnum.ERROR.getDesc()` 获取）的 `ServerResponse` 对象实例，
+     * 适用于一般性的操作失败情况，不需要详细说明具体错误原因，仅告知客户端操作失败时可以使用该方法创建返回对象，例如在出现未预期的异常等通用错误场景下使用。
+     *
+     * @param <T> 泛型类型参数，由调用者指定具体的数据类型，虽然操作失败时可能不一定有具体业务数据返回，但保持与其他方法一致的泛型定义，以保证方法通用性和灵活性。
+     * @return 返回创建好的 `ServerResponse` 对象实例，状态码为错误状态码，提示消息为默认的错误描述信息。
+     */
+    public static <T> ServerResponse<T> createByError() {
+        return new ServerResponse<>(ResponseEnum.ERROR.getCode(), ResponseEnum.ERROR.getDesc());
+    }
 
-}
+    /**
+     * 创建一个表示操作失败且包含自定义错误提示消息的 `ServerResponse` 对象实例，
+     * 通过传入自定义的 `msg` 参数来指定具体的错误消息内容，适用于需要向客户端明确传达具体失败原因的场景，
+     * 比如参数校验不通过时，可以传入 "参数不符合要求，请检查输入参数" 这样的提示消息，让客户端清楚操作失败的具体缘由。
+     *
+     * @param <T> 泛型类型参数，由调用者指定具体的数据类型，同样是为了保证方法通用性，适配不同业务场景下的返回情况。
+     * @param msg 自定义的错误提示消息内容，用于替换默认的错误提示消息，更精准地告知客户端操作失败的原因所在。
+     * @return 返回创建好的 `ServerResponse` 对象实例，状态码为错误状态码，提示消息为传入的自定义消息。
+     */
+    public static <T> ServerResponse<T> createByErrorMessage(String msg) {
+        return new ServerResponse<>(ResponseEnum.ERROR.getCode(), msg);
+    }
+
+    /**
+     * 创建一个表示操作失败且包含自定义状态码和错误提示消息的 `ServerResponse` 对象实例，
+     * 通过传入 `code` 和 `msg` 参数分别指定具体的状态码和错误提示消息内容，适用于需要更精细地表示不同类型的失败情况，
+     * 例如根据不同业务模块或者不同错误类型设置不同的状态码，并搭配相应的错误消息，让客户端能更准确地区分和理解操作失败的具体情况。
+     *
+     * @param <T> 泛型类型参数，由调用者指定具体的数据类型，保持方法通用性，可用于各种需要自定义状态码和消息返回的失败场景。
+     * @param code 自定义的状态码，用于更细致地标识不同的失败情况，与项目中定义的各种状态码规范相匹配，方便客户端根据状态码进行针对性处理。
+     * @param msg 自定义的错误提示消息内容，详细说明操作失败的原因，辅助客户端理解具体的问题所在。
+     * @return 返回创建好的 `ServerResponse` 对象实例，状态码为传入的自定义状态码，提示消息为传入的自定义消息。
+     */
+    public static <T> ServerResponse<T> createByErrorCodeMessage(int code, String msg) {
+        return new ServerResponse<>(code, msg);
+    }
+}

snailmall-user-service/src/main/java/com/njupt/swg/common/utils/CookieUtil.java

@@ -2,47 +2,63 @@ package com.njupt.swg.common.utils;
 
 import lombok.extern.slf4j.Slf4j;
 import org.apache.commons.lang3.StringUtils;
-
 import javax.servlet.http.Cookie;
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
 /**
- * cookie读写
+ * 该类 `CookieUtil` 主要用于处理与 `Cookie` 相关的操作，包括在用户登录时写入 `Cookie`、读取登录相关的 `Cookie` 值以及在用户注销时删除对应的 `Cookie`。
+ * 通过设置 `Cookie` 的各种属性（如域名、路径、有效期等）来控制其作用范围和生命周期，同时借助日志记录相关操作信息，方便排查问题以及了解 `Cookie` 的使用情况。
+ *
+ * @Slf4j 注解用于生成一个名为 `log` 的日志记录对象，便于在类中记录操作日志，尤其是在处理 `Cookie` 过程中方便查看关键信息，比如 `Cookie` 的名称、值以及操作结果等情况。
  */
 @Slf4j
 public class CookieUtil {
+    // 定义了一个静态的常量字符串，表示 `Cookie` 所属的域名，用于设置 `Cookie` 的作用域名范围，这里固定为 "oursnail.cn"，意味着只有在该域名下的页面请求才会携带和使用此 `Cookie`。
     private final static String COOKIE_DOMAIN = "oursnail.cn";
+    // 定义了一个静态的常量字符串，用于表示存储登录相关信息的 `Cookie` 的名称，后续通过这个名称来识别和操作特定的登录 `Cookie`，固定为 "snailmall_login_token"。
     private final static String COOKIE_NAME = "snailmall_login_token";
 
-
     /**
-     * 登陆的时候写入cookie
-     * @param response
-     * @param token
+     * 该方法用于在用户登录时向客户端写入登录相关的 `Cookie`，将登录凭证（以 `token` 的形式）存储到 `Cookie` 中并发送给客户端浏览器保存。
+     *
+     * @param response 作为 `HttpServletResponse` 类型的参数，用于向客户端发送响应信息，包括设置和添加 `Cookie` 到响应头中，使得客户端浏览器能够接收到并保存该 `Cookie`。
+     * @param token 表示登录的凭证信息（通常是经过加密等处理后的字符串），会被存储到名为 `COOKIE_NAME` 的 `Cookie` 中，作为后续验证用户登录状态等用途的标识。
      */
-    public static void writeLoginToken(HttpServletResponse response,String token){
-        Cookie ck = new Cookie(COOKIE_NAME,token);
+    public static void writeLoginToken(HttpServletResponse response, String token) {
+        // 创建一个新的 `Cookie` 对象，传入 `COOKIE_NAME` 作为 `Cookie` 的名称，`token` 作为 `Cookie` 的值，以此来构建用于存储登录凭证的 `Cookie`。
+        Cookie ck = new Cookie(COOKIE_NAME, token);
+        // 设置 `Cookie` 的域名属性，使其作用范围限定在指定的域名 "oursnail.cn" 下，只有访问该域名下的页面时，浏览器才会自动携带这个 `Cookie` 发送请求。
         ck.setDomain(COOKIE_DOMAIN);
-        ck.setPath("/");//设值在根目录
-        ck.setHttpOnly(true);//不允许通过脚本访问cookie,避免脚本攻击
-        ck.setMaxAge(60*60*24*365);//一年，-1表示永久,单位是秒，maxage不设置的话，cookie就不会写入硬盘，只会写在内存，只在当前页面有效
-        log.info("write cookieName:{},cookieValue:{}",ck.getName(),ck.getValue());
+        // 设置 `Cookie` 的路径属性为根目录 "/"，意味着在该域名下的所有页面请求都会携带这个 `Cookie`，如果设置为其他具体路径，则只有访问该路径及其子路径下的页面时才会携带。
+        ck.setPath("/");
+        // 设置 `Cookie` 的 `HttpOnly` 属性为 `true`，这是一种安全机制，使得客户端脚本（如 JavaScript）无法访问该 `Cookie`，可以有效避免跨站脚本攻击（XSS）等安全问题，提高系统的安全性。
+        ck.setHttpOnly(true);
+        // 设置 `Cookie` 的最大存活时间，这里设置为 `60 * 60 * 24 * 365` 秒，即一年，表示该 `Cookie` 在客户端浏览器保存的有效期为一年，超过这个时间后，浏览器会自动删除该 `Cookie`。
+        // 如果设置为 `-1`，则表示永久有效（不过不同浏览器对于永久有效的处理方式可能略有差异），若不设置该属性（`maxAge` 为默认值），则 `Cookie` 不会写入硬盘，只会保存在内存中，仅在当前页面会话有效。
+        ck.setMaxAge(60 * 60 * 24 * 365);
+        log.info("write cookieName:{},cookieValue:{}", ck.getName(), ck.getValue());
+        // 将构建好并设置好属性的 `Cookie` 添加到 `HttpServletResponse` 的响应头中，发送给客户端浏览器，使得浏览器能够保存这个 `Cookie` 用于后续请求携带。
         response.addCookie(ck);
     }
 
     /**
-     * 读取登陆的cookie
-     * @param request
-     * @return
+     * 该方法用于从客户端的请求中读取登录相关的 `Cookie` 值，通过遍历请求中携带的所有 `Cookie`，查找名称为 `COOKIE_NAME` 的 `Cookie`，并返回其值。
+     * 如果找到了对应的 `Cookie`，则返回其存储的登录凭证（`token`）值，若没有找到则返回 `null`，表示未获取到登录相关的 `Cookie`。
+     *
+     * @param request 作为 `HttpServletRequest` 类型的参数，用于获取客户端发送过来的请求信息，包括请求中携带的 `Cookie` 数据，通过它可以获取到所有的 `Cookie` 数组进行遍历查找。
+     * @return 返回 `String` 类型的结果，如果找到了名称为 `COOKIE_NAME` 的 `Cookie`，则返回其对应的值（即登录凭证 `token`），若未找到则返回 `null`。
      */
-    public static String readLoginToken(HttpServletRequest request){
+    public static String readLoginToken(HttpServletRequest request) {
+        // 通过 `HttpServletRequest` 的 `getCookies` 方法获取客户端发送过来的所有 `Cookie`，以数组形式返回，如果没有 `Cookie` 则返回 `null`。
         Cookie[] cks = request.getCookies();
-        if(cks != null){
-            for(Cookie ck:cks){
-                log.info("cookieName:{},cookieBValue:{}",ck.getName(),ck.getValue());
-                if(StringUtils.equals(ck.getName(),COOKIE_NAME)){
-                    log.info("return cookieName:{},cookieBValue:{}",ck.getName(),ck.getValue());
+        if (cks!= null) {
+            for (Cookie ck : cks) {
+                log.info("cookieName:{},cookieBValue:{}", ck.getName(), ck.getValue());
+                // 使用 `StringUtils` 的 `equals` 方法（该方法可以避免空指针异常等情况，进行安全的字符串比较）比较当前遍历到的 `Cookie` 的名称与预定义的 `COOKIE_NAME` 是否相等，
+                // 如果相等，则说明找到了存储登录凭证的 `Cookie`，返回其值（即登录 `token`）。
+                if (StringUtils.equals(ck.getName(), COOKIE_NAME)) {
+                    log.info("return cookieName:{},cookieBValue:{}", ck.getName(), ck.getValue());
                     return ck.getValue();
                 }
             }
@@ -51,24 +67,29 @@ public class CookieUtil {
     }
 
     /**
-     * 注销的时候进行删除
-     * @param request
-     * @param response
+     * 该方法用于在用户注销时，从客户端删除对应的登录相关的 `Cookie`，通过遍历请求中携带的所有 `Cookie`，找到名称为 `COOKIE_NAME` 的 `Cookie`，
+     * 然后将其有效期设置为 `0`，并重新添加到响应中发送给客户端，通知客户端删除该 `Cookie`，以此实现注销时清除登录凭证的功能。
+     *
+     * @param request 作为 `HttpServletRequest` 类型的参数，用于获取客户端当前发送过来的请求信息，从中获取携带的 `Cookie` 数组，以便查找要删除的登录 `Cookie`。
+     * @param response 作为 `HttpServletResponse` 类型的参数，用于向客户端发送响应信息，将设置好有效期为 `0` 的 `Cookie` 重新添加到响应头中，通知客户端删除对应的 `Cookie`。
      */
-    public static void delLoginToken(HttpServletRequest request,HttpServletResponse response){
+    public static void delLoginToken(HttpServletRequest request, HttpServletResponse response) {
         Cookie[] cks = request.getCookies();
-        if(cks != null){
-            for(Cookie ck:cks) {
-                if(StringUtils.equals(ck.getName(),COOKIE_NAME)){
+        if (cks!= null) {
+            for (Cookie ck : cks) {
+                if (StringUtils.equals(ck.getName(), COOKIE_NAME)) {
+                    // 找到名称为 `COOKIE_NAME` 的 `Cookie` 后，先设置其域名属性为预定义的 `COOKIE_DOMAIN`，确保域名范围的一致性，与写入 `Cookie` 时的设置相匹配。
                     ck.setDomain(COOKIE_DOMAIN);
+                    // 设置 `Cookie` 的路径属性为根目录 "/"，同样与写入 `Cookie` 时的路径设置保持一致，确保能够正确地删除对应的 `Cookie`。
                     ck.setPath("/");
-                    ck.setMaxAge(0);//0表示消除此cookie
-                    log.info("del cookieName:{},cookieBValue:{}",ck.getName(),ck.getValue());
+                    // 设置 `Cookie` 的最大存活时间为 `0`，这表示通知客户端浏览器立即删除该 `Cookie`，使其失效，不再携带和使用该 `Cookie` 进行后续请求。
+                    ck.setMaxAge(0);
+                    log.info("del cookieName:{},cookieBValue:{}", ck.getName(), ck.getValue());
+                    // 将设置好属性的 `Cookie`（有效期为 `0`）重新添加到 `HttpServletResponse` 的响应头中，发送给客户端，触发客户端执行删除该 `Cookie` 的操作。
                     response.addCookie(ck);
                     return;
                 }
             }
         }
     }
-
-}
+}

snailmall-user-service/src/main/java/com/njupt/swg/common/utils/DateTimeUtil.java

@@ -4,65 +4,116 @@ import org.apache.commons.lang3.StringUtils;
 import org.joda.time.DateTime;
 import org.joda.time.format.DateTimeFormat;
 import org.joda.time.format.DateTimeFormatter;
-
 import java.text.ParseException;
 import java.text.SimpleDateFormat;
 import java.util.Date;
 
 /**
+ * 该类 `DateTimeUtil` 是一个时间转换的工具类，主要用于处理日期（`Date`）与字符串（`String`）之间的相互转换，以及将日期转换为时间戳的操作。
+ * 它借助了 `Joda-Time` 库来进行日期相关的格式化和解析工作，同时提供了不同形式的方法重载，方便在不同场景下按照指定格式或者默认格式进行时间相关的转换操作，
+ * 并在代码中对一些可能出现的空值情况做了相应处理，提高了工具类的健壮性。另外还包含了一个简单的 `main` 方法用于测试时间转换功能（虽然这种测试方式相对简单，在实际项目中可能会有更完善的单元测试等手段）。
+ *
  * @DESC 时间转换的工具类
  */
 public class DateTimeUtil {
-    //joda-time
-
-    //str->Date
-    //Date->str
+    // 使用 `Joda-Time` 库来处理时间相关操作，以下定义的是一个常量字符串，表示时间格式的标准模板，用于在没有显式指定格式时作为默认的日期时间字符串格式，方便统一格式化规则。
     public static final String STANDARD_FORMAT = "yyyy-MM-dd HH:mm:ss";
 
-
-
-    public static Date strToDate(String dateTimeStr, String formatStr){
+    /**
+     * 将指定格式的日期时间字符串转换为 `Date` 类型的方法，通过传入日期时间字符串和对应的格式字符串，利用 `Joda-Time` 库进行解析并转换为 `Date` 对象。
+     *
+     * @param dateTimeStr 表示要转换的日期时间字符串，例如 "2024-12-17 10:30:00"，其格式需要与传入的 `formatStr` 参数指定的格式一致，否则解析会失败。
+     * @param formatStr 用于指定 `dateTimeStr` 的格式，例如 "yyyy-MM-dd HH:mm:ss" 等常见的日期时间格式模板，通过这个格式来解析输入的字符串，将其转换为对应的 `Date` 对象。
+     * @return 返回解析后的 `Date` 对象，如果解析成功则返回对应的日期时间对应的 `Date` 实例，若解析失败（比如字符串格式不符合要求等情况）会抛出异常（由 `Joda-Time` 库内部处理机制决定）。
+     */
+    public static Date strToDate(String dateTimeStr, String formatStr) {
+        // 根据传入的格式字符串创建 `DateTimeFormatter` 对象，它用于定义如何解析日期时间字符串，按照指定的格式模板来解析输入的字符串内容。
         DateTimeFormatter dateTimeFormatter = DateTimeFormat.forPattern(formatStr);
+        // 使用创建好的 `DateTimeFormatter` 对输入的日期时间字符串进行解析，得到 `DateTime` 对象，`DateTime` 是 `Joda-Time` 库中用于表示日期时间的核心类，提供了丰富的日期时间操作方法。
         DateTime dateTime = dateTimeFormatter.parseDateTime(dateTimeStr);
+        // 将 `DateTime` 对象转换为 `Java` 标准库中的 `Date` 对象并返回，以便在基于 `Java` 标准库的其他代码中使用该日期时间数据。
         return dateTime.toDate();
     }
 
-    public static String dateToStr(Date date,String formatStr){
-        if(date == null){
+    /**
+     * 将 `Date` 类型的日期时间对象转换为指定格式的字符串的方法，先判断传入的 `Date` 对象是否为 `null`，如果是则返回空字符串，避免空指针异常等问题，
+     * 若不为 `null`，则利用 `Joda-Time` 库将其转换为对应的字符串表示形式，按照传入的格式字符串进行格式化输出。
+     *
+     * @param date 要转换的 `Date` 类型的日期时间对象，若为 `null`，则直接返回空字符串，若不为 `null`，则进行格式转换操作。
+     * @param formatStr 用于指定转换后的字符串的格式，例如 "yyyy-MM-dd HH:mm:ss" 等，按照该格式将 `Date` 对象转换为相应格式的字符串返回。
+     * @return 返回格式化后的日期时间字符串，如果传入的 `Date` 对象为 `null`，则返回 `StringUtils.EMPTY`（即空字符串），若不为 `null`，则返回按照指定格式转换后的字符串内容。
+     */
+    public static String dateToStr(Date date, String formatStr) {
+        if (date == null) {
             return StringUtils.EMPTY;
         }
+        // 根据传入的 `Date` 对象创建 `DateTime` 对象，以便使用 `Joda-Time` 库的功能进行后续的格式化操作，`DateTime` 类提供了方便的方法将日期时间转换为不同格式的字符串。
         DateTime dateTime = new DateTime(date);
         return dateTime.toString(formatStr);
     }
 
-    //固定好格式
-    public static Date strToDate(String dateTimeStr){
+    /**
+     * 将日期时间字符串按照默认的标准格式（`STANDARD_FORMAT`，即 "yyyy-MM-dd HH:mm:ss"）转换为 `Date` 类型的方法，简化了调用过程，
+     * 当日期时间字符串的格式符合默认标准格式时，可以直接使用该方法进行转换，无需再传入格式字符串参数。
+     *
+     * @param dateTimeStr 要转换的日期时间字符串，其格式需要符合默认的 "yyyy-MM-dd HH:mm:ss" 格式，否则解析会失败。
+     * @return 返回解析后的 `Date` 对象，如果解析成功则返回对应的日期时间对应的 `Date` 实例，若解析失败（比如字符串格式不符合要求等情况）会抛出异常（由 `Joda-Time` 库内部处理机制决定）。
+     */
+    public static Date strToDate(String dateTimeStr) {
+        // 根据默认的标准格式创建 `DateTimeFormatter` 对象，用于解析输入的日期时间字符串。
         DateTimeFormatter dateTimeFormatter = DateTimeFormat.forPattern(STANDARD_FORMAT);
+        // 使用创建好的 `DateTimeFormatter` 对输入的日期时间字符串进行解析，得到 `DateTime` 对象。
         DateTime dateTime = dateTimeFormatter.parseDateTime(dateTimeStr);
+        // 将 `DateTime` 对象转换为 `Java` 标准库中的 `Date` 对象并返回。
         return dateTime.toDate();
     }
 
-    public static String dateToStr(Date date){
-        if(date == null){
+    /**
+     * 将 `Date` 类型的日期时间对象按照默认的标准格式（`STANDARD_FORMAT`，即 "yyyy-MM-dd HH:mm:ss"）转换为字符串的方法，同样简化了调用过程，
+     * 当需要将 `Date` 对象转换为符合默认格式的字符串时，可以直接使用该方法，无需再传入格式字符串参数，并且对传入的 `Date` 对象是否为 `null` 做了判断处理。
+     *
+     * @param date 要转换的 `Date` 类型的日期时间对象，若为 `null`，则直接返回空字符串，若不为 `null`，则进行格式转换操作。
+     * @return 返回格式化后的日期时间字符串，如果传入的 `Date` 对象为 `null`，则返回 `StringUtils.EMPTY`（即空字符串），若不为 `null`，则返回按照默认格式 "yyyy-MM-dd HH:mm:ss" 转换后的字符串内容。
+     */
+    public static String dateToStr(Date date) {
+        if (date == null) {
             return StringUtils.EMPTY;
         }
+        // 根据传入的 `Date` 对象创建 `DateTime` 对象，以便使用 `Joda-Time` 库的功能将其转换为默认格式的字符串。
         DateTime dateTime = new DateTime(date);
         return dateTime.toString(STANDARD_FORMAT);
     }
 
-    //Date -> 时间戳
+    /**
+     * 将 `Date` 类型的日期时间对象转换为时间戳（从1970年1月1日00:00:00 UTC到指定日期时间的毫秒数）的方法，先判断传入的 `Date` 对象是否为 `null`，
+     * 如果是则返回 `null`，若不为 `null`，则通过 `Java` 标准库中的 `SimpleDateFormat` 按照指定格式（同样是默认的 "yyyy-MM-dd HH:mm:ss"）将 `Date` 对象转换为字符串，
+     * 再解析该字符串为 `Date` 对象（这里解析操作看似重复，但目的是为了获取对应格式下准确的时间戳，`SimpleDateFormat` 的 `parse` 方法会根据格式解析并返回对应时间的 `Date` 对象），
+     * 最后获取其时间戳并返回。不过此方法在解析字符串为 `Date` 对象时可能会抛出 `ParseException` 异常，调用者需要进行相应的异常处理。
+     *
+     * @param date 要转换为时间戳的 `Date` 类型的日期时间对象，若为 `null`，则返回 `null`，若不为 `null`，则进行时间戳转换操作。
+     * @return 返回对应的时间戳（以毫秒为单位的长整型数值），如果传入的 `Date` 对象为 `null`，则返回 `null`，若不为 `null`，则返回从1970年1月1日00:00:00 UTC到指定日期时间的毫秒数。
+     * @throws ParseException 该方法在使用 `SimpleDateFormat` 解析字符串为 `Date` 对象过程中，如果字符串格式不符合要求等情况可能会抛出此异常，需要调用者进行捕获处理。
+     */
     public static Long dateToChuo(Date date) throws ParseException {
-        if(date == null){
+        if (date == null) {
             return null;
         }
-        SimpleDateFormat format =   new SimpleDateFormat( "yyyy-MM-dd HH:mm:ss" );
+        SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
         return format.parse(String.valueOf(date)).getTime();
     }
 
+    /**
+     * `main` 方法是 `Java` 程序的入口点，在这里主要用于简单测试 `dateToChuo` 方法的功能，通过创建 `SimpleDateFormat` 对象按照指定格式解析一个硬编码的日期时间字符串为 `Date` 对象，
+     * 然后调用 `dateToChuo` 方法（虽然这里没有捕获异常，实际使用中应该捕获可能抛出的 `ParseException` 异常）获取时间戳，并打印输出。
+     * 这只是一个简单的测试示例，在实际项目中通常会使用更专业的单元测试框架（如 `JUnit`、`TestNG` 等）来进行更全面、严谨的功能测试。
+     *
+     * @param args 命令行参数数组，在这里并没有实际使用到，一般用于在命令行启动程序时传入外部参数，改变程序的运行行为等情况。
+     * @throws ParseException 由于 `main` 方法中调用了 `dateToChuo` 方法，该方法可能抛出 `ParseException` 异常，所以这里需要声明抛出该异常，不过实际中应该进行异常捕获处理以保证程序的稳定性。
+     */
     public static void main(String[] args) throws ParseException {
-        SimpleDateFormat format =   new SimpleDateFormat( "yyyy-MM-dd HH:mm:ss" );
-        String time="1970-01-06 11:45:55";
+        SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
+        String time = "1970-01-06 11:45:55";
         Date date = format.parse(time);
-        System.out.print("Format To times:"+date.getTime());
+        System.out.print("Format To times:" + date.getTime());
     }
-}
+}