From 73e2b169f7bc4a02140f963fd7b90037be8ff2b8 Mon Sep 17 00:00:00 2001
From: Charles7c <charles7c@126.com>
Date: Thu, 22 May 2025 21:21:48 +0800
Subject: [PATCH] =?UTF-8?q?refactor(json/jackson):=20=E4=BC=98=E5=8C=96?=
 =?UTF-8?q?=E9=83=A8=E5=88=86=E4=BB=A3=E7=A0=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../JacksonAutoConfiguration.java             | 48 +++++++++----------
 ...s.java => JacksonExtensionProperties.java} | 21 ++++----
 ...eEnum.java => BigNumberSerializeMode.java} | 28 ++++++++---
 .../main/resources/default-json-jackson.yml   |  2 +-
 4 files changed, 58 insertions(+), 41 deletions(-)
 rename continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/autoconfigure/{JacksonProperties.java => JacksonExtensionProperties.java} (79%)
 rename continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/enums/{BigNumberSerializeModeEnum.java => BigNumberSerializeMode.java} (58%)

diff --git a/continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/autoconfigure/JacksonAutoConfiguration.java b/continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/autoconfigure/JacksonAutoConfiguration.java
index 839bebd5..0f4a90a2 100644
--- a/continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/autoconfigure/JacksonAutoConfiguration.java
+++ b/continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/autoconfigure/JacksonAutoConfiguration.java
@@ -21,7 +21,6 @@ import java.time.LocalDate;
 import java.time.LocalDateTime;
 import java.time.LocalTime;
 import java.time.format.DateTimeFormatter;
-import java.util.Objects;
 import java.util.TimeZone;
 
 import org.slf4j.Logger;
@@ -45,7 +44,6 @@ import com.fasterxml.jackson.datatype.jsr310.ser.LocalTimeSerializer;
 import cn.hutool.core.date.DatePattern;
 import top.continew.starter.core.enums.BaseEnum;
 import top.continew.starter.core.util.GeneralPropertySourceFactory;
-import top.continew.starter.json.jackson.enums.BigNumberSerializeModeEnum;
 import top.continew.starter.json.jackson.serializer.BaseEnumDeserializer;
 import top.continew.starter.json.jackson.serializer.BaseEnumSerializer;
 import top.continew.starter.json.jackson.serializer.BigNumberSerializer;
@@ -55,30 +53,30 @@ import top.continew.starter.json.jackson.serializer.SimpleDeserializersWrapper;
  * Jackson 自动配置
  *
  * @author Charles7c
+ * @author Jasmine
  * @since 1.0.0
  */
 @AutoConfiguration
-@EnableConfigurationProperties(JacksonProperties.class)
+@EnableConfigurationProperties(JacksonExtensionProperties.class)
 @PropertySource(value = "classpath:default-json-jackson.yml", factory = GeneralPropertySourceFactory.class)
 public class JacksonAutoConfiguration {
+
     private static final Logger log = LoggerFactory.getLogger(JacksonAutoConfiguration.class);
+    private final JacksonExtensionProperties properties;
 
-    private final JacksonProperties jacksonProperties;
-
-    public JacksonAutoConfiguration(JacksonProperties jacksonProperties) {
-        this.jacksonProperties = jacksonProperties;
+    public JacksonAutoConfiguration(JacksonExtensionProperties properties) {
+        this.properties = properties;
     }
 
     @Bean
     public Jackson2ObjectMapperBuilderCustomizer jackson2ObjectMapperBuilderCustomizer() {
         return builder -> {
-
-            JavaTimeModule javaTimeModule = this.timeModule();
-            SimpleModule enumModule = this.baseEnumModule();
+            JavaTimeModule javaTimeModule = this.javaTimeModule();
+            SimpleModule baseEnumModule = this.baseEnumModule();
             SimpleModule bigNumberModule = this.bigNumberModule();
 
             builder.timeZone(TimeZone.getDefault());
-            builder.modules(javaTimeModule, enumModule, bigNumberModule);
+            builder.modules(javaTimeModule, baseEnumModule, bigNumberModule);
             log.debug("[ContiNew Starter] - Auto Configuration 'Jackson' completed initialization.");
         };
     }
@@ -86,10 +84,10 @@ public class JacksonAutoConfiguration {
     /**
      * 日期时间序列化及反序列化配置
      *
-     * @return JavaTimeModule /
+     * @return {@link JavaTimeModule}
      * @since 1.0.0
      */
-    private JavaTimeModule timeModule() {
+    private JavaTimeModule javaTimeModule() {
         JavaTimeModule javaTimeModule = new JavaTimeModule();
         // 针对时间类型：LocalDateTime 的序列化和反序列化处理
         DateTimeFormatter dateTimeFormatter = DateTimeFormatter.ofPattern(DatePattern.NORM_DATETIME_PATTERN);
@@ -125,21 +123,23 @@ public class JacksonAutoConfiguration {
      * 大数值序列化及反序列化配置
      *
      * @return SimpleModule /
-     * @since 2.12.0
+     * @since 2.12.1
      */
     private SimpleModule bigNumberModule() {
         SimpleModule bigNumberModule = new SimpleModule();
-        if (Objects.equals(jacksonProperties.getBigNumberSerializeMode(), BigNumberSerializeModeEnum.FLEXIBLE)) {
-            bigNumberModule.addSerializer(Long.class, BigNumberSerializer.SERIALIZER_INSTANCE);
-            bigNumberModule.addSerializer(Long.TYPE, BigNumberSerializer.SERIALIZER_INSTANCE);
-            bigNumberModule.addSerializer(BigInteger.class, BigNumberSerializer.SERIALIZER_INSTANCE);
-        } else if (Objects.equals(jacksonProperties
-            .getBigNumberSerializeMode(), BigNumberSerializeModeEnum.TO_STRING)) {
-            bigNumberModule.addSerializer(Long.class, ToStringSerializer.instance);
-            bigNumberModule.addSerializer(Long.TYPE, ToStringSerializer.instance);
-            bigNumberModule.addSerializer(BigInteger.class, ToStringSerializer.instance);
+        switch (properties.getBigNumberSerializeMode()) {
+            case FLEXIBLE -> {
+                bigNumberModule.addSerializer(Long.class, BigNumberSerializer.SERIALIZER_INSTANCE);
+                bigNumberModule.addSerializer(Long.TYPE, BigNumberSerializer.SERIALIZER_INSTANCE);
+                bigNumberModule.addSerializer(BigInteger.class, BigNumberSerializer.SERIALIZER_INSTANCE);
+            }
+            case TO_STRING -> {
+                bigNumberModule.addSerializer(Long.class, ToStringSerializer.instance);
+                bigNumberModule.addSerializer(Long.TYPE, ToStringSerializer.instance);
+                bigNumberModule.addSerializer(BigInteger.class, ToStringSerializer.instance);
+            }
+            default -> log.warn("[ContiNew Starter] - Jackson 大数值序列化模式：NO_OPERATE，超过 JS 范围的数值会损失精度");
         }
-
         return bigNumberModule;
     }
 }
diff --git a/continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/autoconfigure/JacksonProperties.java b/continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/autoconfigure/JacksonExtensionProperties.java
similarity index 79%
rename from continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/autoconfigure/JacksonProperties.java
rename to continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/autoconfigure/JacksonExtensionProperties.java
index 52c7ec8f..0a3b9822 100644
--- a/continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/autoconfigure/JacksonProperties.java
+++ b/continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/autoconfigure/JacksonExtensionProperties.java
@@ -18,27 +18,28 @@ package top.continew.starter.json.jackson.autoconfigure;
 
 import org.springframework.boot.context.properties.ConfigurationProperties;
 
-import top.continew.starter.json.jackson.enums.BigNumberSerializeModeEnum;
+import top.continew.starter.json.jackson.enums.BigNumberSerializeMode;
 
 /**
- * jackson 配置属性
+ * Jackson 扩展配置属性
  *
  * @author Jasmine
  * @author Charles7c
- * @since 2.12.0
+ * @since 2.12.1
  */
 @ConfigurationProperties("spring.jackson")
-public class JacksonProperties {
-    /**
-     * 大数值类型序列化模式
-     */
-    private BigNumberSerializeModeEnum bigNumberSerializeMode;
+public class JacksonExtensionProperties {
 
-    public BigNumberSerializeModeEnum getBigNumberSerializeMode() {
+    /**
+     * 大数值序列化模式
+     */
+    private BigNumberSerializeMode bigNumberSerializeMode;
+
+    public BigNumberSerializeMode getBigNumberSerializeMode() {
         return bigNumberSerializeMode;
     }
 
-    public void setBigNumberSerializeMode(BigNumberSerializeModeEnum bigNumberSerializeMode) {
+    public void setBigNumberSerializeMode(BigNumberSerializeMode bigNumberSerializeMode) {
         this.bigNumberSerializeMode = bigNumberSerializeMode;
     }
 }
diff --git a/continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/enums/BigNumberSerializeModeEnum.java b/continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/enums/BigNumberSerializeMode.java
similarity index 58%
rename from continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/enums/BigNumberSerializeModeEnum.java
rename to continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/enums/BigNumberSerializeMode.java
index 5ad5277e..6cf69b19 100644
--- a/continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/enums/BigNumberSerializeModeEnum.java
+++ b/continew-starter-json/continew-starter-json-jackson/src/main/java/top/continew/starter/json/jackson/enums/BigNumberSerializeMode.java
@@ -21,13 +21,29 @@ package top.continew.starter.json.jackson.enums;
  *
  * @author Jasmine
  * @author Charles7c
- * @since 2.12.0
+ * @since 2.12.1
  */
-public enum BigNumberSerializeModeEnum {
-    /** 超过js的最大值转字符串类型，否则保持原类型 */
+public enum BigNumberSerializeMode {
+
+    /**
+     * 超过 JS 范围的数值转为 {@link String} 类型，否则保持原类型
+     * <p>
+     * JS：Number.MIN_SAFE_INTEGER：-9007199254740991L <br />
+     * JS：Number.MAX_SAFE_INTEGER：9007199254740991L
+     * </p>
+     */
     FLEXIBLE,
-    /** 不操作 */
+
+    /**
+     * 统一转为 {@link String} 类型
+     */
+    TO_STRING,
+
+    /**
+     * 不操作（不建议）
+     * <p>
+     * 注意：超过 JS 范围的数值会损失精度，例如：8014753905961037835 会被转为 8014753905961038000
+     * </p>
+     */
     NO_OPERATE,
-    /** 统一转String类型 */
-    TO_STRING,;
 }
diff --git a/continew-starter-json/continew-starter-json-jackson/src/main/resources/default-json-jackson.yml b/continew-starter-json/continew-starter-json-jackson/src/main/resources/default-json-jackson.yml
index 782ae65a..6c47a778 100644
--- a/continew-starter-json/continew-starter-json-jackson/src/main/resources/default-json-jackson.yml
+++ b/continew-starter-json/continew-starter-json-jackson/src/main/resources/default-json-jackson.yml
@@ -21,5 +21,5 @@ spring:
     deserialization:
       # 允许反序列化不存在的属性
       fail-on-unknown-properties: false
-    # 大数值序列化类型的转换
+    # 大数值序列化模式
     big-number-serialize-mode: FLEXIBLE