Module bus.starter
Package org.miaixz.bus.spring

Class ContextBuilder

java.lang.Object
org.springframework.web.util.WebUtils
org.miaixz.bus.spring.ContextBuilder
public class ContextBuilder extends org.springframework.web.util.WebUtils
HTTP 请求、用户信息等的便捷操作工具类

使用 CacheX 接口实现缓存功能，支持延迟初始化和运行时替换。优化了请求获取和上下文管理，提供从多种来源获取参数的功能。

Since:
Java 17+
Author:
Kimi Liu

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static ContextProvider
    provider
    租户 ID 提供者实例

    Fields inherited from class org.springframework.web.util.WebUtils

    CONTENT_TYPE_CHARSET_PREFIX, DEFAULT_CHARACTER_ENCODING, DEFAULT_WEB_APP_ROOT_KEY, ERROR_EXCEPTION_ATTRIBUTE, ERROR_EXCEPTION_TYPE_ATTRIBUTE, ERROR_MESSAGE_ATTRIBUTE, ERROR_REQUEST_URI_ATTRIBUTE, ERROR_SERVLET_NAME_ATTRIBUTE, ERROR_STATUS_CODE_ATTRIBUTE, FORWARD_CONTEXT_PATH_ATTRIBUTE, FORWARD_PATH_INFO_ATTRIBUTE, FORWARD_QUERY_STRING_ATTRIBUTE, FORWARD_REQUEST_URI_ATTRIBUTE, FORWARD_SERVLET_PATH_ATTRIBUTE, HTML_ESCAPE_CONTEXT_PARAM, INCLUDE_CONTEXT_PATH_ATTRIBUTE, INCLUDE_PATH_INFO_ATTRIBUTE, INCLUDE_QUERY_STRING_ATTRIBUTE, INCLUDE_REQUEST_URI_ATTRIBUTE, INCLUDE_SERVLET_PATH_ATTRIBUTE, RESPONSE_ENCODED_HTML_ESCAPE_CONTEXT_PARAM, SESSION_MUTEX_ATTRIBUTE, SUBMIT_IMAGE_SUFFIXES, TEMP_DIR_CONTEXT_ATTRIBUTE, WEB_APP_ROOT_KEY_PARAM

  • Constructor Summary

    Constructors
    Constructor
    Description
    ContextBuilder()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    clear()
    清除请求上下文
    static void
    clear(String requestId)
    清除指定请求的缓存
    static String
    extractValueFromJson(String json, String key)
    从 JSON 字符串中提取指定键的值
    static org.miaixz.bus.core.basic.entity.Authorize
    getAuthorize()
    获取当前用户信息
    static org.miaixz.bus.cache.CacheX<String,String>
    getBodyCache()
    获取 JSON 请求体缓存实例
    static boolean
    getBooleanValue(String key, boolean defaultValue)
    获取布尔型参数值
    static String
    getCookieValue(String key)
    从 Cookie 中获取指定键的值
    static double
    getDoubleValue(String key, double defaultValue)
    获取双精度浮点型参数值
    static org.miaixz.bus.cache.CacheX<String,Map<String,String>>
    getHeaderCache()
    获取请求头缓存实例
    static Map<String,String>
    getHeaders()
    获取 HTTP 请求的所有 Header
    static String
    getHeaderValue(String key)
    从请求头中获取指定键的值
    static int
    getIntValue(String key, int defaultValue)
    获取整型参数值
    static String
    getJsonBodyValue(String key)
    从 JSON 请求体中获取指定键的值
    static <T> T
    getJsonValue(String key, Class<T> clazz)
    获取 JSON 对象参数值
    static long
    getLongValue(String key, long defaultValue)
    获取长整型参数值
    static String
    getMultipartParameterValue(String key)
    从文件上传请求中获取指定键的值
    static org.miaixz.bus.cache.CacheX<String,Map<String,String>>
    getParameterCache()
    获取请求参数缓存实例
    static Map<String,String>
    getParameters()
    获取 HTTP 请求的所有参数
    static String
    getParameterValue(String key)
    从请求参数中获取指定键的值
    static String
    getPathVariable(String key)
    从路径变量中获取指定键的值
    static jakarta.servlet.http.HttpServletRequest
    getRequest()
    获取当前 HTTP 请求对象
    static String
    getRequestId()
    获取当前请求 ID
    static String
    getTenantId()
    获取租户 ID
    static <T> T
    getValue(String key, Class<T> clazz)
    获取指定类型的参数值
    static String
    getValue(String key, org.miaixz.bus.core.lang.EnumValue.Params source)
    从指定来源获取参数值
    static String
    getValueFromJsonBody(String key)
    从 JSON 请求体中获取指定键的值
    static boolean
    isMultipartContent(jakarta.servlet.http.HttpServletRequest request)
    检查请求是否包含文件上传
    static void
    reset()
    重置所有缓存实例
    static void
    setBodyCache(org.miaixz.bus.cache.CacheX<String,String> cache)
    设置 JSON 请求体缓存实现
    static void
    setHeaderCache(org.miaixz.bus.cache.CacheX<String,Map<String,String>> cache)
    设置请求头缓存实现
    static void
    setParameterCache(org.miaixz.bus.cache.CacheX<String,Map<String,String>> cache)
    设置请求参数缓存实现
    static void
    setProvider(ContextProvider provider)
    设置用户信息提供者
    static void
    setRequestId()
    初始化请求上下文

    Methods inherited from class org.springframework.web.util.WebUtils

    clearErrorRequestAttributes, exposeErrorRequestAttributes, findParameterValue, findParameterValue, getCookie, getDefaultHtmlEscape, getNativeRequest, getNativeResponse, getParametersStartingWith, getRealPath, getRequiredSessionAttribute, getResponseEncodedHtmlEscape, getSessionAttribute, getSessionId, getSessionMutex, getTempDir, hasSubmitParameter, isIncludeRequest, isSameOrigin, isValidOrigin, parseMatrixVariables, removeWebAppRootSystemProperty, setSessionAttribute, setWebAppRootSystemProperty

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • provider

      public static volatile ContextProvider provider
      租户 ID 提供者实例

  • Constructor Details

    • ContextBuilder

      public ContextBuilder()

  • Method Details

    • setProvider

      public static void setProvider(ContextProvider provider)
      设置用户信息提供者

      配置自定义用户信息提供者，用于获取用户授权信息。 

      
 ContextProvider customProvider = new CustomContextProvider();
 ContextBuilder.setProvider(customProvider);
      Parameters:
      provider - 用户信息提供者

    • setRequestId

      public static void setRequestId()
      初始化请求上下文

      为当前请求生成新的请求 ID 并存储在 ThreadLocal 中。 

      
 HttpServletRequest request = getRequest();
 ContextBuilder.setRequestId();

    • getRequestId

      public static String getRequestId()
      获取当前请求 ID

      返回当前线程的请求 ID，如果不存在则生成新的 ID。 

      
 String requestId = ContextBuilder.getRequestId();
 if (requestId != null) {
     System.out.println("请求ID: " + requestId);
 }
      Returns:
      请求 ID，或 null 如果无法获取

    • getRequest

      public static jakarta.servlet.http.HttpServletRequest getRequest()
      获取当前 HTTP 请求对象

      从 RequestContextHolder 获取当前 HTTP 请求的 ServletRequestAttributes。 

      
 HttpServletRequest request = ContextBuilder.getRequest();
 if (request != null) {
     System.out.println("请求URI: " + request.getRequestURI());
 }
      Returns:
      HttpServletRequest 对象，或 null 如果无法获取

    • getHeaderCache

      public static org.miaixz.bus.cache.CacheX<String,Map<String,String>> getHeaderCache()
      获取请求头缓存实例

      返回延迟初始化的请求头缓存实例，优先使用 CaffeineCache，失败时回退到 MemoryCache。 

      
 CacheX<String, Map<String, String>> cache = ContextBuilder.getHeaderCache();
 Map<String, String> headers = cache.read("request123");
      Returns:
      请求头缓存实例

    • getParameterCache

      public static org.miaixz.bus.cache.CacheX<String,Map<String,String>> getParameterCache()
      获取请求参数缓存实例

      返回延迟初始化的请求参数缓存实例，优先使用 CaffeineCache，失败时回退到 MemoryCache。 

      
 CacheX<String, Map<String, String>> cache = ContextBuilder.getParameterCache();
 Map<String, String> params = cache.read("request123");
      Returns:
      请求参数缓存实例

    • getBodyCache

      public static org.miaixz.bus.cache.CacheX<String,String> getBodyCache()
      获取 JSON 请求体缓存实例

      返回延迟初始化的 JSON 请求体缓存实例，优先使用 CaffeineCache，失败时回退到 MemoryCache。 

      
 CacheX<String, String> cache = ContextBuilder.getBodyCache();
 String jsonBody = cache.read("request123");
      Returns:
      JSON 请求体缓存实例

    • setHeaderCache

      public static void setHeaderCache(@NonNull org.miaixz.bus.cache.CacheX<String,Map<String,String>> cache)
      设置请求头缓存实现

      配置自定义的请求头缓存实现。 

      
 CacheX<String, Map<String, String>> customCache = new CustomCacheImpl<>();
 ContextBuilder.setHeaderCache(customCache);
      Parameters:
      cache - 缓存实现

    • setParameterCache

      public static void setParameterCache(@NonNull org.miaixz.bus.cache.CacheX<String,Map<String,String>> cache)
      设置请求参数缓存实现

      配置自定义的请求参数缓存实现。 

      
 CacheX<String, Map<String, String>> customCache = new CustomCacheImpl<>();
 ContextBuilder.setParameterCache(customCache);
      Parameters:
      cache - 缓存实现

    • setBodyCache

      public static void setBodyCache(@NonNull org.miaixz.bus.cache.CacheX<String,String> cache)
      设置 JSON 请求体缓存实现

      配置自定义作为 JSON 请求体缓存实现。 

      
 CacheX<String, String> customCache = new CustomCacheImpl<>();
 ContextBuilder.setBodyCache(customCache);
      Parameters:
      cache - 缓存实现

    • getHeaders

      public static Map<String,String> getHeaders()
      获取 HTTP 请求的所有 Header

      从请求中获取所有请求头，优先从缓存读取，缓存未命中时从请求中获取并存入缓存。 

      
 Map<String, String> headers = ContextBuilder.getHeaders();
 System.out.println("请求头: " + headers);
      Returns:
      请求头键值对映射（大小写不敏感）

    • getParameters

      public static Map<String,String> getParameters()
      获取 HTTP 请求的所有参数

      从请求中获取所有请求参数，优先从缓存读取，缓存未命中时从请求中获取并存入缓存。 

      
 Map<String, String> params = ContextBuilder.getParameters();
 System.out.println("请求参数: " + params);
      Returns:
      请求参数键值对映射（大小写不敏感）

    • getValueFromJsonBody

      public static String getValueFromJsonBody(String key)
      从 JSON 请求体中获取指定键的值

      从请求中获取 JSON 请求体，优先从缓存读取，缓存未命中时从请求中读取并存入缓存。 

      
 String value = ContextBuilder.getValueFromJsonBody("userId");
 if (value != null) {
     System.out.println("JSON 值: " + value);
 }
      Parameters:
      key - 键名
      Returns:
      JSON 请求体中指定键的值，或 null 如果未找到或非 JSON 请求

    • extractValueFromJson

      public static String extractValueFromJson(String json, String key)
      从 JSON 字符串中提取指定键的值

      尝试解析 JSON 字符串并提取指定键的值，支持 Map 解析或直接字段提取。 

      
 String json = "{\"userId\": \"123\"}";
 String value = ContextBuilder.extractValueFromJson(json, "userId");
 System.out.println("提取值: " + value);
      Parameters:
      json - JSON 字符串
      key - 键名
      Returns:
      提取的值，或 null 如果未找到

    • getHeaderValue

      @Nullable public static String getHeaderValue(@Nullable String key)
      从请求头中获取指定键的值

      从请求头映射中获取指定键的值。 

      
 String value = ContextBuilder.getHeaderValue("x-user-id");
 if (value != null) {
     System.out.println("请求头值: " + value);
 }
      Parameters:
      key - 键名
      Returns:
      请求头中指定键的值，或 null 如果未找到

    • getParameterValue

      @Nullable public static String getParameterValue(@Nullable String key)
      从请求参数中获取指定键的值

      从请求参数映射中获取指定键的值，包括表单和 URL 参数。 

      
 String value = ContextBuilder.getParameterValue("userId");
 if (value != null) {
     System.out.println("参数值: " + value);
 }
      Parameters:
      key - 键名
      Returns:
      请求参数中指定键的值，或 null 如果未找到

    • getJsonBodyValue

      @Nullable public static String getJsonBodyValue(@Nullable String key)
      从 JSON 请求体中获取指定键的值

      从 JSON 请求体中提取指定键的值。 

      
 String value = ContextBuilder.getJsonBodyValue("userId");
 if (value != null) {
     System.out.println("JSON 值: " + value);
 }
      Parameters:
      key - 键名
      Returns:
      JSON 请求体中指定键的值，或 null 如果未找到

    • getCookieValue

      @Nullable public static String getCookieValue(@Nullable String key)
      从 Cookie 中获取指定键的值

      从 HTTP 请求的 Cookie 中获取指定键的值。 

      
 String value = ContextBuilder.getCookieValue("sessionId");
 if (value != null) {
     System.out.println("Cookie 值: " + value);
 }
      Parameters:
      key - 键名
      Returns:
      Cookie 中指定键的值，或 null 如果未找到

    • getPathVariable

      @Nullable public static String getPathVariable(@Nullable String key)
      从路径变量中获取指定键的值

      从 HTTP 请求的路径变量中获取指定键的值。 

      
 String value = ContextBuilder.getPathVariable("userId");
 if (value != null) {
     System.out.println("路径变量值: " + value);
 }
      Parameters:
      key - 键名
      Returns:
      路径变量中指定键的值，或 null 如果未找到

    • getMultipartParameterValue

      @Nullable public static String getMultipartParameterValue(@Nullable String key)
      从文件上传请求中获取指定键的值

      从 multipart 请求的表单字段中获取指定键的值。 

      
 String value = ContextBuilder.getMultipartParameterValue("fileDesc");
 if (value != null) {
     System.out.println("文件描述: " + value);
 }
      Parameters:
      key - 键名
      Returns:
      文件上传请求中指定键的值，或 null 如果未找到

    • getValue

      @Nullable public static String getValue(@Nullable String key, @NonNull org.miaixz.bus.core.lang.EnumValue.Params source)
      从指定来源获取参数值

      根据指定的参数来源（如请求头、参数、JSON 请求体等）获取键值。 

      
 String value = ContextBuilder.getValue("userId", EnumValue.Params.HEADER);
 if (value != null) {
     System.out.println("值: " + value);
 }
      Parameters:
      key - 键名
      source - 参数来源
      Returns:
      参数值，或 null 如果未找到

    • getIntValue

      public static int getIntValue(@Nullable String key, int defaultValue)
      获取整型参数值

      从所有来源获取指定键的整型值，失败时返回默认值。 

      
 int value = ContextBuilder.getIntValue("age", 0);
 System.out.println("年龄: " + value);
      Parameters:
      key - 键名
      defaultValue - 默认值
      Returns:
      整型参数值

    • getLongValue

      public static long getLongValue(@Nullable String key, long defaultValue)
      获取长整型参数值

      从所有来源获取指定键的长整型值，失败时返回默认值。 

      
 long value = ContextBuilder.getLongValue("timestamp", 0L);
 System.out.println("时间戳: " + value);
      Parameters:
      key - 键名
      defaultValue - 默认值
      Returns:
      长整型参数值

    • getBooleanValue

      public static boolean getBooleanValue(@Nullable String key, boolean defaultValue)
      获取布尔型参数值

      从所有来源获取指定键的布尔型值，失败时返回默认值。 

      
 boolean value = ContextBuilder.getBooleanValue("isActive", false);
 System.out.println("是否激活: " + value);
      Parameters:
      key - 键名
      defaultValue - 默认值
      Returns:
      布尔型参数值

    • getDoubleValue

      public static double getDoubleValue(@Nullable String key, double defaultValue)
      获取双精度浮点型参数值

      从所有来源获取指定键的双精度浮点值，失败时返回默认值。 

      
 double value = ContextBuilder.getDoubleValue("price", 0.0);
 System.out.println("价格: " + value);
      Parameters:
      key - 键名
      defaultValue - 默认值
      Returns:
      双精度浮点型参数值

    • getValue

      @Nullable public static <T> T getValue(@Nullable String key, @NonNull Class<T> clazz)
      获取指定类型的参数值

      从所有来源获取指定键的值并转换为目标类型，失败时返回 null。 

      
 Integer value = ContextBuilder.getValue("age", Integer.class);
 if (value != null) {
     System.out.println("年龄: " + value);
 }
      Type Parameters:
      T - 泛型类型
      Parameters:
      key - 键名
      clazz - 目标类型
      Returns:
      指定类型的参数值，或 null 如果未找到或转换失败

    • getJsonValue

      @Nullable public static <T> T getJsonValue(@Nullable String key, @NonNull Class<T> clazz)
      获取 JSON 对象参数值

      从 JSON 请求体中获取指定键的值并转换为目标类型。 

      
 User user = ContextBuilder.getJsonValue("user", User.class);
 if (user != null) {
     System.out.println("用户: " + user.getName());
 }
      Type Parameters:
      T - 泛型类型
      Parameters:
      key - 键名
      clazz - 目标类型
      Returns:
      指定类型的参数值，或 null 如果未找到或转换失败

    • getAuthorize

      public static org.miaixz.bus.core.basic.entity.Authorize getAuthorize()
      获取当前用户信息

      从自定义提供者或请求头、上下文中的用户 ID 获取授权信息。 

      
 Authorize auth = ContextBuilder.getAuthorize();
 if (auth != null) {
     System.out.println("用户ID: " + auth.getX_user_id());
 }
      Returns:
      Authorize 对象，或 null 如果无法获取

    • getTenantId

      public static String getTenantId()
      获取租户 ID

      按优先级从用户授权数据、请求头、请求参数、JSON 请求体或上下文获取租户 ID。 

      
 String tenantId = ContextBuilder.getTenantId();
 if (tenantId != null) {
     System.out.println("租户ID: " + tenantId);
 }
      Returns:
      租户 ID，或 null 如果未找到

    • isMultipartContent

      public static boolean isMultipartContent(jakarta.servlet.http.HttpServletRequest request)
      检查请求是否包含文件上传

      检查 HTTP 请求的 Content-Type 是否为 multipart 类型。 

      
 HttpServletRequest request = ContextBuilder.getRequest();
 boolean isMultipart = ContextBuilder.isMultipartContent(request);
 System.out.println("是否文件上传: " + isMultipart);
      Parameters:
      request - HTTP 请求对象
      Returns:
      如果是文件上传请求则返回 true，否则返回 false

    • clear

      public static void clear()
      清除请求上下文

      移除当前线程的请求 ID，并清除相关缓存。 

      
 ContextBuilder.clear();
 System.out.println("请求上下文已清除");

    • clear

      public static void clear(String requestId)
      清除指定请求的缓存

      移除指定请求 ID 的请求头、参数和 JSON 请求体缓存。 

      
 ContextBuilder.clear("request123");
 System.out.println("请求缓存已清除");
      Parameters:
      requestId - 请求 ID

    • reset

      public static void reset()
      重置所有缓存实例

      将所有缓存实例置空，用于测试或重新初始化。 

      
 ContextBuilder.reset();
 System.out.println("所有缓存实例已重置");