feat(core): add support for orderly snowflake friendly ID conversion

- Implement SnowflakeFriendlyIdConverterStat to provide detailed statistics
- Enhance SnowflakeIdStateParser with new methods for padStart and character size
- Update SnowflakeFriendlyIdConverter to support padStart configuration
- Add new configuration example for orderly snowflake friendly ID
- Modify existing tests to use new SnowflakeFriendlyIdConverterStat

Author: Ahoo-Wang

cosid-core/src/main/java/me/ahoo/cosid/converter/SnowflakeFriendlyIdConverter.java

@@ -16,6 +16,8 @@
 import me.ahoo.cosid.IdConverter;
 import me.ahoo.cosid.snowflake.MillisecondSnowflakeIdStateParser;
 import me.ahoo.cosid.snowflake.SnowflakeIdStateParser;
+import me.ahoo.cosid.stat.Stat;
+import me.ahoo.cosid.stat.converter.SnowflakeFriendlyIdConverterStat;
 
 import javax.annotation.Nonnull;
 
@@ -49,4 +51,12 @@ public long asLong(@Nonnull String idString) {
         return snowflakeIdStateParser.parse(idString).getId();
     }
 
+    @Override
+    public Stat stat() {
+        return new SnowflakeFriendlyIdConverterStat(
+                getClass().getSimpleName(),
+                snowflakeIdStateParser.isPadStart(),
+                snowflakeIdStateParser.getMachineCharSize(),
+                snowflakeIdStateParser.getSequenceCharSize());
+    }
 }

cosid-core/src/main/java/me/ahoo/cosid/snowflake/SnowflakeIdStateParser.java

@@ -80,6 +80,18 @@ public ZoneId getZoneId() {
         return zoneId;
     }
 
+    public boolean isPadStart() {
+        return padStart;
+    }
+
+    public int getMachineCharSize() {
+        return machineCharSize;
+    }
+
+    public int getSequenceCharSize() {
+        return sequenceCharSize;
+    }
+
     protected abstract DateTimeFormatter getDateTimeFormatter();
 
     protected abstract LocalDateTime getTimestamp(long diffTime);

cosid-core/src/main/java/me/ahoo/cosid/stat/converter/SnowflakeFriendlyIdConverterStat.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright [2021-present] [ahoo wang <[email protected]> (https://github.com/Ahoo-Wang)].
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package me.ahoo.cosid.stat.converter;
+
+import me.ahoo.cosid.stat.Stat;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+
+@AllArgsConstructor
+@Data
+public class SnowflakeFriendlyIdConverterStat implements Stat {
+    private final String kind;
+    private final boolean padStart;
+    private final int machineCharSize;
+    private final int sequenceCharSize;
+}

cosid-core/src/test/java/me/ahoo/cosid/converter/SnowflakeFriendlyIdConverterTest.java

@@ -19,8 +19,8 @@
 import me.ahoo.cosid.snowflake.SecondSnowflakeId;
 import me.ahoo.cosid.snowflake.SecondSnowflakeIdStateParser;
 import me.ahoo.cosid.snowflake.SnowflakeId;
-import me.ahoo.cosid.stat.SimpleStat;
 
+import me.ahoo.cosid.stat.converter.SnowflakeFriendlyIdConverterStat;
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
@@ -68,6 +68,6 @@ void getParser() {
 
     @Test
     void stat() {
-        assertThat(SnowflakeFriendlyIdConverter.INSTANCE.stat(), instanceOf(SimpleStat.class));
+        assertThat(SnowflakeFriendlyIdConverter.INSTANCE.stat(), instanceOf(SnowflakeFriendlyIdConverterStat.class));
     }
 }

documentation/docs/guide/specific-id.md

@@ -61,6 +61,76 @@ cosid:
 ```
 :::
 
+## snowflake_orderly_friendly
+
+使用 _SnowflakeId_ 算法，要求输出的有序的ID字符串：
+
+- 格式：`yyyyMMddHHmmssSSS-[0]<machineId>-[0]<sequence>`
+- 例如：`20250215122059820-0000-0001`
+
+
+::: code-group
+```yaml {9-14} [配置]
+cosid:
+  machine:
+    enabled: true
+    distributor:
+      type: redis
+  snowflake:
+    enabled: true
+    provider:
+      snowflake_orderly_friendly:
+        converter:
+          type: snowflake_friendly
+          friendly:
+            pad-start: true
+```
+```json [配置信息]
+{
+  "snowflake_orderly_friendly": {
+    "kind": "StringSnowflakeId",
+    "actual": {
+      "kind": "ClockSyncSnowflakeId",
+      "actual": {
+        "kind": "MillisecondSnowflakeId",
+        "epoch": 1577203200000,
+        "timestampBit": 41,
+        "machineBit": 10,
+        "sequenceBit": 12,
+        "machineId": 0,
+        "lastTimestamp": -1,
+        "converter": {
+          "kind": "Radix62IdConverter",
+          "radix": 62,
+          "charSize": 11,
+          "padStart": true,
+          "maxId": 9223372036854776000,
+          "actual": null
+        },
+        "safeJavascript": false,
+        "actual": null
+      },
+      "converter": {
+        "kind": "Radix62IdConverter",
+        "radix": 62,
+        "charSize": 11,
+        "padStart": true,
+        "maxId": 9223372036854776000,
+        "actual": null
+      }
+    },
+    "converter": {
+      "kind": "SnowflakeFriendlyIdConverter",
+      "padStart": true,
+      "machineCharSize": 4,
+      "sequenceCharSize": 4,
+      "actual": null
+    }
+  }
+}
+```
+:::
+
 ## snowflake_short_id
 
 使用 _SnowflakeId_ 算法，要求输出的ID字符串：

examples/cosid-example-redis/src/main/resources/application.yaml

@@ -32,6 +32,11 @@ cosid:
       snowflake_friendly:
         converter:
           type: snowflake_friendly
+      snowflake_orderly_friendly:
+        converter:
+          type: snowflake_friendly
+          friendly:
+            pad-start: true
       snowflake_short_id:
         converter:
           type: radix