首页>编程相关>其他源码
下载

uuid

用于创建 RFC9562（以前称为 RFC4122）UUID

  • 完整- 支持所有 RFC9562 UUID 版本
  • 跨平台- 支持...
    • ESM 和通用 JS
    • Chrome、Safari、Firefox、Edge 浏览器
    • NodeJS
    • 反应本机/博览会
  • 安全- 加密强度强的随机值
  • 紧凑- 无依赖关系，可摇树
  • CLI - 包括uuid命令行实用程序
  • Typescript - 现在包含类型

笔记

w> uuid@11现已可用：有关详细信息，请参阅变更日志。长话短说：

  • 现在包含 TypeScript 支持（从依赖项中删除@types/uuid ）
  • 对v1() 、 v6()和v7() options arg 的解释方式进行了微妙的更改。查看详情
  • 二进制 UUID 现在是Uint8Array 。 （可能会影响parse() 、 stringify()的调用者或将option#buf参数传递给v1() - v7()的调用者。）

快速入门

1. 安装

npm install uuid

2.创建UUID

ESM 语法（必须使用命名导出）： 

 import { v4 as uuidv4 } from 'uuid' ;
uuidv4 ( ) ; // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

... CommonJS： 

 const { v4 : uuidv4 } = require ( 'uuid' ) ;
uuidv4 ( ) ; // ⇨ '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'

对于时间戳 UUID、命名空间 UUID 和其他选项，请继续阅读...

API摘要

uuid.NIL nil UUID 字符串（全为零） [email protected]中的新功能
uuid.MAX最大 UUID 字符串（全部为 1） [email protected]中的新功能
uuid.parse()将 UUID 字符串转换为字节数组[email protected]中的新功能
uuid.stringify()将字节数组转换为 UUID 字符串[email protected]中的新功能
uuid.v1()创建版本 1（时间戳）UUID
uuid.v1ToV6()从版本 1 UUID 创建版本 6 UUID uuid@10中的新功能
uuid.v3()创建版本 3（带 MD5 的命名空间）UUID
uuid.v4()创建版本 4（随机）UUID
uuid.v5()创建版本 5（带 SHA-1 的命名空间）UUID
uuid.v6()创建版本 6（时间戳、重新排序）UUID uuid@10中的新功能
uuid.v6ToV1()从版本 6 UUID 创建版本 1 UUID uuid@10中的新功能
uuid.v7()创建版本 7（基于 Unix Epoch 时间）的 UUID uuid@10中的新功能
uuid.v8() “故意留空”
uuid.validate()测试字符串以查看它是否是有效的 UUID [email protected]中的新功能
uuid.version()检测 UUID 的 RFC 版本[email protected]中的新功能

应用程序编程接口

uuid.NIL

nil UUID 字符串（全为零）。

例子： 

 import { NIL as NIL_UUID } from 'uuid' ;

NIL_UUID ; // ⇨ '00000000-0000-0000-0000-000000000000'

uuid.MAX

最大 UUID 字符串（全为 1）。

例子： 

 import { MAX as MAX_UUID } from 'uuid' ;

MAX_UUID ; // ⇨ 'ffffffff-ffff-ffff-ffff-ffffffffffff'

uuid.parse(str)

将 UUID 字符串转换为字节数组

str有效的 UUID String
回报Uint8Array[16]
投掷如果str不是有效的 UUID，则TypeError

笔记

parse()和stringify()使用的字节数组中的值的顺序遵循 UUID 字符串中十六进制对的左↠右顺序。如下例所示。

例子： 

 import { parse as uuidParse } from 'uuid' ;

// Parse a UUID
uuidParse ( '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b' ) ; // ⇨ 
  // Uint8Array(16) [
  //   110, 192, 189, 127,  17,
  //   192,  67, 218, 151,  94,
  //    42, 138, 217, 235, 174,
  //    11
  // ]

uuid.stringify(arr[, 偏移量])

将字节数组转换为 UUID 字符串

arr类似Array的 16 个值的集合（从offset开始），介于 0-255 之间。
[ offset =0] Number数组中的起始索引
回报String
投掷如果无法生成有效的 UUID 字符串，则TypeError

笔记

parse()和stringify()使用的字节数组中的值的顺序遵循 UUID 字符串中十六进制对的左↠右顺序。如下例所示。

例子： 

 import { stringify as uuidStringify } from 'uuid' ;

const uuidBytes = Uint8Array . of (
  0x6e ,
  0xc0 ,
  0xbd ,
  0x7f ,
  0x11 ,
  0xc0 ,
  0x43 ,
  0xda ,
  0x97 ,
  0x5e ,
  0x2a ,
  0x8a ,
  0xd9 ,
  0xeb ,
  0xae ,
  0x0b
) ;

uuidStringify ( uuidBytes ) ; // ⇨ '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'

uuid.v1([选项[,缓冲区[,偏移量]]])

创建 RFC 版本 1（时间戳）UUID

[ options ]具有以下一项或多项属性的Object ：
[ options.node = (random) ] RFC“节点”字段作为字节值的Array[6] （按照 4.1.6）
[ options.clockseq = (random) ] RFC“时钟序列”作为 0 - 0x3fff 之间的Number
[ options.msecs = (current time) ] RFC“时间戳”字段（毫秒Number ，unix 纪元）
[ options.nsecs = 0 ] RFC“时间戳”字段（添加到msecs的纳秒Number ，应为 0-10,000）
[ options.random = (random) ] 16 个随机字节 (0-255) 的Array ，用于生成上面的其他字段
[ options.rng ] options.random的替代方案，一个返回 16 个随机字节 (0-255) 的Array的Function
[ buffer ] Array | Buffer如果指定，uuid 将以字节形式写入此处，从offset开始
[ offset =0]开始在buffer中写入 UUID 字节Number索引
回报UUID 如果没有指定buffer String ，否则返回buffer
投掷如果每秒请求超过 10M UUID， Error

笔记

默认节点 ID（UUID 中的最后 12 位数字）在进程启动时随机生成一次，然后在进程持续时间内保持不变。

笔记

options.random和options.rng仅在第一次调用v1()时才有意义，可以传递它们来初始化内部node和clockseq字段。

例子： 

 import { v1 as uuidv1 } from 'uuid' ;

uuidv1 ( ) ; // ⇨ '2c5ea4c0-4067-11e9-9bdd-2b0d7b3dcb6d'

使用options的示例： 

 import { v1 as uuidv1 } from 'uuid' ;

const options = {
  node : Uint8Array . of ( 0x01 , 0x23 , 0x45 , 0x67 , 0x89 , 0xab ) ,
  clockseq : 0x1234 ,
  msecs : new Date ( '2011-11-01' ) . getTime ( ) ,
  nsecs : 5678 ,
} ;
uuidv1 ( options ) ; // ⇨ '710b962e-041c-11e1-9234-0123456789ab'

uuid.v1ToV6(uuid)

将 UUID 从版本 1 转换为版本 6 

 import { v1ToV6 } from 'uuid' ;

v1ToV6 ( '92f62d9e-22c4-11ef-97e9-325096b39f47' ) ; // ⇨ '1ef22c49-2f62-6d9e-97e9-325096b39f47'

uuid.v3(名称, 命名空间[, 缓冲区[, 偏移量]])

创建 RFC 版本 3（带 MD5 的命名空间）UUID

API 与v5()相同，但使用“v3”代替。

重要的

根据 RFC，“如果向后兼容性不是问题，则首选 SHA-1 [版本 5] 。”

uuid.v4([选项[,缓冲区[,偏移量]]])

创建 RFC 版本 4（随机）UUID

[ options ]具有以下一项或多项属性的Object ：
[ options.random .随机] 16 个随机字节Array (0-255)
[ options.rng ] options.random的替代方案，一个返回 16 个随机字节 (0-255) 的Array的Function
[ buffer ] Array | Buffer如果指定，uuid 将以字节形式写入此处，从offset开始
[ offset =0]开始在buffer中写入 UUID 字节Number索引
回报UUID 如果没有指定buffer String ，否则返回buffer

例子： 

 import { v4 as uuidv4 } from 'uuid' ;

uuidv4 ( ) ; // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

使用预定义random值的示例： 

 import { v4 as uuidv4 } from 'uuid' ;

const v4options = {
  random : Uint8Array . of (
    0x10 ,
    0x91 ,
    0x56 ,
    0xbe ,
    0xc4 ,
    0xfb ,
    0xc1 ,
    0xea ,
    0x71 ,
    0xb4 ,
    0xef ,
    0xe1 ,
    0x67 ,
    0x1c ,
    0x58 ,
    0x36
  ) ,
} ;
uuidv4 ( v4options ) ; // ⇨ '109156be-c4fb-41ea-b1b4-efe1671c5836'

uuid.v5(名称, 命名空间[, 缓冲区[, 偏移量]])

创建 RFC 版本 5（带 SHA-1 的命名空间）UUID

name String | Array
namespace String | Array[16]命名空间UUID
[ buffer ] Array | Buffer如果指定，uuid 将以字节形式写入此处，从offset开始
[ offset =0]开始在buffer中写入 UUID 字节Number索引
回报UUID 如果没有指定buffer String ，否则返回buffer

笔记

RFC DNS和URL命名空间可用作v5.DNS和v5.URL 。

自定义命名空间的示例： 

 import { v5 as uuidv5 } from 'uuid' ;

// Define a custom namespace.  Readers, create your own using something like
// https://www.uuidgenerator.net/
const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341' ;

uuidv5 ( 'Hello, World!' , MY_NAMESPACE ) ; // ⇨ '630eb68f-e0fa-5ecc-887a-7c7a62614681'

RFC URL命名空间示例： 

 import { v5 as uuidv5 } from 'uuid' ;

uuidv5 ( 'https://www.w3.org/' , uuidv5 . URL ) ; // ⇨ 'c106a26a-21bb-5538-8bf2-57095d1976c1'

uuid.v6([选项[,缓冲区[,偏移量]]])

创建 RFC 版本 6（时间戳、重新排序）UUID

此方法采用与 uuid.v1() 相同的参数。 

 import { v6 as uuidv6 } from 'uuid' ;

uuidv6 ( ) ; // ⇨ '1e940672-c5ea-64c0-9b5d-ab8dfbbd4bed'

使用options的示例： 

 import { v6 as uuidv6 } from 'uuid' ;

const options = {
  node : [ 0x01 , 0x23 , 0x45 , 0x67 , 0x89 , 0xab ] ,
  clockseq : 0x1234 ,
  msecs : new Date ( '2011-11-01' ) . getTime ( ) ,
  nsecs : 5678 ,
} ;
uuidv6 ( options ) ; // ⇨ '1e1041c7-10b9-662e-9234-0123456789ab'

uuid.v6ToV1(uuid)

将 UUID 从版本 6 转换为版本 1 

 import { v6ToV1 } from 'uuid' ;

v6ToV1 ( '1ef22c49-2f62-6d9e-97e9-325096b39f47' ) ; // ⇨ '92f62d9e-22c4-11ef-97e9-325096b39f47'

uuid.v7([选项[,缓冲区[,偏移量]]])

创建 RFC 版本 7（随机）UUID

[ options ]具有以下一项或多项属性的Object ：
[ options.msecs = (current time) ] RFC“时间戳”字段（毫秒Number ，unix 纪元）
[ options.random = (random) ] 16 个随机字节 (0-255) 的Array ，用于生成上面的其他字段
[ options.rng ] options.random的替代方案，一个返回 16 个随机字节 (0-255) 的Array的Function
[ options.seq = (random) ] 32 位序列 0 - 0xffffffff 之间的Number 。这可以被提供以帮助确保在同一毫秒时间间隔内生成的UUID的唯一性。默认值 = 随机值。
[ buffer ] Array | Buffer如果指定，uuid 将以字节形式写入此处，从offset开始
[ offset =0]开始在buffer中写入 UUID 字节Number索引
回报UUID 如果没有指定buffer String ，否则返回buffer

例子： 

 import { v7 as uuidv7 } from 'uuid' ;

uuidv7 ( ) ; // ⇨ '01695553-c90c-705a-b56d-778dfbbd4bed'

uuid.v8()

“故意留空”

笔记

版本 8（实验性）UUID“用于实验性或特定于供应商的用例”。 RFC 没有为它们定义创建算法，这就是为什么这个包不提供v8()方法。然而， validate()和version()方法确实适用于此类 UUID。

uuid.validate(str)

测试字符串以查看它是否是有效的 UUID

str要验证的String
回报如果字符串是有效的 UUID，则为true ，否则为false

例子： 

 import { validate as uuidValidate } from 'uuid' ;

uuidValidate ( 'not a UUID' ) ; // ⇨ false
uuidValidate ( '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b' ) ; // ⇨ true

一起使用validate和version可以进行每个版本的验证，例如仅验证 v4 UUId。 

 import { version as uuidVersion } from 'uuid' ;
import { validate as uuidValidate } from 'uuid' ;

function uuidValidateV4 ( uuid ) {
  return uuidValidate ( uuid ) && uuidVersion ( uuid ) === 4 ;
}

const v1Uuid = 'd9428888-122b-11e1-b85c-61cd3cbb3210' ;
const v4Uuid = '109156be-c4fb-41ea-b1b4-efe1671c5836' ;

uuidValidateV4 ( v4Uuid ) ; // ⇨ true
uuidValidateV4 ( v1Uuid ) ; // ⇨ false

uuid.版本(str)

检测 UUID 的 RFC 版本

str有效的 UUID String
回报Number UUID 的 RFC 版本
投掷如果str不是有效的 UUID，则TypeError

例子： 

 import { version as uuidVersion } from 'uuid' ;

uuidVersion ( '45637ec4-c85f-11ea-87d0-0242ac130003' ) ; // ⇨ 1
uuidVersion ( '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b' ) ; // ⇨ 4

笔记

对于NIL UUID，此方法返回0 ；对于MAX UUID，此方法返回15 。

命令行

可以使用uuid从命令行生成 UUID。 

$ npx uuid
ddeb27fb-d9a0-4624-be4d-4615062daed4

默认情况下生成版本 4 UUIDS，但也支持其他版本。输入uuid --help了解详细信息： 

$ npx uuid --help

Usage:
  uuid
  uuid v1
  uuid v3 < name > < namespace uuid >
  uuid v4
  uuid v5 < name > < namespace uuid >
  uuid v7
  uuid --help

Note: < namespace uuid > may be " URL " or " DNS " to use the corresponding UUIDs
defined by RFC9562

时间戳 UUID 的options处理

在uuid@11之前， options状态可能会干扰用于确保基于时间戳的 UUID 唯一性的内部状态（ v1() 、 v6()和v7()方法）。从uuid@11开始，这个问题已通过使用options参数的存在作为标志来在两种可能的行为之间进行选择来解决：

  • 不带options ：利用内部状态来提高 UUID 的唯一性。
  • 使用options ：不使用内部状态，而是根据需要应用适当的默认值。

支持

浏览器： uuid版本针对最新版本的桌面 Chrome、Safari、Firefox 和 Edge 进行了测试。这些浏览器的移动版本预计可以运行，但目前尚未经过测试。

Node ： uuid构建针对 Node（LTS 版本）以及之前的版本进行测试。例如， node@18处于维护模式， node@22是当前的 LTS 版本。所以uuid支持node@16 - node@22 。

Typescript ：支持过去两年内发布的 TS 版本。来源

已知问题

反应本机/博览会

  1. 安装react-native-get-random-values
  2. 在uuid之前导入它。由于uuid也可能显示为某些其他导入的传递依赖项，因此最安全的做法是导入react-native-get-random-values作为入口点的第一件事： 
 import 'react-native-get-random-values' ;
import { v4 as uuidv4 } from 'uuid' ;

从 README_js.md 生成的 Markdown

展开
附加信息
相关应用
为您推荐
相关资讯 全部