111

snailmall-category-service/src/main/java/com/njupt/swg/SnailmallCategoryServiceApplication.java

@@ -4,13 +4,28 @@ import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
 
+/**
+ * 该类SnailmallCategoryServiceApplication是Spring Boot应用的启动类，它是整个应用程序的入口点。
+ * 通过运行这个类的main方法，将会启动Spring Boot应用，加载相关的配置、初始化各种组件，并启动内置的Web服务器（如Tomcat等，根据配置而定），开始对外提供服务。
+ * 它使用了Spring Boot相关的注解来简化配置以及集成Spring Cloud相关功能。
+ */
 @SpringBootApplication
+// 这是一个组合注解，相当于同时使用了@Configuration、@EnableAutoConfiguration和@ComponentScan三个注解。
+// @Configuration表示该类是一个配置类，可用于定义一些Spring的Bean或者配置相关的属性等；
+// @EnableAutoConfiguration用于启用Spring Boot的自动配置功能，会根据项目依赖自动配置各种组件，比如数据源、Web相关配置等；
+// @ComponentScan用于指定Spring扫描组件（如带有@Component、@Service、@Controller等注解的类）的基础包路径，默认会扫描当前类所在的包及其子包下的组件。
 @EnableDiscoveryClient
+// 该注解用于开启服务发现客户端功能，使得应用可以注册到服务注册中心（比如Eureka、Consul等），并且可以从注册中心发现其他服务，方便实现微服务之间的调用和协作。
 public class SnailmallCategoryServiceApplication {
 
+    /**
+     * main方法是Java应用程序的入口方法，在这里通过调用SpringApplication的run方法来启动Spring Boot应用。
+     * 传入当前启动类的Class对象（SnailmallCategoryServiceApplication.class）以及命令行参数（args），
+     * Spring Boot会根据配置和依赖进行一系列的初始化和启动操作，最终启动应用并使其处于可运行状态，对外提供服务。
+     * @param args 命令行参数，可用于在启动应用时传入一些自定义的配置信息等，比如指定应用运行的端口号、配置文件路径等（具体取决于应用的实现和配置）。
+     */
     public static void main(String[] args) {
         SpringApplication.run(SnailmallCategoryServiceApplication.class, args);
     }
 
-}
-
+}

snailmall-category-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,41 @@ import org.springframework.web.bind.annotation.ExceptionHandler;
 import org.springframework.web.bind.annotation.ResponseBody;
 
 /**
+ * 该类ExceptionHandlerAdvice用于进行全局异常处理，它可以捕获不同类型的异常，并返回相应的错误响应信息给客户端。
  * @Author swg.
  * @Date 2019/1/1 13:21
  * @CONTACT 317758022@qq.com
  * @DESC 全局异常处理
  */
 @ControllerAdvice
+// 表示该类中处理异常的方法返回的结果会直接作为响应体返回给客户端，而不是进行视图解析等操作。
 @ResponseBody
+// 使用Slf4j注解，方便进行日志记录，简化日志输出的代码编写。
 @Slf4j
 public class ExceptionHandlerAdvice {
+    /**
+     * 该方法用于处理所有类型为Exception（即最通用的异常类型）的异常情况。
+     * 当捕获到这类异常时，会先将异常信息记录到日志中（方便后续排查问题），然后返回一个表示服务器内部错误的响应信息给客户端，
+     * 告知客户端系统出现异常，让其稍后再试。响应中使用了在Constants类中定义的表示服务器内部错误的状态码。
+     * @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, "系统异常，请稍后再试");
     }
 
+    /**
+     * 该方法用于专门处理SnailmallException类型的异常情况。
+     * 同样会先将异常信息记录到日志中，然后返回一个包含该异常对象中定义的异常状态码以及异常消息的响应信息给客户端。
+     * 这样针对特定业务的异常可以更精准地反馈给客户端相应的错误情况。
+     * @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-category-service/src/main/java/com/njupt/swg/common/exception/SnailmallException.java

@@ -4,22 +4,38 @@ import com.njupt.swg.common.resp.ResponseEnum;
 import lombok.Getter;
 
 /**
+ * 该类SnailmallException继承自RuntimeException，用于定义特定于业务（可能是名为Snailmall相关业务）的异常情况。
+ * 通过继承RuntimeException，可以在代码中方便地抛出这种自定义异常，并且无需在方法声明中显式地抛出（因为是运行时异常）。
  * @Author swg.
  * @Date 2019/1/1 13:18
  * @CONTACT 317758022@qq.com
  * @DESC
  */
 @Getter
-public class SnailmallException extends RuntimeException{
+// 使用lombok的@Getter注解，自动生成获取exceptionStatus属性值的get方法，方便外部获取该异常状态码。
+public class SnailmallException extends RuntimeException {
+    // 定义一个表示异常状态码的属性，初始值设置为从ResponseEnum.ERROR中获取的状态码，通常用于表示默认的错误状态码情况。
     private int exceptionStatus = ResponseEnum.ERROR.getCode();
 
-    public SnailmallException(String msg){
+    /**
+     * 构造方法，接收一个字符串类型的参数msg，用于创建一个SnailmallException实例。
+     * 调用父类（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 异常消息内容
+     */
+    public SnailmallException(int code, String msg) {
         super(msg);
         exceptionStatus = code;
     }
-
-}
+}

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

@@ -3,23 +3,36 @@ 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属性生成对应的获取方法，方便外部获取这些属性值。
 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-category-service/src/main/java/com/njupt/swg/common/resp/ServerResponse.java

@@ -4,75 +4,168 @@ import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.databind.annotation.JsonSerialize;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
-
 import java.io.Serializable;
 
 /**
+ * 该类ServerResponse是本项目的通用的返回封装类，用于统一封装服务端返回给客户端的响应信息，
+ * 包含了状态码、提示消息以及具体的数据内容（数据部分可以是各种类型，通过泛型<T>来表示其通用性），方便客户端解析和处理返回结果。
  * @Author swg.
  * @Date 2018/12/31 20:11
  * @CONTACT 317758022@qq.com
  * @DESC 作为本项目的通用的返回封装类
  */
 @Getter
+// 使用lombok的@Getter注解，自动生成获取status、msg、data属性值的方法，方便外部获取这些成员变量的值。
 @JsonSerialize(include = JsonSerialize.Inclusion.NON_NULL)
+// 通过该注解配置Jackson序列化时的行为，这里表示只序列化非空的属性，避免返回包含大量空值的JSON数据给客户端，节省网络传输和客户端解析成本。
 public class ServerResponse<T> implements Serializable {
+    // 表示响应的状态码，用于客户端判断请求的处理结果状态，通常会对应一些预定义的状态码值，比如成功、失败等情况。
     private int status;
+    // 表示响应的提示消息，用于向客户端传达一些关于请求处理结果的文字描述信息，便于客户端展示给用户知晓具体情况。
     private String msg;
+    // 泛型成员变量，用于承载具体的业务数据，其类型根据实际业务场景而定，可以是对象、集合等各种数据结构类型。
     private T data;
 
-    public ServerResponse(){}
+    public ServerResponse() {
+    }
 
-    public ServerResponse(int status){
+    /**
+     * 构造方法，只接收状态码参数，用于创建一个ServerResponse实例，此时提示消息和数据部分为空，
+     * 可用于只需要传递状态码来表示一种简单响应情况的场景，比如某些只关注操作是否成功的情况（成功或失败状态码）。
+     * @param status 响应状态码
+     */
+    public ServerResponse(int status) {
         this.status = status;
     }
-    public ServerResponse(int status,String msg){
+
+    /**
+     * 构造方法，接收状态码和提示消息参数，用于创建一个带有指定状态码和提示消息的ServerResponse实例，
+     * 数据部分为空，适用于需要向客户端传达具体的状态信息以及对应的文字描述情况，比如操作失败时告知具体失败原因等场景。
+     * @param status 响应状态码
+     * @param msg 响应提示消息
+     */
+    public ServerResponse(int status, String msg) {
         this.status = status;
         this.msg = msg;
     }
-    public ServerResponse(int status,T data){
+
+    /**
+     * 构造方法，接收状态码和数据参数，用于创建一个带有指定状态码和具体业务数据的ServerResponse实例，
+     * 提示消息为空，适用于操作成功且需要返回具体业务数据给客户端的场景，比如查询操作成功后返回查询到的数据集合等情况。
+     * @param status 响应状态码
+     * @param data 具体业务数据
+     */
+    public ServerResponse(int status, T data) {
         this.status = status;
         this.data = data;
     }
-    public ServerResponse(int status,String msg,T data){
+
+    /**
+     * 构造方法，接收状态码、提示消息和数据参数，用于创建一个完整的带有状态码、提示消息以及具体业务数据的ServerResponse实例，
+     * 适用于各种需要全面传递响应信息给客户端的复杂场景，综合体现了请求处理的结果情况。
+     * @param status 响应状态码
+     * @param msg 响应提示消息
+     * @param data 具体业务数据
+     */
+    public ServerResponse(int status, String msg, T data) {
         this.status = status;
         this.msg = msg;
         this.data = data;
     }
 
+    /**
+     * 通过该注解标记该方法在JSON序列化时被忽略，也就是不会将该方法的返回结果作为JSON数据的一部分返回给客户端。
+     * 该方法用于判断当前响应是否表示成功，通过对比响应状态码和预定义的表示成功的状态码（从ResponseEnum.SUCCESS中获取）来确定，
+     * 方便客户端快速判断请求是否成功处理，而不需要关注具体的状态码数值细节。
+     * @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);
+
+    /**
+     * 创建一个表示成功的ServerResponse实例，使用预定义的成功状态码和对应的成功描述信息（从ResponseEnum.SUCCESS中获取），
+     * 数据部分为空，适用于只需要简单告知客户端操作成功的基本情况，不需要额外返回具体业务数据和自定义提示消息的场景。
+     * @param <T> 泛型标识，确保返回的ServerResponse类型与调用处期望的类型一致（虽然此处数据部分为空，但保持泛型通用性）。
+     * @return 返回一个表示成功的ServerResponse实例。
+     */
+    public static <T> ServerResponse<T> createBySuccess() {
+        return new ServerResponse<>(ResponseEnum.SUCCESS.getCode(), ResponseEnum.SUCCESS.getDesc());
     }
 
     /**
-     * 失败的方法
+     * 创建一个表示成功的ServerResponse实例，使用预定义的成功状态码，同时可以自定义提示消息，数据部分为空，
+     * 适用于操作成功但需要向客户端传达一些额外的自定义提示内容的场景，比如成功后提示一些引导性的话语等情况。
+     * @param <T> 泛型标识，确保返回的ServerResponse类型与调用处期望的类型一致（虽然此处数据部分为空，但保持泛型通用性）。
+     * @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实例，使用预定义的成功状态码，同时携带具体业务数据，提示消息为默认的成功描述信息（从ResponseEnum.SUCCESS中获取），
+     * 适用于操作成功且需要返回具体业务数据给客户端的场景，比如查询到了相关数据并返回给客户端展示等情况。
+     * @param <T> 泛型标识，确保返回的ServerResponse类型与调用处期望的类型一致（根据传入的数据类型来确定具体的泛型类型）。
+     * @param 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实例，使用预定义的成功状态码，同时携带具体业务数据以及自定义提示消息，
+     * 适用于操作成功且需要向客户端返回具体业务数据和一些额外自定义提示内容的复杂场景，综合向客户端传达完整的成功响应信息。
+     * @param <T> 泛型标识，确保返回的ServerResponse类型与调用处期望的类型一致（根据传入的数据类型来确定具体的泛型类型）。
+     * @param message 自定义的提示消息内容。
+     * @param data 具体业务数据。
+     * @return 返回一个表示成功的ServerResponse实例。
+     */
+    public static <T> ServerResponse<T> createBySuccess(String message, T data) {
+        return new ServerResponse<>(ResponseEnum.SUCCESS.getCode(), message, data);
     }
 
+    /**
+     * 以下是一系列静态方法，用于方便地创建表示失败的ServerResponse实例，按照不同的需求场景提供了多种创建方式。
+     */
 
+    /**
+     * 创建一个表示失败的ServerResponse实例，使用预定义的表示失败的状态码和对应的失败描述信息（从ResponseEnum.ERROR中获取），
+     * 适用于一般性的失败情况，不需要额外自定义提示消息和返回具体业务数据，简单告知客户端操作失败的基本情况。
+     * @param <T> 泛型标识，确保返回的ServerResponse类型与调用处期望的类型一致（虽然此处数据部分为空，但保持泛型通用性）。
+     * @return 返回一个表示失败的ServerResponse实例。
+     */
+    public static <T> ServerResponse<T> createByError() {
+        return new ServerResponse<>(ResponseEnum.ERROR.getCode(), ResponseEnum.ERROR.getDesc());
+    }
 
-}
+    /**
+     * 创建一个表示失败的ServerResponse实例，使用预定义的表示失败的状态码，同时可以自定义提示消息，
+     * 适用于操作失败且需要向客户端传达具体的失败原因等自定义提示内容的场景，更详细地告知客户端操作失败的情况。
+     * @param <T> 泛型标识，确保返回的ServerResponse类型与调用处期望的类型一致（虽然此处数据部分为空，但保持泛型通用性）。
+     * @param msg 自定义的提示消息内容。
+     * @return 返回一个表示失败的ServerResponse实例。
+     */
+    public static <T> ServerResponse<T> createByErrorMessage(String msg) {
+        return new ServerResponse<>(ResponseEnum.ERROR.getCode(), msg);
+    }
+
+    /**
+     * 创建一个表示失败的ServerResponse实例，可自定义失败状态码和提示消息，
+     * 适用于需要根据具体业务逻辑来设定特定的失败状态码以及传达对应的失败原因等情况，更加灵活地表示各种失败场景。
+     * @param <T> 泛型标识，确保返回的ServerResponse类型与调用处期望的类型一致（虽然此处数据部分为空，但保持泛型通用性）。
+     * @param code 自定义的失败状态码。
+     * @param msg 自定义的提示消息内容。
+     * @return 返回一个表示失败的ServerResponse实例。
+     */
+    public static <T> ServerResponse<T> createByErrorCodeMessage(int code, String msg) {
+        return new ServerResponse<>(code, msg);
+    }
+}

snailmall-category-service/src/main/java/com/njupt/swg/controller/CategoryController.java

@@ -7,8 +7,9 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
-
 /**
+ * 该类CategoryController是一个Spring的RestController，用于处理与品类相关的业务接口请求。
+ * 这些接口主要是供后端管理系统人员操作使用的，所以通常需要管理员权限来访问（当前代码中鉴权相关有待后续完善，如TODO注释所述）。
  * @Author swg.
  * @Date 2019/1/2 12:57
  * @CONTACT 317758022@qq.com
@@ -18,55 +19,69 @@ import org.springframework.web.bind.annotation.RestController;
 //TODO 这里首先实现业务  关于这里重复的鉴权，后面将会移植到网关中统一去做
 //TODO 先开放GET请求
 @RestController
+// 表明该类是一个Spring RESTful风格的控制器，其内部的方法返回值会直接序列化为JSON格式并返回给客户端，无需额外配置视图解析等。
 @RequestMapping("/manage/category/")
+// 定义该控制器处理请求的基础路径，所有该控制器下的接口请求路径都以此为前缀。
 public class CategoryController {
     @Autowired
+    // 使用Spring的依赖注入功能，自动注入ICategoryService的实现类实例，以便在控制器方法中调用对应的业务逻辑方法。
     private ICategoryService categoryService;
 
     /**
-     * 获取品类子节点(平级)
+     * 获取品类子节点(平级)的接口方法。
+     * 接收一个名为categoryId的请求参数（类型为Integer，默认值为0），用于指定获取哪个品类的子节点信息。
+     * 通过调用categoryService的getCategory方法来获取相应的品类子节点信息，并将其返回给客户端，返回的数据格式为ServerResponse类型，
+     * 该类型是项目自定义的通用响应封装类，包含了状态码、提示消息以及具体的数据内容等信息。
      */
     @RequestMapping("get_category.do")
-    public ServerResponse getCategory(@RequestParam(value = "categoryId",defaultValue = "0") Integer categoryId){
+    public ServerResponse getCategory(@RequestParam(value = "categoryId", defaultValue = "0") Integer categoryId) {
         ServerResponse response = categoryService.getCategory(categoryId);
         return response;
     }
 
     /**
-     * 增加节点
+     * 增加品类节点的接口方法。
+     * 接收两个请求参数，一个是categoryName（类型为String）表示要增加的品类节点的名称，另一个是parentId（类型为int，默认值为0），
+     * 用于指定新增节点的父节点ID。通过调用categoryService的addCategory方法来执行增加品类节点的业务逻辑，
+     * 并将执行结果（以ServerResponse类型封装）返回给客户端，告知客户端操作是否成功以及相关信息。
      */
     @RequestMapping("add_category.do")
-    public ServerResponse addCategory(String categoryName, @RequestParam(value = "parentId",defaultValue = "0")int parentId){
-        ServerResponse response = categoryService.addCategory(categoryName,parentId);
+    public ServerResponse addCategory(String categoryName, @RequestParam(value = "parentId", defaultValue = "0") int parentId) {
+        ServerResponse response = categoryService.addCategory(categoryName, parentId);
         return response;
     }
 
     /**
-     * 修改品类名称
+     * 修改品类名称的接口方法。
+     * 接收两个请求参数，categoryName（类型为String）表示要修改后的品类名称，categoryId（类型为Integer）用于指定要修改名称的品类的ID。
+     * 直接调用categoryService的updateCategoryName方法来执行修改品类名称的业务逻辑，并将该方法返回的ServerResponse<String>类型的结果直接返回给客户端，
+     * 这里返回的泛型<String>可能表示返回一些与修改操作相关的提示消息等字符串内容。
      */
     @RequestMapping("set_category_name.do")
-    public ServerResponse<String> set_category_name(String categoryName,Integer categoryId){
-        return categoryService.updateCategoryName(categoryName,categoryId);
+    public ServerResponse<String> set_category_name(String categoryName, Integer categoryId) {
+        return categoryService.updateCategoryName(categoryName, categoryId);
     }
 
     /**
-     * 递归获取自身和所有的子节点
+     * 递归获取自身和所有的子节点的接口方法。
+     * 接收一个名为categoryId的请求参数（类型为Integer，默认值为0），用于指定从哪个品类节点开始递归获取其自身及所有子节点信息。
+     * 通过调用categoryService的selectCategoryAndDeepChildrenById方法来执行递归获取的业务逻辑，并将结果（以ServerResponse类型封装）返回给客户端，
+     * 方便客户端获取完整的品类树相关信息。
      */
     @RequestMapping("get_deep_category.do")
-    public ServerResponse get_deep_category(@RequestParam(value = "categoryId",defaultValue = "0") Integer categoryId){
+    public ServerResponse get_deep_category(@RequestParam(value = "categoryId", defaultValue = "0") Integer categoryId) {
         return categoryService.selectCategoryAndDeepChildrenById(categoryId);
     }
 
 
     /**
-     * 这是为了给其他服务调用而新增的接口
+     * 这是为了给其他服务调用而新增的接口。
+     * 接收一个名为categoryId的请求参数（类型为Integer），用于指定要获取详细信息的品类ID。
+     * 通过调用categoryService的getCategoryDetail方法来获取相应品类的详细信息，并将结果（以ServerResponse类型封装）返回给客户端，
+     * 方便其他服务使用该接口获取所需的品类详情数据。
      */
     @RequestMapping("get_category_detail.do")
-    public ServerResponse get_category_detail(Integer categoryId){
+    public ServerResponse get_category_detail(Integer categoryId) {
         return categoryService.getCategoryDetail(categoryId);
     }
-
-
-
-
-}
+}

snailmall-category-service/src/main/java/com/njupt/swg/dao/CategoryMapper.java

@@ -1,24 +1,79 @@
 package com.njupt.swg.dao;
 
-
 import com.njupt.swg.entity.Category;
 import org.apache.ibatis.annotations.Mapper;
-
 import java.util.List;
 
+/**
+ * 该接口CategoryMapper是MyBatis框架中用于定义与数据库交互操作的Mapper接口，
+ * 它定义了一系列针对Category实体相关的数据库操作方法，这些方法会与对应的MyBatis映射文件（XML配置文件）中的SQL语句进行关联，
+ * 实现对数据库中相关表的数据操作功能。
+ * @Mapper注解用于标记该接口是一个MyBatis的Mapper接口，在Spring框架集成MyBatis时，会自动扫描并创建该接口的代理实现类，
+ * 方便在其他业务层代码中进行注入和调用这些数据库操作方法。
+ */
 @Mapper
 public interface CategoryMapper {
+    /**
+     * 根据主键（id）删除对应的记录的方法，接收一个Integer类型的id参数，
+     * 用于指定要删除记录的主键值，返回一个整数类型结果，表示受影响的行数（通常用于判断删除操作是否成功，例如返回1表示成功删除了1条记录）。
+     * 该方法会关联到MyBatis映射文件中对应的<delete>标签定义的SQL语句来执行实际的数据库删除操作。
+     * @param id 要删除记录的主键值（对应数据库表中的唯一标识字段）
+     * @return 受影响的行数
+     */
     int deleteByPrimaryKey(Integer id);
 
+    /**
+     * 插入一条完整的Category实体记录到数据库的方法，接收一个Category类型的record参数，
+     * 该参数包含了要插入到数据库表中的各个字段对应的值，返回一个整数类型结果，表示受影响的行数（例如返回1表示成功插入了1条记录）。
+     * 此方法会对应MyBatis映射文件中定义的插入相关的SQL语句（如<insert>标签定义的语句）来执行实际的插入操作。
+     * @param record 要插入的Category实体对象，包含了插入到数据库表所需的各个字段值
+     * @return 受影响的行数
+     */
     int insert(Category record);
 
+    /**
+     * 有选择性地插入Category实体记录到数据库的方法，同样接收一个Category类型的record参数。
+     * 与insert方法不同的是，它会根据record对象中各个属性是否为null来决定是否插入对应的列数据到数据库表中，更加灵活，避免插入不必要的null值。
+     * 返回一个整数类型结果，表示受影响的行数，关联到MyBatis映射文件中对应的动态插入SQL语句（如<insertSelective>标签定义的语句）来执行操作。
+     * @param record 要插入的Category实体对象，其属性的null情况会决定实际插入的列数据
+     * @return 受影响的行数
+     */
     int insertSelective(Category record);
 
+    /**
+     * 根据主键（id）查询对应的Category实体记录的方法，接收一个Integer类型的id参数，用于指定要查询记录的主键值。
+     * 返回一个Category类型的结果，即查询到的对应的实体对象，如果没有查询到则返回null。
+     * 该方法会关联到MyBatis映射文件中对应的查询SQL语句（如<select>标签定义的语句）以及定义的结果映射（<resultMap>标签相关配置）来将数据库查询结果转换为Category实体对象。
+     * @param id 要查询记录的主键值（对应数据库表中的唯一标识字段）
+     * @return 查询到的Category实体对象，如果未查询到则为null
+     */
     Category selectByPrimaryKey(Integer id);
 
+    /**
+     * 根据传入的Category实体对象有选择性地更新数据库中对应记录的方法，接收一个Category类型的record参数。
+     * 会根据record对象中各个属性是否为null来决定是否更新对应的列数据，只更新有值变化的列，避免全列更新，更加灵活高效。
+     * 返回一个整数类型结果，表示受影响的行数，关联到MyBatis映射文件中对应的动态更新SQL语句（如<updateByPrimaryKeySelective>标签定义的语句）来执行实际的更新操作。
+     * @param record 要用于更新的Category实体对象，其属性的null情况会决定实际更新的列数据
+     * @return 受影响的行数
+     */
     int updateByPrimaryKeySelective(Category record);
 
+    /**
+     * 根据传入的Category实体对象更新数据库中对应记录的所有列数据的方法，接收一个Category类型的record参数。
+     * 不管属性值是否有变化，都会按照record对象中的属性值更新数据库表中对应记录的所有列，返回一个整数类型结果，表示受影响的行数。
+     * 关联到MyBatis映射文件中对应的更新SQL语句（如<updateByPrimaryKey>标签定义的语句）来执行实际的更新操作。
+     * @param record 要用于更新的Category实体对象，包含了更新数据库表对应记录所有列所需的各个字段值
+     * @return 受影响的行数
+     */
     int updateByPrimaryKey(Category record);
 
+    /**
+     * 根据父节点的categoryId查询其对应的子节点记录列表的方法，接收一个Integer类型的categoryId参数，用于指定父节点的标识。
+     * 返回一个List<Category>类型的结果，即包含了查询到的所有子节点对应的Category实体对象的列表，如果没有子节点则返回空列表。
+     * 该方法会关联到MyBatis映射文件中对应的查询子节点的SQL语句（如<selectCategoryChildrenByParentId>标签定义的语句，假设有对应配置）来执行实际的查询操作，
+     * 并通过定义的结果映射将数据库查询结果转换为Category实体对象列表。
+     * @param categoryId 父节点的标识（对应数据库表中表示父子关系的字段值）
+     * @return 查询到的子节点对应的Category实体对象列表，若无子节点则为空列表
+     */
     List<Category> selectCategoryChildrenByParentId(Integer categoryId);
 }

snailmall-category-service/src/main/java/com/njupt/swg/dao/mapper/CategoryMapper.xml

@@ -1,6 +1,12 @@
-<?xml version="1.0" encoding="UTF-8" ?>
+<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd" >
+<!-- 该mapper标签定义了MyBatis的映射文件，namespace属性指定了对应的Mapper接口的全限定名，
+     用于将XML中的SQL语句与Java代码中的Mapper接口方法关联起来 -->
 <mapper namespace="com.njupt.swg.dao.CategoryMapper" >
+
+  <!-- 定义了一个名为BaseResultMap的结果映射，用于将从数据库查询结果映射到Java中的com.njupt.swg.entity.Category实体类对象。
+       通过<constructor>标签内的<idArg>和<arg>元素来指定构造函数参数与数据库表字段的对应关系，
+       包括字段名、JDBC类型以及对应的Java类型等信息 -->
   <resultMap id="BaseResultMap" type="com.njupt.swg.entity.Category" >
     <constructor >
       <idArg column="id" jdbcType="INTEGER" javaType="java.lang.Integer" />
@@ -12,111 +18,136 @@
       <arg column="update_time" jdbcType="TIMESTAMP" javaType="java.util.Date" />
     </constructor>
   </resultMap>
+
+  <!-- 定义了一个名为Base_Column_List的SQL片段，包含了要从数据库表中查询的列名列表，
+       后续其他SQL语句可以通过<include>标签引用这个片段，方便复用代码 -->
   <sql id="Base_Column_List" >
     id, parent_id, name, status, sort_order, create_time, update_time
   </sql>
+
+  <!-- 定义了一个名为selectByPrimaryKey的查询语句，用于根据主键（id）查询记录。
+       resultMap属性指定了使用前面定义的BaseResultMap来映射查询结果，parameterType指定了传入参数的类型为Integer（对应主键的类型）。
+       SQL语句通过<include>标签引用了Base_Column_List片段来获取指定列的数据，并根据传入的主键值进行筛选查询 -->
   <select id="selectByPrimaryKey" resultMap="BaseResultMap" parameterType="java.lang.Integer" >
-    select 
+    select
     <include refid="Base_Column_List" />
     from mmall_category
     where id = #{id,jdbcType=INTEGER}
   </select>
+
+  <!-- 定义了一个名为deleteByPrimaryKey的删除语句，用于根据主键（id）删除记录，parameterType指定了传入参数的类型为Integer（对应主键的类型），
+       SQL语句指定了从mmall_category表中删除满足id条件的记录 -->
   <delete id="deleteByPrimaryKey" parameterType="java.lang.Integer" >
     delete from mmall_category
     where id = #{id,jdbcType=INTEGER}
   </delete>
+
+  <!-- 定义了一个名为insert的插入语句，用于向mmall_category表中插入一条完整的记录，parameterType指定了传入参数的类型为com.njupt.swg.entity.Category实体类，
+       SQL语句明确列出了要插入的列名以及对应的通过#{属性名,jdbcType=类型}方式获取实体类属性值来插入数据，对于create_time和update_time使用了数据库函数now()来获取当前时间插入 -->
   <insert id="insert" parameterType="com.njupt.swg.entity.Category" >
-    insert into mmall_category (id, parent_id, name, 
-      status, sort_order, create_time, 
-      update_time)
-    values (#{id,jdbcType=INTEGER}, #{parentId,jdbcType=INTEGER}, #{name,jdbcType=VARCHAR}, 
-      #{status,jdbcType=BIT}, #{sortOrder,jdbcType=INTEGER}, now(),
-      now())
+    insert into mmall_category (id, parent_id, name,
+                                status, sort_order, create_time,
+                                update_time)
+    values (#{id,jdbcType=INTEGER}, #{parentId,jdbcType=INTEGER}, #{name,jdbcType=VARCHAR},
+            #{status,jdbcType=BIT}, #{sortOrder,jdbcType=INTEGER}, now(),
+            now())
   </insert>
+
+  <!-- 定义了一个名为insertSelective的插入语句，相比于insert语句更加灵活，它会根据传入的com.njupt.swg.entity.Category实体类对象中属性是否为null来决定是否插入对应的列数据。
+       通过<trim>标签结合<if>条件判断来动态构建插入语句的列名和对应的值部分，避免插入不必要的null值到数据库表中 -->
   <insert id="insertSelective" parameterType="com.njupt.swg.entity.Category" >
     insert into mmall_category
     <trim prefix="(" suffix=")" suffixOverrides="," >
-      <if test="id != null" >
+      <if test="id!= null" >
         id,
       </if>
-      <if test="parentId != null" >
+      <if test="parentId!= null" >
         parent_id,
       </if>
-      <if test="name != null" >
+      <if test="name!= null" >
         name,
       </if>
-      <if test="status != null" >
+      <if test="status!= null" >
         status,
       </if>
-      <if test="sortOrder != null" >
+      <if test="sortOrder!= null" >
         sort_order,
       </if>
-      <if test="createTime != null" >
+      <if test="createTime!= null" >
         create_time,
       </if>
-      <if test="updateTime != null" >
+      <if test="updateTime!= null" >
         update_time,
       </if>
     </trim>
     <trim prefix="values (" suffix=")" suffixOverrides="," >
-      <if test="id != null" >
+      <if test="id!= null" >
         #{id,jdbcType=INTEGER},
       </if>
-      <if test="parentId != null" >
+      <if test="parentId!= null" >
         #{parentId,jdbcType=INTEGER},
       </if>
-      <if test="name != null" >
+      <if test="name!= null" >
         #{name,jdbcType=VARCHAR},
       </if>
-      <if test="status != null" >
+      <if test="status!= null" >
         #{status,jdbcType=BIT},
       </if>
-      <if test="sortOrder != null" >
+      <if test="sortOrder!= null" >
         #{sortOrder,jdbcType=INTEGER},
       </if>
-      <if test="createTime != null" >
+      <if test="createTime!= null" >
         now(),
       </if>
-      <if test="updateTime != null" >
+      <if test="updateTime!= null" >
         now(),
       </if>
     </trim>
   </insert>
+
+  <!-- 定义了一个名为updateByPrimaryKeySelective的更新语句，根据传入的com.njupt.swg.entity.Category实体类对象中属性是否为null来决定是否更新对应的列数据。
+       通过<set>标签结合<if>条件判断来动态构建更新语句的列赋值部分，只更新有值变化的列，避免不必要的全列更新，最后根据主键（id）来定位要更新的记录 -->
   <update id="updateByPrimaryKeySelective" parameterType="com.njupt.swg.entity.Category" >
     update mmall_category
     <set >
-      <if test="parentId != null" >
+      <if test="parentId!= null" >
         parent_id = #{parentId,jdbcType=INTEGER},
       </if>
-      <if test="name != null" >
+      <if test="name!= null" >
         name = #{name,jdbcType=VARCHAR},
       </if>
-      <if test="status != null" >
+      <if test="status!= null" >
         status = #{status,jdbcType=BIT},
       </if>
-      <if test="sortOrder != null" >
+      <if test="sortOrder!= null" >
         sort_order = #{sortOrder,jdbcType=INTEGER},
       </if>
-      <if test="createTime != null" >
+      <if test="createTime!= null" >
         create_time = #{createTime,jdbcType=TIMESTAMP},
       </if>
-      <if test="updateTime != null" >
+      <if test="updateTime!= null" >
         update_time = now(),
       </if>
     </set>
     where id = #{id,jdbcType=INTEGER}
   </update>
+
+  <!-- 定义了一个名为updateByPrimaryKey的更新语句，用于根据传入的com.njupt.swg.entity.Category实体类对象来更新mmall_category表中对应主键（id）的记录的所有列数据，
+       直接列出了要更新的列名和对应从实体类获取的属性值，最后根据主键（id）来定位要更新的记录 -->
   <update id="updateByPrimaryKey" parameterType="com.njupt.swg.entity.Category" >
     update mmall_category
     set parent_id = #{parentId,jdbcType=INTEGER},
-      name = #{name,jdbcType=VARCHAR},
-      status = #{status,jdbcType=BIT},
-      sort_order = #{sortOrder,jdbcType=INTEGER},
-      create_time = #{createTime,jdbcType=TIMESTAMP},
-      update_time = now()
+        name = #{name,jdbcType=VARCHAR},
+        status = #{status,jdbcType=BIT},
+        sort_order = #{sortOrder,jdbcType=INTEGER},
+        create_time = #{createTime,jdbcType=TIMESTAMP},
+        update_time = now()
     where id = #{id,jdbcType=INTEGER}
   </update>
 
+  <!-- 定义了一个名为selectCategoryChildrenByParentId的查询语句，用于根据父节点的categoryId查询其对应的子节点记录。
+       parameterType指定了传入参数的类型为int（对应categoryId的类型），resultMap指定了使用前面定义的BaseResultMap来映射查询结果，
+       SQL语句通过<include>标签引用了Base_Column_List片段来获取指定列的数据，并根据传入的父节点categoryId值进行筛选查询 -->
   <select id="selectCategoryChildrenByParentId" parameterType="int" resultMap="BaseResultMap">
     SELECT <include refid="Base_Column_List"/> from mmall_category where parent_id = #{categoryId}
   </select>

snailmall-category-service/src/main/java/com/njupt/swg/entity/Category.java

@@ -3,24 +3,32 @@ package com.njupt.swg.entity;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
-
 import java.util.Date;
 
+/**
+ * 该类Category是一个实体类，用于映射数据库中对应的表结构，代表了品类相关的业务对象。
+ * 它通过使用Lombok提供的注解来简化代码编写，自动生成了一些常用的方法，如构造函数、Getter/Setter方法等。
+ * 此类中的各个属性对应数据库表中的相应字段，用于在Java程序与数据库之间传递和存储数据。
+ */
 @Data
+// 使用Lombok的@Data注解，会自动为类中的所有非静态、非final属性生成Getter、Setter方法，同时还会生成toString、equals、hashCode等方法，方便对象的操作和比较等。
 @AllArgsConstructor
+// 使用Lombok的@AllArgsConstructor注解，会自动生成一个包含所有属性的构造函数，方便在创建对象时一次性传入所有属性值进行初始化。
 @NoArgsConstructor
+// 使用Lombok的@NoArgsConstructor注解，会自动生成一个无参构造函数，在一些框架（如MyBatis在实例化对象等场景）可能需要使用无参构造函数的情况下很有用。
 public class Category {
+    // 对应数据库表中品类记录的唯一标识字段，用于区分不同的品类，类型为Integer。
     private Integer id;
-
+    // 表示品类的父节点ID，用于构建品类之间的层级关系，类型为Integer，通过该字段可以知道某个品类所属的上级品类，若为顶级品类则可能为特定的默认值（如0等表示无父节点）。
     private Integer parentId;
-
+    // 品类的名称，类型为String，用于直观地标识和区分不同的品类，例如“电子产品”“服装”等具体的品类名称。
     private String name;
-
+    // 表示品类的状态，类型为Boolean，可用于标记品类是否有效、是否启用等业务状态，例如true表示该品类正常可用，false表示已停用等情况。
     private Boolean status;
-
+    // 用于指定品类在展示、排序等场景下的顺序，类型为Integer，数值越小可能表示在排序中越靠前等，方便对多个品类进行顺序排列。
     private Integer sortOrder;
-
+    // 记录品类创建的时间，类型为Date，用于记录该品类首次被添加到系统中的时间点，方便后续进行时间相关的查询、统计等操作。
     private Date createTime;
-
+    // 记录品类最后一次更新的时间，类型为Date，每次对品类的相关信息（如名称、状态等）进行修改操作后，会更新该时间字段，便于追踪品类信息的变更情况。
     private Date updateTime;
 }

snailmall-category-service/src/main/java/com/njupt/swg/entity/User.java

@@ -4,40 +4,45 @@ import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 import lombok.ToString;
-
 import java.io.Serializable;
 import java.util.Date;
 
 /**
+ * 该类User是用户实体类，用于在Java程序中表示用户相关的业务对象，其各个属性对应了用户在系统中的各项信息。
+ * 通过使用Lombok提供的注解来简化代码编写，自动生成了诸如构造函数、Getter/Setter方法、toString方法等常用的代码结构。
+ * 此类实现了Serializable接口，以便能够在网络传输、对象持久化等场景下进行序列化和反序列化操作，保证对象状态的正确保存和恢复。
  * @Author swg.
  * @Date 2018/12/31 21:01
  * @CONTACT 317758022@qq.com
  * @DESC 用户实体类
  */
 @Data
+// 使用Lombok的@Data注解，会自动为类中的所有非静态、非final属性生成Getter、Setter方法，同时还会生成toString、equals、hashCode等方法，方便对用户对象进行操作、比较以及以字符串形式展示等操作。
 @NoArgsConstructor
+// 使用Lombok的@NoArgsConstructor注解，会自动生成一个无参构造函数，在一些框架初始化对象或者通过反射创建对象等场景中可能会需要使用无参构造函数。
 @AllArgsConstructor
+// 使用Lombok的@AllArgsConstructor注解，会自动生成一个包含所有属性的构造函数，方便在创建用户对象时一次性传入所有属性值来进行初始化操作。
 @ToString
+// 使用Lombok的@ToString注解，会自动重写toString方法，使得在调用该方法时能够以一种比较友好的格式输出用户对象的各个属性值，便于调试和查看对象内容。
 public class User implements Serializable {
+    // 用户在系统中的唯一标识，通常由数据库自动生成或者按照一定规则分配，类型为Integer，用于区分不同的用户个体。
     private Integer id;
-
+    // 用户登录系统时使用的用户名，类型为String，要求具有唯一性（一般情况下），方便用户进行身份识别和登录操作。
     private String username;
-
+    // 用户登录系统时使用的密码，类型为String，通常会经过加密处理后存储，以保障用户账户的安全性。
     private String password;
-
+    // 用户的电子邮箱地址，类型为String，可用于接收系统发送的通知、验证邮件等，也是一种常用的用户联系方式和身份验证方式之一。
     private String email;
-
+    // 用户的手机号码，类型为String，同样可用于接收短信通知、作为登录验证的一种方式等，是重要的用户联系方式。
     private String phone;
-
+    // 用户设置的密保问题，类型为String，用于在用户忘记密码等情况下进行身份验证，辅助找回密码等操作。
     private String question;
-
+    // 用户针对密保问题设置的答案，类型为String，必须与密保问题相对应，用于验证用户身份的合法性。
     private String answer;
-
-    //角色0-管理员,1-普通用户
+    // 用于标识用户在系统中的角色，类型为Integer，0表示管理员角色，拥有较高的系统操作权限；1表示普通用户角色，权限相对受限，只能进行一些常规的业务操作。
     private Integer role;
-
+    // 记录用户账号创建的时间，类型为Date，便于后续查询用户注册时间、统计不同时间段的注册人数等与时间相关的业务操作。
     private Date createTime;
-
+    // 记录用户账号信息最后一次更新的时间，类型为Date，比如用户修改密码、更新联系方式等操作后，会更新该时间字段，方便追踪用户信息的变更情况。
     private Date updateTime;
-
 }

snailmall-category-service/src/main/java/com/njupt/swg/service/CategoryServiceImpl.java

@@ -16,115 +16,165 @@ import java.util.List;
 import java.util.Set;
 
 /**
+ * 该类CategoryServiceImpl是实现了ICategoryService接口的服务层实现类，主要用于处理与品类相关的业务逻辑。
+ * 它依赖于CategoryMapper来与数据库进行交互，获取或操作品类相关的数据，并通过抛出SnailmallException异常来处理业务中的错误情况，
+ * 使用ServerResponse来封装业务操作结果返回给上层调用者，同时利用日志记录相关信息辅助排查问题等。
  * @Author swg.
  * @Date 2019/1/2 12:54
  * @CONTACT 317758022@qq.com
  * @DESC
  */
 @Service
+// 该注解表明这个类是Spring框架中的一个服务层组件，Spring会自动扫描并管理这个类，使其可以被注入到其他需要使用的地方。
 @Slf4j
-public class CategoryServiceImpl implements ICategoryService{
+// 使用lombok的@Slf4j注解，自动生成一个名为log的日志记录对象，方便在类中记录日志信息，便于后续调试和查看业务执行情况。
+public class CategoryServiceImpl implements ICategoryService {
     @Autowired
+    // 使用Spring的依赖注入功能，自动注入CategoryMapper的实例，以便调用其定义的数据库操作方法，实现与数据库的交互。
     private CategoryMapper categoryMapper;
 
-
+    /**
+     * 获取品类子节点（平级）的业务方法，根据传入的品类ID获取其下一级的所有子品类信息。
+     *
+     * @param categoryId 要获取子节点的品类的ID，若为null则表示参数不合法。
+     * @return ServerResponse类型的结果，若获取成功则返回包含子品类列表的成功响应，若没有子节点则返回相应提示信息的成功响应，若参数不合法则抛出异常。
+     */
     @Override
     public ServerResponse getCategory(Integer categoryId) {
-        //1.校验参数
-        if(categoryId == null){
+        // 1.校验参数
+        if (categoryId == null) {
+            // 如果品类ID为null，说明参数不符合要求，抛出SnailmallException异常，提示“未找到该品类”，由全局异常处理机制进行处理。
             throw new SnailmallException("未找到该品类");
         }
-        //2.根据父亲id获取这个父亲下一级所有子ID
+        // 2.根据父亲id获取这个父亲下一级所有子ID
         List<Category> categoryList = categoryMapper.selectCategoryChildrenByParentId(categoryId);
-        if(CollectionUtils.isEmpty(categoryList)){
+        if (CollectionUtils.isEmpty(categoryList)) {
+            // 如果获取到的子品类列表为空，说明该节点下没有任何子节点，记录相应的日志信息供后续查看。
             log.info("该节点下没有任何子节点");
         }
         return ServerResponse.createBySuccess(categoryList);
     }
 
+    /**
+     * 增加品类节点的业务方法，根据传入的品类名称和父节点ID创建并添加一个新的品类到数据库中。
+     *
+     * @param categoryName 要添加的品类的名称，不能为空字符串。
+     * @param parentId     新添加品类的父节点的ID，默认值为0等情况可表示无父节点（根据具体业务规则）。
+     * @return ServerResponse类型的结果，若添加成功则返回包含成功提示消息的成功响应，若添加失败则返回包含失败提示消息的响应。
+     */
     @Override
     public ServerResponse addCategory(String categoryName, int parentId) {
-        //1.校验参数
-        if(StringUtils.isBlank(categoryName)){
+        // 1.校验参数
+        if (StringUtils.isBlank(categoryName)) {
+            // 如果品类名称为空字符串，说明参数不符合要求，抛出SnailmallException异常，提示“品类名字不能为空”，由全局异常处理机制进行处理。
             throw new SnailmallException("品类名字不能为空");
         }
-        //2.创建类目
+        // 2.创建类目
         Category category = new Category();
         category.setName(categoryName);
         category.setParentId(parentId);
         category.setStatus(true);
 
         int resultCount = categoryMapper.insert(category);
-        if(resultCount > 0){
+        if (resultCount > 0) {
+            // 如果数据库插入操作影响的行数大于0，说明插入成功，返回包含“添加品类成功”提示消息的成功响应。
             return ServerResponse.createBySuccessMessage("添加品类成功");
         }
         return ServerResponse.createByErrorMessage("添加品类失败");
     }
 
+    /**
+     * 修改品类名称的业务方法，根据传入的新的品类名称和品类ID来更新数据库中对应品类的名称信息。
+     *
+     * @param categoryName 要修改成的新的品类名称，不能为空字符串。
+     * @param categoryId   要修改名称的品类的ID，用于定位数据库中的对应记录。
+     * @return ServerResponse<String>类型的结果，若更新成功则返回包含成功提示消息的成功响应，若更新失败则返回包含失败提示消息的响应，
+     * 这里返回的泛型<String>可能表示返回一些与修改操作相关的提示消息等字符串内容。
+     */
     @Override
     public ServerResponse<String> updateCategoryName(String categoryName, Integer categoryId) {
-        //1.校验参数
-        if(StringUtils.isBlank(categoryName)){
+        // 1.校验参数
+        if (StringUtils.isBlank(categoryName)) {
+            // 如果品类名称为空字符串，说明参数不符合要求，抛出SnailmallException异常，提示“品类名字不能为空”，由全局异常处理机制进行处理。
             throw new SnailmallException("品类名字不能为空");
         }
-        //2.根据id获取品类
+        // 2.根据id获取品类
         Category tmpCat = categoryMapper.selectByPrimaryKey(categoryId);
-        if(tmpCat == null){
+        if (tmpCat == null) {
+            // 如果根据ID没有查询到对应的品类，说明品类不存在，抛出SnailmallException异常，提示“品类不存在”，由全局异常处理机制进行处理。
             throw new SnailmallException("品类不存在");
         }
-        //3.更新品类名称
+        // 3.更新品类名称
         Category category = new Category();
         category.setId(categoryId);
         category.setName(categoryName);
         int resultCount = categoryMapper.updateByPrimaryKeySelective(category);
-        if(resultCount > 0){
+        if (resultCount > 0) {
+            // 如果数据库更新操作影响的行数大于0，说明更新成功，返回包含“更新品类名称成功”提示消息的成功响应。
             return ServerResponse.createBySuccessMessage("更新品类名称成功");
         }
         return ServerResponse.createByErrorMessage("更新品类名称失败");
     }
 
+    /**
+     * 递归获取自身和所有的子节点的业务方法，根据传入的品类ID，递归地获取该品类及其所有子品类的ID信息，并返回。
+     *
+     * @param categoryId 要开始递归获取子节点的品类的ID，可以为null（根据业务逻辑进行相应处理）。
+     * @return ServerResponse类型的结果，若获取成功则返回包含品类ID列表的成功响应，其中包含了自身及所有子品类的ID信息。
+     */
     @Override
     public ServerResponse selectCategoryAndDeepChildrenById(Integer categoryId) {
-        //1、创建一个空Set用来存放不重复的品类对象--去重
+        // 1、创建一个空Set用来存放不重复的品类对象--去重
         Set<Category> categorySet = Sets.newHashSet();
-        //2、递归获取所有的子节点（儿子、孙子、等等），包括自己也添加进去
-        findChildCategory(categorySet,categoryId);
-        //3、将递归获取到的品类id取出来放进list中
+        // 2、递归获取所有的子节点（儿子、孙子、等等），包括自己也添加进去
+        findChildCategory(categorySet, categoryId);
+        // 3、将递归获取到的品类id取出来放进list中
         List<Integer> categoryIdList = new ArrayList<>();
-        if(categoryId != null){
-            for(Category category:categorySet){
+        if (categoryId!= null) {
+            for (Category category : categorySet) {
                 categoryIdList.add(category.getId());
             }
         }
         return ServerResponse.createBySuccess(categoryIdList);
     }
 
-    private Set<Category> findChildCategory(Set<Category> categorySet,Integer categoryId){
-        //4、如果自己不为空的话，首先把自己添加进去；如果自己为空，这个递归分支就结束，所以也是一个停止条件
+    /**
+     * 递归查找子品类的私有方法，用于在selectCategoryAndDeepChildrenById方法中递归地查找给定品类及其所有子品类，并添加到传入的Set集合中进行去重存储。
+     *
+     * @param categorySet 用于存储品类对象的Set集合，通过引用传递，在递归过程中不断添加品类对象进去，实现去重和收集所有相关品类的功能。
+     * @param categoryId  当前要查找子品类的品类的ID，若为null则该递归分支结束（作为停止条件之一）。
+     * @return 返回最终收集了自身及所有子品类对象的Set集合，方便外层方法进一步处理。
+     */
+    private Set<Category> findChildCategory(Set<Category> categorySet, Integer categoryId) {
+        // 4、如果自己不为空的话，首先把自己添加进去；如果自己为空，这个递归分支就结束，所以也是一个停止条件
         Category category = categoryMapper.selectByPrimaryKey(categoryId);
-        if(category != null){
+        if (category!= null) {
             categorySet.add(category);
         }
-        //5、根据父亲id获取下一级所有品类（即先获取儿子们）
+        // 5、根据父亲id获取下一级所有品类（即先获取儿子们）
         List<Category> categoryList = categoryMapper.selectCategoryChildrenByParentId(categoryId);
-        //6、根据每一个儿子再获取儿子的儿子们，递归下去
-        for(Category categoryItem:categoryList){
-            findChildCategory(categorySet,categoryItem.getId());
+        // 6、根据每一个儿子再获取儿子的儿子们，递归下去
+        for (Category categoryItem : categoryList) {
+            findChildCategory(categorySet, categoryItem.getId());
         }
         return categorySet;
     }
 
-
+    /**
+     * 获取品类详细信息的业务方法，根据传入的品类ID获取对应品类的详细信息。
+     *
+     * @param categoryId 要获取详细信息的品类的ID，若为null则表示参数不合法。
+     * @return ServerResponse类型的结果，若获取成功则返回包含品类对象的成功响应，若品类不存在则返回包含相应提示消息的失败响应，若参数不合法则返回包含相应提示消息的失败响应。
+     */
     @Override
     public ServerResponse getCategoryDetail(Integer categoryId) {
-        if(categoryId == null){
+        if (categoryId == null) {
             return ServerResponse.createByErrorMessage("参数不能为空");
         }
         Category category = categoryMapper.selectByPrimaryKey(categoryId);
-        if(category == null){
+        if (category == null) {
             return ServerResponse.createByErrorMessage("品类不存在");
         }
         return ServerResponse.createBySuccess(category);
     }
-
-}
+}

snailmall-category-service/src/main/java/com/njupt/swg/service/ICategoryService.java

@@ -4,6 +4,9 @@ import com.njupt.swg.common.resp.ServerResponse;
 import com.njupt.swg.entity.Category;
 
 /**
+ * 该接口ICategoryService定义了与品类相关的一系列业务操作方法，作为服务层的接口，它规定了品类业务逻辑的抽象方法签名，
+ * 具体的业务实现将由实现该接口的类（如CategoryServiceImpl）来完成。这样的设计符合面向接口编程的原则，便于代码的解耦和替换实现类等操作，
+ * 不同的实现类可以根据具体需求（例如不同的数据库存储方式、业务规则变化等）来实现这些方法，而对于调用者来说只需要依赖这个接口即可。
  * @Author swg.
  * @Date 2019/1/2 12:54
  * @CONTACT 317758022@qq.com
@@ -11,19 +14,50 @@ import com.njupt.swg.entity.Category;
  */
 public interface ICategoryService {
 
-    /** 根据类目id获取其下面所有的一级子类目 **/
+    /**
+     * 根据类目id获取其下面所有的一级子类目方法声明。
+     * 通过传入的品类ID，查询并返回该品类下的所有一级子品类信息，返回结果使用ServerResponse进行封装，方便统一处理响应状态、提示消息以及实际数据内容。
+     * @param categoryId 用于指定要获取子品类的那个品类的唯一标识，即类目ID。
+     * @return 返回一个ServerResponse对象，若查询成功，其内部包含查询到的一级子品类相关数据（例如子品类列表等），若出现异常等情况则包含相应的错误提示信息等内容。
+     */
     ServerResponse getCategory(Integer categoryId);
 
-    /** 新建一个商品类目 **/
+    /**
+     * 新建一个商品类目方法声明。
+     * 根据传入的品类名称和父品类的ID，创建一个新的商品类目信息并保存到相关的数据存储中（通常是数据库），返回结果使用ServerResponse进行封装，
+     * 以告知调用者操作是否成功以及相关的提示消息等情况。
+     * @param categoryName 要创建的商品类目的名称，用于标识该新品类的名字信息。
+     * @param parentId 要创建的商品类目的父品类的ID，用于确定新品类在品类层级结构中的所属位置，若为特定值（如0等）可能表示顶级品类无父品类等情况。
+     * @return 返回一个ServerResponse对象，若创建成功，其内部包含表示成功的提示消息等内容，若创建失败则包含相应的失败提示消息等情况。
+     */
     ServerResponse addCategory(String categoryName, int parentId);
 
-    /** 更新品类名称 **/
+    /**
+     * 更新品类名称方法声明。
+     * 通过传入的新的品类名称和要更新的品类的ID，更新对应品类在数据存储（如数据库）中的名称信息，返回结果使用ServerResponse<String>进行封装，
+     * 这里的泛型<String>可能表示返回一些与更新操作相关的额外字符串信息（比如更新成功的详细说明、失败原因等，具体由实现类决定），同时也包含操作是否成功的状态等信息。
+     * @param categoryName 要更新成的新的品类名称，是更新操作的关键数据，决定了品类最终呈现的名称内容。
+     * @param categoryId 要进行名称更新的品类的唯一标识，用于定位到具体要修改的品类记录。
+     * @return 返回一个ServerResponse<String>对象，若更新成功，其内部包含表示成功的提示消息等内容，若更新失败则包含相应的失败提示消息等情况，同时可能包含相关的额外字符串信息。
+     */
     ServerResponse<String> updateCategoryName(String categoryName, Integer categoryId);
 
-    /** 递归查询出所有品类 **/
+    /**
+     * 递归查询出所有品类方法声明。
+     * 根据传入的品类ID，递归地查询出该品类及其所有层级的子品类信息，返回结果使用ServerResponse进行封装，方便调用者获取和处理查询到的品类相关数据，
+     * 以及知晓操作是否成功等整体情况。
+     * @param categoryId 用于指定从哪个品类开始进行递归查询，即起始品类的唯一标识，若为特定值（如null等，具体由实现类约定）可能有不同的处理逻辑等情况。
+     * @return 返回一个ServerResponse对象，若查询成功，其内部包含查询到的品类相关数据（例如品类ID列表等，具体由实现类决定返回的数据内容），若出现异常等情况则包含相应的错误提示信息等内容。
+     */
     ServerResponse selectCategoryAndDeepChildrenById(Integer categoryId);
 
 
-    /** 被其他服务调用的接口 **/
+    /**
+     * 被其他服务调用的接口方法声明。
+     * 通过传入的品类ID，获取该品类的详细信息，返回结果使用ServerResponse进行封装，便于其他服务获取品类详细情况以及判断操作是否成功等，
+     * 该接口主要用于对外提供品类详细信息的获取功能，供其他相关服务使用。
+     * @param categoryId 用于指定要获取详细信息的品类的唯一标识，通过该ID定位到具体的品类记录获取详细内容。
+     * @return 返回一个ServerResponse对象，若获取成功，其内部包含查询到的品类详细数据（例如品类对象等，具体由实现类决定返回的数据内容），若出现异常等情况则包含相应的错误提示信息等内容。
+     */
     ServerResponse getCategoryDetail(Integer categoryId);
-}
+}