v1.0.1 - README文档升级

Author: nelson820125

README-EN.md

@@ -1,5 +1,7 @@
 # Jordium.Snowflake.NET
 
+English | [简体中文](./README.md)
+
 [![NuGet](https://img.shields.io/nuget/v/Jordium.Snowflake.NET.svg)](https://www.nuget.org/packages/Jordium.Snowflake.NET/)
 [![.NET](https://img.shields.io/badge/.NET-8.0-512BD4)](https://dotnet.microsoft.com/download/dotnet/8.0)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -8,12 +10,12 @@ High-performance distributed ID generator based on Twitter's Snowflake algorithm
 
 ## Features
 
-- ? **Globally Unique**: Supports multi-datacenter, multi-machine deployment
-- ? **Trend Increasing**: IDs increase by timestamp, optimized for database indexing
-- ? **High Performance**: 2 million - 20 million IDs/second per machine
-- ? **Multiple Implementations**: Drift algorithm, Traditional algorithm, Lock-free algorithm
-- ? **Clock Rollback Handling**: Automatic handling of system time rollback
-- ? **Flexible Configuration**: Customizable bit allocation
+- ✅ **Globally Unique**: Supports multi-datacenter, multi-machine deployment
+- 📈 **Trend Increasing**: IDs increase by timestamp, optimized for database indexing
+- ⚡ **High Performance**: 2 million - 20 million IDs/second per machine
+- 🔧 **Multiple Implementations**: Drift algorithm, Traditional algorithm, Lock-free algorithm
+- ⏰ **Clock Rollback Handling**: Automatic handling of system time rollback
+- 🎯 **Flexible Configuration**: Customizable bit allocation
 
 ## Installation
 
@@ -130,19 +132,19 @@ public class OrderController : ControllerBase
 
 | Algorithm | Implementation | Use Case | Performance | Clock Rollback | Recommended |
 |-----------|---------------|----------|-------------|----------------|-------------|
-| **Method 1** | SnowflakeWorkerV1 | Monolith app, high concurrency | ???? | ? Special sequence | ????? |
-| **Method 2** | SnowflakeWorkerV2 | General, standard implementation | ???? | ?? Throws exception | ??? |
-| **Method 3** | SnowflakeWorkerV3 | Distributed cluster, microservices | ????? | ?? Large rollback throws | ???? |
+| **Method 1** | SnowflakeWorkerV1 | Monolith app, high concurrency | ⭐⭐⭐⭐ | ✅ Special sequence | ⭐⭐⭐⭐⭐ |
+| **Method 2** | SnowflakeWorkerV2 | General, standard implementation | ⭐⭐⭐⭐ | ❌ Throws exception | ⭐⭐⭐ |
+| **Method 3** | SnowflakeWorkerV3 | Distributed cluster, microservices | ⭐⭐⭐⭐⭐ | ⚠️ Large rollback throws | ⭐⭐⭐⭐ |
 
 ### Detailed Description
 
 #### Method 1 - Drift Algorithm (Recommended)
 
 **Features**:
-- ? Auto-handles clock rollback (uses reserved sequence 1-4)
-- ? Auto "drift" to future time when sequence overflows
-- ? Complete event callback mechanism
-- ?? Uses `lock` for synchronization
+- ✅ Auto-handles clock rollback (uses reserved sequence 1-4)
+- ✅ Auto "drift" to future time when sequence overflows
+- ✅ Complete event callback mechanism
+- 🔒 Uses `lock` for synchronization
 
 **Use Cases**:
 - Monolithic applications (multiple threads competing for same WorkerId)
@@ -176,10 +178,10 @@ generator.GenIdActionAsync = arg =>
 #### Method 2 - Traditional Algorithm
 
 **Features**:
-- ? Standard Snowflake implementation
-- ? Simple logic, easy to understand
-- ?? Throws exception on clock rollback
-- ?? Uses `lock` for synchronization
+- ✅ Standard Snowflake implementation
+- ✅ Simple logic, easy to understand
+- ❌ Throws exception on clock rollback
+- 🔒 Uses `lock` for synchronization
 
 **Use Cases**:
 - Learning and understanding Snowflake algorithm
@@ -213,11 +215,11 @@ catch (Exception ex)
 #### Method 3 - Lock-Free Algorithm (High Performance)
 
 **Features**:
-- ? CAS lock-free concurrency, highest performance
-- ? Timestamp cached in state, reduces system calls
-- ? Significant performance advantage in distributed scenarios
-- ?? Short rollback auto-sleeps and waits
-- ?? Large rollback (> 1000ms) throws exception
+- ✅ CAS lock-free concurrency, highest performance
+- ✅ Timestamp cached in state, reduces system calls
+- ✅ Significant performance advantage in distributed scenarios
+- ⚠️ Short rollback auto-sleeps and waits
+- ⚠️ Large rollback (> 1000ms) throws exception
 
 **Use Cases**:
 - Microservice clusters (each service has independent WorkerId)
@@ -282,10 +284,10 @@ var generator = new DefaultIDGenerator(options);
 
 | Threads | Throughput | Avg Latency | Note |
 |---------|-----------|-------------|------|
-| 1       | 12-15M IDs/sec | 0.067-0.083 ¦Ìs | Single thread, no contention |
-| 2       | 9-12M IDs/sec | 0.167-0.222 ¦Ìs | Light contention |
-| 4       | 7-9M IDs/sec | 0.444-0.571 ¦Ìs | Medium contention |
-| 8       | 6-8M IDs/sec | 1.000-1.333 ¦Ìs | Heavy contention |
+| 1       | 12-15M IDs/sec | 0.067-0.083 ��s | Single thread, no contention |
+| 2       | 9-12M IDs/sec | 0.167-0.222 ��s | Light contention |
+| 4       | 7-9M IDs/sec | 0.444-0.571 ��s | Medium contention |
+| 8       | 6-8M IDs/sec | 1.000-1.333 ��s | Heavy contention |
 
 ### Distributed Performance (Method 3)
 
@@ -299,17 +301,17 @@ var generator = new DefaultIDGenerator(options);
 
 | Test Item | Count | Duplicates | Result |
 |-----------|-------|-----------|--------|
-| Single WorkerId Concurrent | 1M | 0 | ? Pass |
-| Multi WorkerId Concurrent | 1M | 0 | ? Pass |
-| Extreme Concurrency (32 threads) | 3.2M | 0 | ? Pass |
-| Sustained Pressure (5 sec) | 10M+ | 0 | ? Pass |
+| Single WorkerId Concurrent | 1M | 0 | ✅ Pass |
+| Multi WorkerId Concurrent | 1M | 0 | ✅ Pass |
+| Extreme Concurrency (32 threads) | 3.2M | 0 | ✅ Pass |
+| Sustained Pressure (5 sec) | 10M+ | 0 | ✅ Pass |
 
 ### Stability Tests
 
-- ? **Million-level Test**: Generate 1M IDs at once, no duplicates
-- ? **Sustained Pressure Test**: Continuous generation for 5 seconds, no duplicates
-- ? **Multi-datacenter Test**: 3 datacenters ¡Á 3 workers, no duplicates
-- ? **Clock Rollback Test**: Method 1 auto-handles, Method 2/3 correctly throw exceptions
+- ✅ **Million-level Test**: Generate 1M IDs at once, no duplicates
+- ✅ **Sustained Pressure Test**: Continuous generation for 5 seconds, no duplicates
+- ✅ **Multi-datacenter Test**: 3 datacenters × 3 workers, no duplicates
+- ✅ **Clock Rollback Test**: Method 1 auto-handles, Method 2/3 correctly throw exceptions
 
 ### Performance Notes
 
@@ -322,32 +324,32 @@ var generator = new DefaultIDGenerator(options);
 > - System load
 >
 > The above data are reference values from typical test environments. 
-> Real deployment environments may have ¡À30% variations.
+> Real deployment environments may have ��30% variations.
 > We recommend running benchmarks on actual hardware for accurate data.
 
 ## ID Structure
 
 ### Standard 64-bit Snowflake ID
 
 ```
-©°©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©Ð©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©Ð©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©Ð©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©´
-©¦ Timestamp(41bit)©¦ DC ID (5bit)©¦ Worker(5bit)©¦ Sequence(12) ©¦
-©¸©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©Ø©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©Ø©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©Ø©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¤©¼
+����������������������������������������������������������������������������������������������������������������������
+�� Timestamp(41bit)�� DC ID (5bit)�� Worker(5bit)�� Sequence(12) ��
+�������������������������������������ة��������������������������ة��������������������������ة�����������������������������
   ~69 years        32 DCs        32 Workers   4096/ms
 ```
 
 ### Bit Allocation Examples
 
 | Config | Worker Bits | DC Bits | Seq Bits | Capacity |
 |--------|------------|---------|----------|----------|
-| Standard | 5 | 5 | 12 | 32 DC ¡Á 32 Worker ¡Á 4096/ms |
-| Multi-DC | 4 | 6 | 12 | 64 DC ¡Á 16 Worker ¡Á 4096/ms |
-| Multi-Worker | 6 | 4 | 12 | 16 DC ¡Á 64 Worker ¡Á 4096/ms |
-| Low Concurrency | 5 | 5 | 10 | 32 DC ¡Á 32 Worker ¡Á 1024/ms |
+| Standard | 5 | 5 | 12 | 32 DC �� 32 Worker �� 4096/ms |
+| Multi-DC | 4 | 6 | 12 | 64 DC �� 16 Worker �� 4096/ms |
+| Multi-Worker | 6 | 4 | 12 | 16 DC �� 64 Worker �� 4096/ms |
+| Low Concurrency | 5 | 5 | 10 | 32 DC �� 32 Worker �� 1024/ms |
 
 **Constraints**:
-- Worker bits + DC bits + Seq bits ¡Ü 22
-- Seq bits ¡Ü 12
+- Worker bits + DC bits + Seq bits �� 22
+- Seq bits �� 12
 
 ## FAQ
 
@@ -383,11 +385,11 @@ var options = new IDGeneratorOptions
 Ensure each machine has a unique `WorkerId` and `DataCenterId` combination:
 
 ```csharp
-// Wrong Example ?
+// Wrong Example ❌
 // Server 1: WorkerId=1, DataCenterId=1
-// Server 2: WorkerId=1, DataCenterId=1  ¡û Will produce duplicate IDs
+// Server 2: WorkerId=1, DataCenterId=1  ← Will produce duplicate IDs
 
-// Correct Example ?
+// Correct Example ✅
 // Server 1: WorkerId=1, DataCenterId=1
 // Server 2: WorkerId=2, DataCenterId=1
 // Server 3: WorkerId=1, DataCenterId=2
@@ -396,13 +398,13 @@ Ensure each machine has a unique `WorkerId` and `DataCenterId` combination:
 ### 4. What if Performance is Below Expectations?
 
 **Checklist**:
-- ? Use singleton pattern (`AddSingleton`)
-- ? Avoid frequent creation of `DefaultIDGenerator` instances
-- ? Choose Method 1 for single-machine high concurrency
-- ? Choose Method 3 for distributed scenarios
-- ? Check for duplicate WorkerIds
-- ? Use Release mode build
-- ? Ensure stable system clock
+- ✅ Use singleton pattern (`AddSingleton`)
+- ✅ Avoid frequent creation of `DefaultIDGenerator` instances
+- ✅ Choose Method 1 for single-machine high concurrency
+- ✅ Choose Method 3 for distributed scenarios
+- ✅ Check for duplicate WorkerIds
+- ✅ Use Release mode build
+- ✅ Ensure stable system clock
 
 ## License