docs 补充客户端工具类注释

ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/utils/ServletUtils.java

@@ -25,7 +25,7 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
- * 客户端工具类
+ * 客户端工具类，提供获取请求参数、响应处理、头部信息等常用操作
  *
  * @author ruoyi
  */
@@ -33,52 +33,73 @@ import java.util.Map;
 public class ServletUtils extends JakartaServletUtil {
 
     /**
-     * 获取String参数
+     * 获取指定名称的 String 类型的请求参数
+     *
+     * @param name 参数名
+     * @return 参数值
      */
     public static String getParameter(String name) {
         return getRequest().getParameter(name);
     }
 
     /**
-     * 获取String参数
+     * 获取指定名称的 String 类型的请求参数，若参数不存在，则返回默认值
+     *
+     * @param name         参数名
+     * @param defaultValue 默认值
+     * @return 参数值或默认值
      */
     public static String getParameter(String name, String defaultValue) {
         return Convert.toStr(getRequest().getParameter(name), defaultValue);
     }
 
     /**
-     * 获取Integer参数
+     * 获取指定名称的 Integer 类型的请求参数
+     *
+     * @param name 参数名
+     * @return 参数值
      */
     public static Integer getParameterToInt(String name) {
         return Convert.toInt(getRequest().getParameter(name));
     }
 
     /**
-     * 获取Integer参数
+     * 获取指定名称的 Integer 类型的请求参数，若参数不存在，则返回默认值
+     *
+     * @param name         参数名
+     * @param defaultValue 默认值
+     * @return 参数值或默认值
      */
     public static Integer getParameterToInt(String name, Integer defaultValue) {
         return Convert.toInt(getRequest().getParameter(name), defaultValue);
     }
 
     /**
-     * 获取Boolean参数
+     * 获取指定名称的 Boolean 类型的请求参数
+     *
+     * @param name 参数名
+     * @return 参数值
      */
     public static Boolean getParameterToBool(String name) {
         return Convert.toBool(getRequest().getParameter(name));
     }
 
     /**
-     * 获取Boolean参数
+     * 获取指定名称的 Boolean 类型的请求参数，若参数不存在，则返回默认值
+     *
+     * @param name         参数名
+     * @param defaultValue 默认值
+     * @return 参数值或默认值
      */
     public static Boolean getParameterToBool(String name, Boolean defaultValue) {
         return Convert.toBool(getRequest().getParameter(name), defaultValue);
     }
 
     /**
-     * 获得所有请求参数
+     * 获取所有请求参数（以 Map 的形式返回）
      *
      * @param request 请求对象{@link ServletRequest}
-     * @return Map
+     * @return 请求参数的 Map，键为参数名，值为参数值数组
      */
     public static Map<String, String[]> getParams(ServletRequest request) {
         final Map<String, String[]> map = request.getParameterMap();
@@ -86,10 +107,10 @@ public class ServletUtils extends JakartaServletUtil {
     }
 
     /**
-     * 获得所有请求参数
+     * 获取所有请求参数（以 Map 的形式返回，值为字符串形式的拼接）
      *
      * @param request 请求对象{@link ServletRequest}
-     * @return Map
+     * @return 请求参数的 Map，键为参数名，值为拼接后的字符串
      */
     public static Map<String, String> getParamMap(ServletRequest request) {
         Map<String, String> params = new HashMap<>();
@@ -100,7 +121,9 @@ public class ServletUtils extends JakartaServletUtil {
     }
 
     /**
-     * 获取request
+     * 获取当前 HTTP 请求对象
+     *
+     * @return 当前 HTTP 请求对象
      */
     public static HttpServletRequest getRequest() {
         try {
@@ -111,7 +134,9 @@ public class ServletUtils extends JakartaServletUtil {
     }
 
     /**
-     * 获取response
+     * 获取当前 HTTP 响应对象
+     *
+     * @return 当前 HTTP 响应对象
      */
     public static HttpServletResponse getResponse() {
         try {
@@ -122,12 +147,25 @@ public class ServletUtils extends JakartaServletUtil {
     }
 
     /**
-     * 获取session
+     * 获取当前请求的 HttpSession 对象
+     * <p>
+     * 如果当前请求已经关联了一个会话（即已经存在有效的 session ID），
+     * 则返回该会话对象；如果没有关联会话，则会创建一个新的会话对象并返回。
+     * <p>
+     * HttpSession 用于存储会话级别的数据，如用户登录信息、购物车内容等，
+     * 可以在多个请求之间共享会话数据
+     *
+     * @return 当前请求的 HttpSession 对象
      */
     public static HttpSession getSession() {
         return getRequest().getSession();
     }
 
+    /**
+     * 获取当前请求的请求属性
+     *
+     * @return {@link ServletRequestAttributes} 请求属性对象
+     */
     public static ServletRequestAttributes getRequestAttributes() {
         try {
             RequestAttributes attributes = RequestContextHolder.getRequestAttributes();
@@ -137,6 +175,13 @@ public class ServletUtils extends JakartaServletUtil {
         }
     }
 
+    /**
+     * 获取指定请求头的值，如果头部为空则返回空字符串
+     *
+     * @param request 请求对象
+     * @param name    头部名称
+     * @return 头部值
+     */
     public static String getHeader(HttpServletRequest request, String name) {
         String value = request.getHeader(name);
         if (StringUtils.isEmpty(value)) {
@@ -145,6 +190,12 @@ public class ServletUtils extends JakartaServletUtil {
         return urlDecode(value);
     }
 
+    /**
+     * 获取所有请求头的 Map，键为头部名称，值为头部值
+     *
+     * @param request 请求对象
+     * @return 请求头的 Map
+     */
     public static Map<String, String> getHeaders(HttpServletRequest request) {
         Map<String, String> map = new LinkedCaseInsensitiveMap<>();
         Enumeration<String> enumeration = request.getHeaderNames();
@@ -159,7 +210,7 @@ public class ServletUtils extends JakartaServletUtil {
     }
 
     /**
-     * 将字符串渲染到客户端
+     * 将字符串渲染到客户端（以 JSON 格式返回）
      *
      * @param response 渲染对象
      * @param string   待渲染的字符串
@@ -176,37 +227,47 @@ public class ServletUtils extends JakartaServletUtil {
     }
 
     /**
-     * 是否是Ajax异步请求
+     * 判断当前请求是否为 Ajax 异步请求
      *
-     * @param request
+     * @param request 请求对象
+     * @return 是否为 Ajax 请求
      */
     public static boolean isAjaxRequest(HttpServletRequest request) {
 
+        // 判断 Accept 头部是否包含 application/json
         String accept = request.getHeader("accept");
         if (accept != null && accept.contains(MediaType.APPLICATION_JSON_VALUE)) {
             return true;
         }
 
+        // 判断 X-Requested-With 头部是否包含 XMLHttpRequest
         String xRequestedWith = request.getHeader("X-Requested-With");
         if (xRequestedWith != null && xRequestedWith.contains("XMLHttpRequest")) {
             return true;
         }
 
+        // 判断 URI 后缀是否为 .json 或 .xml
         String uri = request.getRequestURI();
         if (StringUtils.equalsAnyIgnoreCase(uri, ".json", ".xml")) {
             return true;
         }
 
+        // 判断请求参数 __ajax 是否为 json 或 xml
         String ajax = request.getParameter("__ajax");
         return StringUtils.equalsAnyIgnoreCase(ajax, "json", "xml");
     }
 
+    /**
+     * 获取客户端 IP 地址
+     *
+     * @return 客户端 IP 地址
+     */
     public static String getClientIP() {
         return getClientIP(getRequest());
     }
 
     /**
-     * 内容编码
+     * 对内容进行 URL 编码
      *
      * @param str 内容
      * @return 编码后的内容
@@ -216,7 +277,7 @@ public class ServletUtils extends JakartaServletUtil {
     }
 
     /**
-     * 内容解码
+     * 对内容进行 URL 解码
      *
      * @param str 内容
      * @return 解码后的内容