update 增加多个方法的注释以提升代码可读性

2026-06-18 03:34:27 +00:00 · 2026-05-15 13:04:30 +08:00
parent 592d998e0f
commit 4fdf2ea75a
25 changed files with 514 additions and 6 deletions
@@ -135,6 +135,12 @@ public enum FormatsType {
     */
    private final String timeFormat;

+    /**
+     * 根据字符串内容匹配时间格式类型。
+     *
+     * @param str 字符串内容
+     * @return 时间格式类型
+     */
    public static FormatsType getFormatsType(String str) {
        for (FormatsType value : values()) {
            if (StringUtils.contains(str, value.getTimeFormat())) {
@@ -60,6 +60,11 @@ public final class SpringUtils extends SpringUtil {
        return getApplicationContext();
    }

+    /**
+     * 当前是否启用虚拟线程。
+     *
+     * @return true 启用 false 未启用
+     */
    public static boolean isVirtual() {
        return Threading.VIRTUAL.isActive(getBean(Environment.class));
    }
@@ -21,6 +21,12 @@ public class AddressUtils {
    // 内网地址
    public static final String LOCAL_ADDRESS = "内网IP";

+    /**
+     * 根据 IP 查询真实地址。
+     *
+     * @param ip IP 地址
+     * @return 真实地址
+     */
    public static String getRealAddressByIP(String ip) {
        // 处理空串并过滤HTML标签
        ip = HtmlUtil.cleanHtmlTag(StringUtils.blankToDefault(ip,""));
@@ -33,6 +33,13 @@ public class CellMergeHandler {
        this.hasTitle = hasTitle;
        this.rowIndex = hasTitle ? rowIndex : 0;
    }
+
+    /**
+     * 计算需要合并的单元格区域。
+     *
+     * @param rows 数据行
+     * @return 单元格合并区域列表
+     */
    @SneakyThrows
    public List<CellRangeAddress> handle(List<?> rows) {
        // 如果入参为空集合则返回空集
@@ -22,38 +22,95 @@ import java.util.function.Supplier;
 */
 public record ExcelWriterWrapper<T>(ExcelWriter excelWriter) {

+    /**
+     * 写出集合数据到指定工作表。
+     *
+     * @param data       数据集合
+     * @param writeSheet 工作表
+     */
    public void write(Collection<T> data, WriteSheet writeSheet) {
        excelWriter.write(data, writeSheet);
    }

+    /**
+     * 通过数据提供器写出集合数据到指定工作表。
+     *
+     * @param supplier   数据提供器
+     * @param writeSheet 工作表
+     */
    public void write(Supplier<Collection<T>> supplier, WriteSheet writeSheet) {
        excelWriter.write(supplier.get(), writeSheet);
    }

+    /**
+     * 写出集合数据到指定工作表和表格。
+     *
+     * @param data       数据集合
+     * @param writeSheet 工作表
+     * @param writeTable 表格
+     */
    public void write(Collection<T> data, WriteSheet writeSheet, WriteTable writeTable) {
        excelWriter.write(data, writeSheet, writeTable);
    }

+    /**
+     * 通过数据提供器写出集合数据到指定工作表和表格。
+     *
+     * @param supplier   数据提供器
+     * @param writeSheet 工作表
+     * @param writeTable 表格
+     */
    public void write(Supplier<Collection<T>> supplier, WriteSheet writeSheet, WriteTable writeTable) {
        excelWriter.write(supplier.get(), writeSheet, writeTable);
    }

+    /**
+     * 填充数据到指定工作表。
+     *
+     * @param data       填充数据
+     * @param writeSheet 工作表
+     */
    public void fill(Object data, WriteSheet writeSheet) {
        excelWriter.fill(data, writeSheet);
    }

+    /**
+     * 按填充配置填充数据到指定工作表。
+     *
+     * @param data       填充数据
+     * @param fillConfig 填充配置
+     * @param writeSheet 工作表
+     */
    public void fill(Object data, FillConfig fillConfig, WriteSheet writeSheet) {
        excelWriter.fill(data, fillConfig, writeSheet);
    }

+    /**
+     * 通过数据提供器填充数据到指定工作表。
+     *
+     * @param supplier   数据提供器
+     * @param writeSheet 工作表
+     */
    public void fill(Supplier<Object> supplier, WriteSheet writeSheet) {
        excelWriter.fill(supplier, writeSheet);
    }

+    /**
+     * 通过数据提供器按填充配置填充数据到指定工作表。
+     *
+     * @param supplier   数据提供器
+     * @param fillConfig 填充配置
+     * @param writeSheet 工作表
+     */
    public void fill(Supplier<Object> supplier, FillConfig fillConfig, WriteSheet writeSheet) {
        excelWriter.fill(supplier, fillConfig, writeSheet);
    }

+    /**
+     * 获取写出上下文。
+     *
+     * @return 写出上下文
+     */
    public WriteContext writeContext() {
        return excelWriter.writeContext();
    }
@@ -70,34 +127,82 @@ public record ExcelWriterWrapper<T>(ExcelWriter excelWriter) {

    // -------------------------------- sheet start

+    /**
+     * 创建工作表。
+     *
+     * @param sheetNo   工作表编号
+     * @param sheetName 工作表名称
+     * @return 工作表
+     */
    public static WriteSheet buildSheet(Integer sheetNo, String sheetName) {
        return sheetBuilder(sheetNo, sheetName).build();
    }

+    /**
+     * 创建工作表。
+     *
+     * @param sheetNo 工作表编号
+     * @return 工作表
+     */
    public static WriteSheet buildSheet(Integer sheetNo) {
        return sheetBuilder(sheetNo).build();
    }

+    /**
+     * 创建工作表。
+     *
+     * @param sheetName 工作表名称
+     * @return 工作表
+     */
    public static WriteSheet buildSheet(String sheetName) {
        return sheetBuilder(sheetName).build();
    }

+    /**
+     * 创建工作表。
+     *
+     * @return 工作表
+     */
    public static WriteSheet buildSheet() {
        return sheetBuilder().build();
    }

+    /**
+     * 创建工作表构造器。
+     *
+     * @param sheetNo   工作表编号
+     * @param sheetName 工作表名称
+     * @return 工作表构造器
+     */
    public static ExcelWriterSheetBuilder sheetBuilder(Integer sheetNo, String sheetName) {
        return FesodSheet.writerSheet(sheetNo, sheetName);
    }

+    /**
+     * 创建工作表构造器。
+     *
+     * @param sheetNo 工作表编号
+     * @return 工作表构造器
+     */
    public static ExcelWriterSheetBuilder sheetBuilder(Integer sheetNo) {
        return FesodSheet.writerSheet(sheetNo);
    }

+    /**
+     * 创建工作表构造器。
+     *
+     * @param sheetName 工作表名称
+     * @return 工作表构造器
+     */
    public static ExcelWriterSheetBuilder sheetBuilder(String sheetName) {
        return FesodSheet.writerSheet(sheetName);
    }

+    /**
+     * 创建工作表构造器。
+     *
+     * @return 工作表构造器
+     */
    public static ExcelWriterSheetBuilder sheetBuilder() {
        return FesodSheet.writerSheet();
    }
@@ -106,18 +211,40 @@ public record ExcelWriterWrapper<T>(ExcelWriter excelWriter) {

    // -------------------------------- table start

+    /**
+     * 创建表格。
+     *
+     * @param tableNo 表格编号
+     * @return 表格
+     */
    public static WriteTable buildTable(Integer tableNo) {
        return tableBuilder(tableNo).build();
    }

+    /**
+     * 创建表格。
+     *
+     * @return 表格
+     */
    public static WriteTable buildTable() {
        return tableBuilder().build();
    }

+    /**
+     * 创建表格构造器。
+     *
+     * @param tableNo 表格编号
+     * @return 表格构造器
+     */
    public static ExcelWriterTableBuilder tableBuilder(Integer tableNo) {
        return FesodSheet.writerTable(tableNo);
    }

+    /**
+     * 创建表格构造器。
+     *
+     * @return 表格构造器
+     */
    public static ExcelWriterTableBuilder tableBuilder() {
        return FesodSheet.writerTable();
    }
@@ -16,15 +16,33 @@ public class JsonEnhancementContext {

    private final Map<String, Object> attributes = new LinkedHashMap<>();

+    /**
+     * 构造响应增强上下文。
+     *
+     * @param jsonMapper JSON 映射器
+     */
    public JsonEnhancementContext(JsonMapper jsonMapper) {
        this.jsonMapper = jsonMapper;
    }

+    /**
+     * 获取上下文属性。
+     *
+     * @param key 属性键
+     * @param <T> 属性值类型
+     * @return 属性值
+     */
    @SuppressWarnings("unchecked")
    public <T> T getAttribute(String key) {
        return (T) attributes.get(key);
    }

+    /**
+     * 设置上下文属性。
+     *
+     * @param key   属性键
+     * @param value 属性值
+     */
    public void setAttribute(String key, Object value) {
        attributes.put(key, value);
    }
@@ -9,6 +9,13 @@ import java.lang.annotation.Annotation;
 */
 public record JsonFieldContext(Object owner, String propertyName, AnnotatedMember member, Object value) {

+    /**
+     * 获取字段上的指定注解。
+     *
+     * @param annotationType 注解类型
+     * @param <A>            注解类型
+     * @return 注解对象
+     */
    public <A extends Annotation> A getAnnotation(Class<A> annotationType) {
        return member == null ? null : member.getAnnotation(annotationType);
    }
@@ -31,6 +31,12 @@ public class JsonValueEnhancer {

    private final Map<Class<?>, List<PropertyMetadata>> propertyCache = new ConcurrentHashMap<>();

+    /**
+     * 构造统一响应增强器。
+     *
+     * @param jsonMapper JSON 映射器
+     * @param processors 字段处理器列表
+     */
    public JsonValueEnhancer(JsonMapper jsonMapper, List<JsonFieldProcessor> processors) {
        this.jsonMapper = jsonMapper;
        List<JsonFieldProcessor> sortedProcessors = new ArrayList<>(processors);
@@ -38,6 +44,12 @@ public class JsonValueEnhancer {
        this.processors = Collections.unmodifiableList(sortedProcessors);
    }

+    /**
+     * 增强响应对象。
+     *
+     * @param body 响应对象
+     * @return 增强后的响应对象
+     */
    public Object enhance(Object body) {
        if (body == null || body instanceof JsonNode || processors.isEmpty()) {
            return body;
@@ -45,6 +57,12 @@ public class JsonValueEnhancer {
        return enhanceTree(body);
    }

+    /**
+     * 判断消息转换器是否支持响应增强。
+     *
+     * @param converterType 消息转换器类型
+     * @return true 支持 false 不支持
+     */
    public boolean supports(Class<?> converterType) {
        return !processors.isEmpty()
            && !ByteArrayHttpMessageConverter.class.isAssignableFrom(converterType)
@@ -18,6 +18,11 @@ public record DataPermissionAccess(Set<String> perms, Set<String> roleKeys) impl

    public static final DataPermissionAccess EMPTY = new DataPermissionAccess(Set.of(), Set.of());

+    /**
+     * 是否存在数据权限约束。
+     *
+     * @return true 存在权限约束 false 不存在权限约束
+     */
    public boolean constrained() {
        return CollUtil.isNotEmpty(perms) || CollUtil.isNotEmpty(roleKeys);
    }
@@ -40,6 +40,11 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
    private final List<String> sqlSet;
    private SharedString sqlSelect = new SharedString();

+    /**
+     * 构造 Mapper 级 Lambda CRUD 链式包装器。
+     *
+     * @param crudMapper Mapper 对象
+     */
    public LambdaCrudChainWrapper(BaseMapperPlus<T, V> crudMapper) {
        this.crudMapper = crudMapper;
        super.setEntityClass(crudMapper.currentModelClass());
@@ -47,6 +52,22 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
        this.sqlSet = new ArrayList<>();
    }

+    /**
+     * 构造 Mapper 级 Lambda CRUD 链式包装器实例。
+     *
+     * @param crudMapper          Mapper 对象
+     * @param entity              实体对象
+     * @param entityClass         实体类型
+     * @param sqlSelect           查询字段 SQL 片段
+     * @param sqlSet              更新 set SQL 片段集合
+     * @param paramNameSeq        参数名称序列
+     * @param paramNameValuePairs 参数名称与参数值映射
+     * @param mergeSegments       查询条件表达式
+     * @param paramAlias          参数别名
+     * @param lastSql             SQL 尾部片段
+     * @param sqlComment          SQL 注释片段
+     * @param sqlFirst            SQL 起始片段
+     */
    LambdaCrudChainWrapper(BaseMapperPlus<T, V> crudMapper, T entity, Class<T> entityClass, SharedString sqlSelect,
                           List<String> sqlSet, AtomicInteger paramNameSeq, Map<String, Object> paramNameValuePairs,
                           MergeSegments mergeSegments, SharedString paramAlias, SharedString lastSql,
@@ -65,6 +86,13 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
        this.sqlFirst = sqlFirst;
    }

+    /**
+     * 按条件选择查询字段。
+     *
+     * @param condition 是否选择字段
+     * @param columns   查询字段集合
+     * @return this
+     */
    @Override
    public LambdaCrudChainWrapper<T, V> select(boolean condition, List<SFunction<T, ?>> columns) {
        if (condition && CollectionUtils.isNotEmpty(columns)) {
@@ -73,16 +101,36 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
        return typedThis;
    }

+    /**
+     * 选择查询字段。
+     *
+     * @param columns 查询字段
+     * @return this
+     */
    @SafeVarargs
    public final LambdaCrudChainWrapper<T, V> select(SFunction<T, ?>... columns) {
        return select(true, CollectionUtils.toList(columns));
    }

+    /**
+     * 按条件选择查询字段。
+     *
+     * @param condition 是否选择字段
+     * @param columns   查询字段
+     * @return this
+     */
    @SafeVarargs
    public final LambdaCrudChainWrapper<T, V> select(boolean condition, SFunction<T, ?>... columns) {
        return select(condition, CollectionUtils.toList(columns));
    }

+    /**
+     * 按字段过滤条件选择查询字段。
+     *
+     * @param entityClass 实体类型
+     * @param predicate   字段过滤条件
+     * @return this
+     */
    @Override
    public LambdaCrudChainWrapper<T, V> select(Class<T> entityClass, Predicate<TableFieldInfo> predicate) {
        if (entityClass == null) {
@@ -95,11 +143,25 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
        return typedThis;
    }

+    /**
+     * 获取查询字段 SQL 片段。
+     *
+     * @return 查询字段 SQL 片段
+     */
    @Override
    public String getSqlSelect() {
        return sqlSelect.getStringValue();
    }

+    /**
+     * 按条件设置更新字段。
+     *
+     * @param condition 是否设置该字段
+     * @param column    字段
+     * @param val       字段值
+     * @param mapping   参数映射
+     * @return this
+     */
    @Override
    public LambdaCrudChainWrapper<T, V> set(boolean condition, SFunction<T, ?> column, Object val, String mapping) {
        return maybeDo(condition, () -> {
@@ -130,11 +192,27 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
        return set(org.dromara.common.core.utils.StringUtils.isNotBlank(value), column, value);
    }

+    /**
+     * 按条件设置自定义 SQL 更新片段。
+     *
+     * @param condition 是否设置该片段
+     * @param setSql    SQL 更新片段
+     * @param params    SQL 片段参数
+     * @return this
+     */
    @Override
    public LambdaCrudChainWrapper<T, V> setSql(boolean condition, String setSql, Object... params) {
        return maybeDo(condition && StringUtils.isNotBlank(setSql), () -> sqlSet.add(formatSqlMaybeWithParam(setSql, params)));
    }

+    /**
+     * 按条件设置字段自增。
+     *
+     * @param condition 是否设置该字段
+     * @param column    字段
+     * @param val       自增值
+     * @return this
+     */
    @Override
    public LambdaCrudChainWrapper<T, V> setIncrBy(boolean condition, SFunction<T, ?> column, Number val) {
        return maybeDo(condition, () -> {
@@ -144,6 +222,14 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
        });
    }

+    /**
+     * 按条件设置字段自减。
+     *
+     * @param condition 是否设置该字段
+     * @param column    字段
+     * @param val       自减值
+     * @return this
+     */
    @Override
    public LambdaCrudChainWrapper<T, V> setDecrBy(boolean condition, SFunction<T, ?> column, Number val) {
        return maybeDo(condition, () -> {
@@ -153,6 +239,11 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
        });
    }

+    /**
+     * 获取更新 set SQL 片段。
+     *
+     * @return 更新 set SQL 片段
+     */
    @Override
    public String getSqlSet() {
        if (CollectionUtils.isEmpty(sqlSet)) {
@@ -170,14 +261,36 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
        return typedThis;
    }

+    /**
+     * 添加 FIND_IN_SET 条件。
+     *
+     * @param value  匹配值
+     * @param column 字段
+     * @return this
+     */
    public LambdaCrudChainWrapper<T, V> findInSet(Object value, SFunction<T, ?> column) {
        return findInSet(true, value, column);
    }

+    /**
+     * 添加 FIND_IN_SET 条件。
+     *
+     * @param condition 是否添加该条件
+     * @param value     匹配值
+     * @param column    字段
+     * @return this
+     */
    public LambdaCrudChainWrapper<T, V> findInSet(boolean condition, Object value, SFunction<T, ?> column) {
        return findInSet(condition, value, columnToString(column));
    }

+    /**
+     * 值不为空时添加 FIND_IN_SET 条件。
+     *
+     * @param value  匹配值
+     * @param column 字段
+     * @return this
+     */
    public LambdaCrudChainWrapper<T, V> findInSetIfPresent(Object value, SFunction<T, ?> column) {
        return findInSet(value != null, value, column);
    }
@@ -382,6 +495,11 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
        return crudMapper.update(entity, typedThis);
    }

+    /**
+     * 创建新的链式包装器实例。
+     *
+     * @return 新的链式包装器实例
+     */
    @Override
    protected LambdaCrudChainWrapper<T, V> instance() {
        return new LambdaCrudChainWrapper<>(crudMapper, getEntity(), getEntityClass(), null, null, paramNameSeq,
@@ -389,6 +507,9 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
            SharedString.emptyString());
    }

+    /**
+     * 清空当前 Wrapper 状态。
+     */
    @Override
    public void clear() {
        super.clear();
@@ -114,11 +114,22 @@ public class PageQuery implements Serializable {
        return list;
    }

+    /**
+     * 获取当前页起始行号。
+     *
+     * @return 起始行号
+     */
    @JsonIgnore
    public Integer getFirstNum() {
        return (pageNum - 1) * pageSize;
    }

+    /**
+     * 构造分页查询对象。
+     *
+     * @param pageSize 分页大小
+     * @param pageNum  当前页码
+     */
    public PageQuery(Integer pageSize, Integer pageNum) {
        this.pageSize = pageSize;
        this.pageNum = pageNum;
@@ -149,10 +149,22 @@ public class OssClientConfig implements Config<OssClientConfig, OssClientConfig.
        return Optional.ofNullable(prefix);
    }

+    /**
+     * 根据 OSS 配置属性构建客户端配置。
+     *
+     * @param properties OSS 配置属性
+     * @return 客户端配置
+     */
    public static OssClientConfig formProperties(OssProperties properties) {
        return formPropertiesBuilder(properties).build();
    }

+    /**
+     * 根据 OSS 配置属性构建客户端配置构造器。
+     *
+     * @param properties OSS 配置属性
+     * @return 客户端配置构造器
+     */
    public static OssClientConfigBuilder formPropertiesBuilder(OssProperties properties) {
        String regionString = properties.getRegion();
        Region region = Region.US_EAST_1;
@@ -47,6 +47,12 @@ public enum AccessPolicy {
     */
    private final ObjectCannedACL objectCannedACL;

+    /**
+     * 根据策略类型查找访问策略。
+     *
+     * @param type 策略类型
+     * @return 访问策略
+     */
    public static AccessPolicy formType(String type) {
        return Arrays.stream(values())
            .filter(policy -> policy.getType().toString().equals(type))
@@ -12,34 +12,86 @@ public class S3StorageException extends RuntimeException {
    @Serial
    private static final long serialVersionUID = 1L;

+    /**
+     * 使用异常消息构造 S3 对象存储异常。
+     *
+     * @param message 异常消息
+     */
    public S3StorageException(String message) {
        super(message);
    }

+    /**
+     * 使用异常消息和原因构造 S3 对象存储异常。
+     *
+     * @param message 异常消息
+     * @param cause   异常原因
+     */
    public S3StorageException(String message, Throwable cause) {
        super(message, cause);
    }

+    /**
+     * 使用异常原因构造 S3 对象存储异常。
+     *
+     * @param cause 异常原因
+     */
    public S3StorageException(Throwable cause) {
        super(cause);
    }

+    /**
+     * 使用完整异常参数构造 S3 对象存储异常。
+     *
+     * @param message            异常消息
+     * @param cause              异常原因
+     * @param enableSuppression  是否启用抑制
+     * @param writableStackTrace 是否写入堆栈
+     */
    public S3StorageException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
        super(message, cause, enableSuppression, writableStackTrace);
    }

+    /**
+     * 创建 S3 对象存储异常。
+     *
+     * @param message 异常消息
+     * @return S3 对象存储异常
+     */
    public static S3StorageException form(String message) {
        return new S3StorageException(message);
    }

+    /**
+     * 创建 S3 对象存储异常。
+     *
+     * @param message 异常消息
+     * @param cause   异常原因
+     * @return S3 对象存储异常
+     */
    public static S3StorageException form(String message, Throwable cause) {
        return new S3StorageException(message, cause);
    }

+    /**
+     * 创建 S3 对象存储异常。
+     *
+     * @param cause 异常原因
+     * @return S3 对象存储异常
+     */
    public static S3StorageException form(Throwable cause) {
        return new S3StorageException(cause);
    }

+    /**
+     * 创建 S3 对象存储异常。
+     *
+     * @param message            异常消息
+     * @param cause              异常原因
+     * @param enableSuppression  是否启用抑制
+     * @param writableStackTrace 是否写入堆栈
+     * @return S3 对象存储异常
+     */
    public static S3StorageException form(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
        return new S3StorageException(message, cause, enableSuppression, writableStackTrace);
    }
@@ -15,30 +15,72 @@ public record HandleAsyncResult<T>(
        Throwable error
 ) {

+    /**
+     * 获取异步处理结果。
+     *
+     * @return 异步处理结果
+     */
    public Optional<T> getResult() {
        return Optional.ofNullable(result);
    }

+    /**
+     * 获取异步处理异常。
+     *
+     * @return 异步处理异常
+     */
    public Optional<Throwable> getError() {
        return Optional.ofNullable(error);
    }

+    /**
+     * 是否处理成功。
+     *
+     * @return true 成功 false 失败
+     */
    public boolean isSuccess() {
        return getError().isEmpty();
    }

+    /**
+     * 是否处理失败。
+     *
+     * @return true 失败 false 成功
+     */
    public boolean isFailure() {
        return getError().isPresent();
    }

+    /**
+     * 构建异步处理结果。
+     *
+     * @param result 结果
+     * @param error  异常
+     * @param <T>    结果类型
+     * @return 异步处理结果
+     */
    public static <T> HandleAsyncResult<T> of(T result, Throwable error) {
        return new HandleAsyncResult<T>(result, error);
    }

+    /**
+     * 构建成功的异步处理结果。
+     *
+     * @param result 结果
+     * @param <T>    结果类型
+     * @return 异步处理结果
+     */
    public static <T> HandleAsyncResult<T> success(T result) {
        return new HandleAsyncResult<T>(result, null);
    }

+    /**
+     * 构建失败的异步处理结果。
+     *
+     * @param error 异常
+     * @param <T>   结果类型
+     * @return 异步处理结果
+     */
    public static <T> HandleAsyncResult<T> failure(Throwable error) {
        return new HandleAsyncResult<T>(null, error);
    }
@@ -16,6 +16,15 @@ public record PutObjectResult(
        long size
 ) {

+    /**
+     * 构建文件上传结果。
+     *
+     * @param url  文件地址
+     * @param key  文件标识
+     * @param eTag 文件 ETag
+     * @param size 文件大小
+     * @return 文件上传结果
+     */
    public static PutObjectResult form(String url, String key, String eTag, long size) {
        return new PutObjectResult(url, key, eTag, size);
    }
@@ -48,14 +48,35 @@ public class PathNamedTemplate implements Template {
        return delegate.render(bindingMap);
    }

+    /**
+     * 构建带路径名称的模板。
+     *
+     * @param pathName 路径名称
+     * @param delegate 模板对象
+     * @return 带路径名称的模板
+     */
    public static PathNamedTemplate form(String pathName, Template delegate) {
        return new PathNamedTemplate(pathName, delegate);
    }

+    /**
+     * 根据模板引擎和路径名称构建模板。
+     *
+     * @param templateEngine 模板引擎
+     * @param pathName       路径名称
+     * @return 带路径名称的模板
+     */
    public static PathNamedTemplate form(TemplateEngine templateEngine,String pathName) {
        return new PathNamedTemplate(pathName,templateEngine.getTemplate(pathName));
    }

+    /**
+     * 根据模板引擎和路径名称集合构建模板映射。
+     *
+     * @param templateEngine 模板引擎
+     * @param pathNames      路径名称集合
+     * @return 模板映射
+     */
    public static Map<String, PathNamedTemplate> form(TemplateEngine templateEngine, Set<String> pathNames) {
        Map<String, PathNamedTemplate> result = new HashMap<>();
        for (String pathName : pathNames) {
@@ -104,10 +104,20 @@ public class SysUser extends BaseEntity {
    private String remark;


+    /**
+     * 使用用户ID构造系统用户对象。
+     *
+     * @param userId 用户ID
+     */
    public SysUser(Long userId) {
        this.userId = userId;
    }

+    /**
+     * 判断当前用户是否为超级管理员。
+     *
+     * @return true 是超级管理员 false 不是超级管理员
+     */
    public boolean isSuperAdmin() {
        return SystemConstants.SUPER_ADMIN_USER_ID.equals(this.userId);
    }
@@ -88,6 +88,11 @@ public class SysRoleBo implements Serializable {
     */
    private Long[] deptIds;

+    /**
+     * 判断当前角色是否为超级管理员角色。
+     *
+     * @return true 是超级管理员角色 false 不是超级管理员角色
+     */
    public boolean isSuperAdmin() {
        return SystemConstants.SUPER_ADMIN_ROLE_ID.equals(this.roleId);
    }
@@ -133,6 +133,11 @@ public class SysUserBo implements Serializable {
     */
    private Map<String, Object> params = new HashMap<>();

+    /**
+     * 判断当前用户是否为超级管理员。
+     *
+     * @return true 是超级管理员 false 不是超级管理员
+     */
    public boolean isSuperAdmin() {
        return SystemConstants.SUPER_ADMIN_USER_ID.equals(this.userId);
    }
@@ -93,6 +93,11 @@ public class SysRoleVo implements Serializable {
     */
    private boolean flag = false;

+    /**
+     * 判断当前角色是否为超级管理员角色。
+     *
+     * @return true 是超级管理员角色 false 不是超级管理员角色
+     */
    public boolean isSuperAdmin() {
        return SystemConstants.SUPER_ADMIN_ROLE_ID.equals(this.roleId);
    }
@@ -165,6 +165,12 @@ public interface SysUserMapper extends BaseMapperPlus<SysUser, SysUserVo>, MPJBa
    })
    int updateById(@Param(Constants.ENTITY) SysUser user);

+    /**
+     * 构建用户与角色关联查询条件
+     *
+     * @param user 查询条件
+     * @return 用户角色关联查询包装器
+     */
    default MPJLambdaWrapper<SysUser> buildUserRoleJoinWrapper(SysUserBo user) {
        return JoinWrappers.lambda("u", SysUser.class)
            .distinct()
@@ -19,6 +19,11 @@ public class SystemApplicationRunner implements ApplicationRunner {

    private final ISysOssConfigService ossConfigService;

+    /**
+     * 应用启动后初始化 OSS 配置缓存。
+     *
+     * @param args 启动参数
+     */
    @Override
    public void run(ApplicationArguments args) throws Exception {
        ossConfigService.init();
@@ -110,7 +110,7 @@ public interface ISysMenuService {
    /**
     * 是否存在菜单子节点
     *
-     * @param menuIds 菜单ID串
+     * @param menuIds 菜单ID列表
     * @return 结果 true 存在 false 不存在
     */
    boolean hasChildByMenuId(Collection<Long> menuIds);
@@ -150,8 +150,7 @@ public interface ISysMenuService {
    /**
     * 批量删除菜单管理信息
     *
-     * @param menuIds 菜单ID串
-     * @return 结果
+     * @param menuIds 菜单ID列表
     */
    void deleteMenuById(Collection<Long> menuIds);

@@ -110,7 +110,7 @@ public class SysMenuServiceImpl implements ISysMenuService {
    }

    /**
-     * 根据用户ID查询菜单
+     * 根据用户ID查询菜单树信息
     *
     * @param userId 用户ID
     * @return 按树结构组织的菜单列表
@@ -251,7 +251,7 @@ public class SysMenuServiceImpl implements ISysMenuService {
    /**
     * 是否存在菜单子节点
     *
-     * @param menuIds 菜单ID串
+     * @param menuIds 菜单ID列表
     * @return 结果
     */
    @Override
@@ -337,7 +337,7 @@ public class SysMenuServiceImpl implements ISysMenuService {
    }

    /**
-     * 校验路由名称是否唯一
+     * 校验路由组合是否唯一
     *
     * @param menuBo 菜单信息
     * @return 结果