27次发布 (2个稳定版本)
1.0.1 | 2024年8月17日 |
---|---|
1.0.0 | 2024年5月11日 |
0.7.2 | 2023年9月18日 |
0.7.0 | 2023年7月31日 |
0.2.6 | 2022年6月23日 |
#50 in Unix API
2,981 每月下载量
用于 4 crates
76KB
1.5K SLoC
uuid7
UUID版本7的Rust实现
let uuid = uuid7::uuid7();
println!("{}", uuid); // e.g., "01809424-3e59-7c05-9219-566f82fff672"
println!("{:?}", uuid.as_bytes()); // as 16-byte big-endian array
let uuid_string: String = uuid7::uuid7().to_string();
参阅 RFC 9562.
字段和位布局
此实现生成的标识符具有以下位布局
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| unix_ts_ms |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| unix_ts_ms | ver | counter |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var| counter |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| rand |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
其中
- 48位的
unix_ts_ms
字段专门用于Unix时间戳(毫秒)。 - 4位的
ver
字段设置为0111
。 - 42位的
counter
字段容纳一个计数器,确保在毫秒内生成的ID的顺序递增。每次生成新的ID时,计数器递增1,当unix_ts_ms
发生变化时,计数器重置为随机数。 - 2位的
var
字段设置为10
。 - 剩余的32位
rand
用一个密码学上强随机数填充。
42位的 counter
足够大,因此您通常无需担心溢出,但在极其罕见的情况下溢出,此库将递增 unix_ts_ms
字段以继续生成单调的实例。因此,unix_ts_ms
的值可能大于系统实时时钟的值。
UUIDv7,根据设计,依赖于系统时钟以保证生成的ID顺序单调递增。如果系统时钟回退,生成器可能无法生成单调序列。此库忽略时钟回退并重用之前的 unix_ts_ms
,除非认为时钟回退是重大的(默认情况下,超过十秒)。如果发生此类重大回退,此库默认重置生成器,从而破坏生成的ID的递增顺序。
crates功能
默认功能
std
将库与系统时钟等集成,以获取当前时间戳。在没有std
的情况下,此crates在no_std
环境下提供有限的功能。global_gen
(表示std
)启用了主要的uuid7()
函数以及底层的进程级全局生成器。
可选功能
serde
启用了Uuid
对象的序列化和反序列化。uuid
(与global_gen
一起)启用了返回流行的uuidcrate的Uuid
对象的new_v7()
函数。
其他功能
此库还支持生成UUID版本4
let uuid = uuid7::uuid4();
println!("{}", uuid); // e.g., "2ca4b2ce-6c13-40d4-bccf-37d222820f6f"
V7Generator
提供了一个接口,允许更精细地控制UUIDv7生成的各个方面
use uuid7::V7Generator;
let mut g = V7Generator::new(rand::rngs::OsRng);
let custom_unix_ts_ms = 0x0123_4567_8901u64;
let x = g.generate_or_reset_core(custom_unix_ts_ms, 10_000);
println!("{}", x);
let y = g
.generate_or_abort_core(custom_unix_ts_ms, 10_000)
.expect("clock went backwards by more than 10_000 milliseconds");
println!("{}", y);
许可证
根据Apache许可证版本2.0授权。
另请参阅
依赖项
~0.3–0.8MB
~14K SLoC