Class SafePathUtil

java.lang.Object
cloud.opencode.base.image.security.SafePathUtil
public final class SafePathUtil extends Object
Safe Path Util 安全路径工具类

Utilities for validating and sanitizing file paths for image operations.

用于验证和清理图片操作文件路径的工具类。

Usage Examples | 使用示例:

// Validate path
SafePathUtil.validatePath(path);

// Check for path traversal
boolean safe = SafePathUtil.isSafePath(path, baseDir);

// Sanitize filename
String safe = SafePathUtil.sanitizeFilename("../evil.jpg");

Features | 主要功能:

  • Path traversal attack prevention - 路径遍历攻击防护
  • Filename sanitization - 文件名清理
  • Image file extension validation - 图片文件扩展名验证

Security | 安全性:

  • Thread-safe: Yes (stateless utility) - 线程安全: 是（无状态工具）
  • Null-safe: No (throws on null path) - 空值安全: 否（null 路径抛异常）

Performance | 性能特性:

  • Time complexity: O(m) where m is the filename length - regex matching and string replacement scan the filename once - 时间复杂度: O(m)，m 为文件名长度 - 正则匹配和字符串替换对文件名各扫描一次
  • Space complexity: O(m) - sanitized string proportional to filename length - 空间复杂度: O(m) - 清理后的字符串与文件名长度成正比
Since:
JDK 25, opencode-base-image V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • validatePath

      public static void validatePath(Path path) throws ImageValidationException
      Validate path for image operations 验证图片操作的路径
      Parameters:
      path - the path to validate | 要验证的路径
      Throws:
      ImageValidationException - if path is invalid | 如果路径无效

    • validatePath

      public static void validatePath(Path path, Path baseDir) throws ImageValidationException
      Validate path within base directory 在基础目录内验证路径
      Parameters:
      path - the path to validate | 要验证的路径
      baseDir - the base directory | 基础目录
      Throws:
      ImageValidationException - if path is outside base dir | 如果路径在基础目录之外

    • isSafePath

      public static boolean isSafePath(Path path, Path baseDir)
      Check if path is safe (within base directory) 检查路径是否安全（在基础目录内）
      Parameters:
      path - the path to check | 要检查的路径
      baseDir - the base directory | 基础目录
      Returns:
      true if path is safe | 如果路径安全返回true

    • sanitizeFilename

      public static String sanitizeFilename(String filename)
      Sanitize filename for safe storage 清理文件名以安全存储
      Parameters:
      filename - the original filename | 原始文件名
      Returns:
      the sanitized filename | 清理后的文件名

    • getExtension

      public static String getExtension(String filename)
      Get file extension 获取文件扩展名
      Parameters:
      filename - the filename | 文件名
      Returns:
      the extension (without dot) | 扩展名（不含点）

    • isAllowedExtension

      public static boolean isAllowedExtension(String extension)
      Check if extension is allowed 检查扩展名是否允许
      Parameters:
      extension - the extension to check | 要检查的扩展名
      Returns:
      true if allowed | 如果允许返回true

    • getFormat

      public static ImageFormat getFormat(Path path)
      Get format from path 从路径获取格式
      Parameters:
      path - the file path | 文件路径
      Returns:
      the image format or null | 图片格式或null

    • generateOutputPath

      public static Path generateOutputPath(Path inputPath, String suffix)
      Generate safe output path 生成安全的输出路径
      Parameters:
      inputPath - the input path | 输入路径
      suffix - the suffix to add | 要添加的后缀
      Returns:
      the output path | 输出路径

    • generateOutputPath

      public static Path generateOutputPath(Path inputPath, ImageFormat format)
      Generate safe output path with new format 生成带新格式的安全输出路径
      Parameters:
      inputPath - the input path | 输入路径
      format - the new format | 新格式
      Returns:
      the output path | 输出路径

    • ensureParentExists

      public static boolean ensureParentExists(Path path)
      Ensure parent directory exists 确保父目录存在
      Parameters:
      path - the file path | 文件路径
      Returns:
      true if directory exists or was created | 如果目录存在或已创建返回true