Merge branch 'dev' into test

zt-framework/zt-common/pom.xml

@@ -52,6 +52,12 @@
             <scope>provided</scope> <!-- 设置为 provided，只有工具类需要使用到 -->
         </dependency>
 
+        <dependency>
+            <groupId>org.springframework.data</groupId>
+            <artifactId>spring-data-redis</artifactId>
+            <scope>provided</scope> <!-- 设置为 provided，只有工具类需要使用到 -->
+        </dependency>
+
         <dependency>
             <groupId>jakarta.servlet</groupId>
             <artifactId>jakarta.servlet-api</artifactId>
@@ -151,6 +157,12 @@
             <artifactId>spring-boot-starter-test</artifactId>
             <scope>test</scope>
         </dependency>
+
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
 </project>

zt-framework/zt-common/src/main/java/com/zt/plat/framework/common/annotation/PageSum.java

@@ -0,0 +1,31 @@
+package com.zt.plat.framework.common.annotation;
+
+import java.lang.annotation.*;
+
+/**
+ * 标记分页结果中需要求和的字段。
+ * <p>
+ * 未显式指定列名时，会默认使用实体字段对应的数据库列。
+ * <p>
+ * {@link #exist()} 可以用于声明该字段并不存在于表结构中，相当于为字段添加
+ * {@code @TableField(exist = false)}，方便在 DO 中声明专用于汇总结果的临时字段。
+ */
+@Documented
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface PageSum {
+
+    /**
+     * 自定义求和的数据库列名或表达式，未设置时默认使用实体字段对应的列。
+     */
+    String column() default "";
+
+    /**
+     * 是否在实体字段上声明真实存在的数据库列。
+     * <p>
+     * 设为 {@code false} 时，框架会自动为该字段提供 {@code @TableField(exist = false)} 的能力，
+     * 适用于只在分页响应中返回的临时统计字段。
+     */
+    boolean exist() default false;
+
+}

zt-framework/zt-common/src/main/java/com/zt/plat/framework/common/pojo/PageResult.java

@@ -1,11 +1,18 @@
 package com.zt.plat.framework.common.pojo;
 
+import com.fasterxml.jackson.annotation.JsonAlias;
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonProperty;
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 import java.io.Serializable;
+import java.math.BigDecimal;
 import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.Map;
 
 @Schema(description = "分页结果")
 @Data
@@ -15,19 +22,31 @@ public final class PageResult<T> implements Serializable {
     private List<T> list;
 
     @Schema(description = "总量", requiredMode = Schema.RequiredMode.REQUIRED)
+    @JsonProperty("total")
+    @JsonAlias({"totalCount"})
     private Long total;
 
+    @Schema(description = "汇总信息（字段需使用 @PageSum 标注）")
+    @JsonProperty("summary")
+    private Map<String, BigDecimal> summary;
+
     public PageResult() {
+        this.list = new ArrayList<>();
+        this.summary = Collections.emptyMap();
     }
 
     public PageResult(List<T> list, Long total) {
+        this(list, total, null);
+    }
+
+    public PageResult(List<T> list, Long total, Map<String, BigDecimal> summary) {
         this.list = list;
         this.total = total;
+        setSummaryInternal(summary);
     }
 
     public PageResult(Long total) {
-        this.list = new ArrayList<>();
-        this.total = total;
+        this(new ArrayList<>(), total, null);
     }
 
     public static <T> PageResult<T> empty() {
@@ -38,4 +57,30 @@ public final class PageResult<T> implements Serializable {
         return new PageResult<>(total);
     }
 
+    public void setSummary(Map<String, BigDecimal> summary) {
+        setSummaryInternal(summary);
+    }
+
+    private void setSummaryInternal(Map<String, BigDecimal> summary) {
+        if (summary == null || summary.isEmpty()) {
+            this.summary = Collections.emptyMap();
+            return;
+        }
+        this.summary = new LinkedHashMap<>(summary);
+    }
+
+    public <R> PageResult<R> convert(List<R> newList) {
+        return new PageResult<>(newList, total, summary);
+    }
+
+    @JsonIgnore
+    public Long getTotalCount() {
+        return total;
+    }
+
+    @JsonIgnore
+    public void setTotalCount(Long totalCount) {
+        this.total = totalCount;
+    }
+
 }

zt-framework/zt-common/src/main/java/com/zt/plat/framework/common/util/object/BeanUtils.java

@@ -4,6 +4,7 @@ import cn.hutool.core.bean.BeanUtil;
 import com.zt.plat.framework.common.pojo.PageResult;
 import com.zt.plat.framework.common.util.collection.CollectionUtils;
 
+import java.util.Collections;
 import java.util.List;
 import java.util.Set;
 import java.util.function.Consumer;
@@ -69,10 +70,13 @@ public class BeanUtils {
             return null;
         }
         List<T> list = toBean(source.getList(), targetType);
+        if (list == null) {
+            list = Collections.emptyList();
+        }
         if (peek != null) {
             list.forEach(peek);
         }
-        return new PageResult<>(list, source.getTotal());
+        return new PageResult<>(list, source.getTotal(), source.getSummary());
     }
 
     public static void copyProperties(Object source, Object target) {

zt-framework/zt-spring-boot-starter-monitor/src/main/java/com/zt/plat/framework/tracer/core/filter/TraceFilter.java

@@ -24,10 +24,15 @@ public class TraceFilter extends OncePerRequestFilter {
     @Override
     protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
             throws IOException, ServletException {
-        // 设置响应 traceId
-        response.addHeader(HEADER_NAME_TRACE_ID, TracerUtils.getTraceId());
+        String traceId = TracerUtils.getTraceId();
+        try {
+            // 设置响应 traceId，便于客户端回溯
+            response.addHeader(HEADER_NAME_TRACE_ID, traceId);
             // 继续过滤
             chain.doFilter(request, response);
+        } finally {
+            TracerUtils.clear();
+        }
     }
 
 }

zt-framework/zt-spring-boot-starter-mybatis/pom.xml

@@ -107,6 +107,12 @@
             <groupId>org.springframework.cloud</groupId>
             <artifactId>spring-cloud-starter-openfeign</artifactId>
         </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
 </project>