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

Download history 470/week @ 2024-05-04 791/week @ 2024-05-11 634/week @ 2024-05-18 606/week @ 2024-05-25 536/week @ 2024-06-01 516/week @ 2024-06-08 456/week @ 2024-06-15 615/week @ 2024-06-22 562/week @ 2024-06-29 798/week @ 2024-07-06 607/week @ 2024-07-13 744/week @ 2024-07-20 581/week @ 2024-07-27 988/week @ 2024-08-03 515/week @ 2024-08-10 825/week @ 2024-08-17

2,981 每月下载量
用于 4 crates

Apache-2.0

76KB
1.5K SLoC

uuid7

Crates.io License

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