Giao diện
@digiforce-nc/snowflake-id
Package @digiforce-nc/snowflake-id - bộ sinh ID phân tán kiểu Snowflake 53-bit, an toàn cho JavaScript và MySQL.
1) Tổng quan
Snowflake ID là thuật toán sinh ID duy nhất, có thứ tự thời gian, không cần cơ sở dữ liệu trung tâm. Package này triển khai biến thể 53-bit thay vì 64-bit gốc của Twitter.
Tại sao 53-bit?
| Ràng buộc | Giá trị | Lý do |
|---|---|---|
Number.MAX_SAFE_INTEGER | 2^53 − 1 | JavaScript chỉ biểu diễn chính xác số nguyên ≤ 53 bit |
MySQL BIGINT | 8 bytes | Lưu trữ thoải mái, không mất dữ liệu |
| JSON serialization | an toàn | Không cần chuyển sang string khi truyền qua API |
Với 53 bit, ID vẫn đảm bảo tính duy nhất trong hệ thống phân tán với hàng triệu bản ghi mỗi ngày.
2) Cấu trúc ID
|-- timestamp (41 bit) --|-- workerId (4 bit) --|-- sequence (8 bit) --|| Thành phần | Số bit | Mô tả |
|---|---|---|
| timestamp | 41 | Mili-giây tính từ epoch. Đủ dùng ~69 năm. |
| workerId | 4 | Định danh worker/node (0–15). |
| sequence | 8 | Số thứ tự trong cùng mili-giây (0–255). |
Tổng: 41 + 4 + 8 = 53 bit - nằm trong Number.MAX_SAFE_INTEGER.
3) API
Constructor
typescript
import { Snowflake } from '@digiforce-nc/snowflake-id';
const snowflake = new Snowflake({
workerId: 1, // 0–15, mặc định 0
epoch: 1609459200000, // mốc thời gian gốc (ms), mặc định 2021-01-01
});| Option | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
workerId | number | 0 | ID của worker/node trong hệ thống phân tán (0–15) |
epoch | number | 1609459200000 | Mốc thời gian cơ sở (Unix ms) |
generate()
Sinh một ID mới, trả về number.
typescript
const id = snowflake.generate();
// 6842512345678901Mỗi lần gọi trả về ID tăng dần, duy nhất trong cùng worker.
parse(id)
Phân tách ID thành các thành phần gốc.
typescript
const parts = snowflake.parse(id);
// {
// timestamp: 1672531200123,
// workerId: 1,
// sequence: 42
// }| Trường | Kiểu | Mô tả |
|---|---|---|
timestamp | number | Unix timestamp (ms) tuyệt đối |
workerId | number | ID worker đã sinh |
sequence | number | Số thứ tự trong mili-giây đó |
4) Ví dụ sử dụng
typescript
import { Snowflake } from '@digiforce-nc/snowflake-id';
const sf = new Snowflake({ workerId: 3 });
// Sinh 5 ID liên tiếp
const ids = Array.from({ length: 5 }, () => sf.generate());
console.log(ids);
// [6842512345678901, 6842512345678902, ...]
// Parse để kiểm tra
const info = sf.parse(ids[0]);
console.log(`Sinh lúc: ${new Date(info.timestamp).toISOString()}`);
console.log(`Worker: ${info.workerId}, Sequence: ${info.sequence}`);5) Lưu ý
Không có dependency ngoài - package hoàn toàn standalone.
Worker ID phải duy nhất giữa các instance trong cùng hệ thống để tránh trùng ID.
Sequence overflow (>255 trong 1ms) sẽ chờ đến mili-giây tiếp theo.
ID có thứ tự thời gian - có thể dùng để sắp xếp gần đúng theo thời gian tạo.