跳至主要内容
本页内容

键空间

Deno KV 是一个键值存储。键空间是由键+值+版本戳三元组组成的扁平命名空间。键是由键部分组成的序列，允许对分层数据进行建模。值是任意的 JavaScript 对象。版本戳表示值的插入/修改时间。

键 跳转到标题

Deno KV 中的键是由键部分组成的序列，键部分可以是字符串 (string)、数字 (number)、布尔值 (boolean)、Uint8Array 或大整数 (bigint)。

使用一系列部分而不是单个字符串可以消除分隔符注入攻击的可能性，因为没有可见的分隔符。

当攻击者通过将键编码方案中使用的分隔符注入用户控制的变量来操纵键值存储的结构时，就会发生键注入攻击，从而导致意外行为或未经授权的访问。例如，考虑一个使用斜杠 (/) 作为分隔符的键值存储，其键类似于“users/alice/settings”和“users/bob/settings”。攻击者可以创建一个名为“alice/settings/hacked”的新用户，以形成键“users/alice/settings/hacked/settings”，从而注入分隔符并操纵键结构。在 Deno KV 中，注入将导致键 ["users", "alice/settings/hacked", "settings"]，这不会造成危害。

在键部分之间，使用不可见的分隔符来分隔各个部分。这些分隔符永远不可见，但可确保一个部分不会与另一个部分混淆。例如，键部分 ["abc", "def"]、["ab", "cdef"]、["abc", "", "def"] 都是不同的键。

键是区分大小写的，并按其组成部分按字典顺序排序。第一部分最重要，最后一部分最不重要。各部分的顺序由部分的类型和值决定。

键部分排序 跳转到标题

键的各部分按其类型按字典顺序排序，在给定类型内，它们按其值排序。类型的排序如下：

  1. Uint8Array
  2. string
  3. number
  4. bigint
  5. boolean

在给定类型内，排序如下：

  • Uint8Array：数组的字节顺序
  • string：字符串的 UTF-8 编码的字节顺序
  • number：-Infinity < -1.0 < -0.5 < -0.0 < 0.0 < 0.5 < 1.0 < Infinity < NaN
  • bigint：数学顺序，最大的负数在前，最大的正数在后
  • boolean：false < true

这意味着部分 1.0（一个数字）排在部分 2.0（也是一个数字）之前，但大于部分 0n（一个 bigint），因为 1.0 是一个数字，而 0n 是一个 bigint，类型排序优先于类型内值的排序。

键示例 跳转到标题

["users", 42, "profile"]; // User with ID 42's profile
["posts", "2023-04-23", "comments"]; // Comments for all posts on 2023-04-23
["products", "electronics", "smartphones", "apple"]; // Apple smartphones in the electronics category
["orders", 1001, "shipping", "tracking"]; // Tracking information for order ID 1001
["files", new Uint8Array([1, 2, 3]), "metadata"]; // Metadata for a file with Uint8Array identifier
["projects", "openai", "tasks", 5]; // Task with ID 5 in the OpenAI project
["events", "2023-03-31", "location", "san_francisco"]; // Events in San Francisco on 2023-03-31
["invoices", 2023, "Q1", "summary"]; // Summary of Q1 invoices for 2023
["teams", "engineering", "members", 1n]; // Member with ID 1n in the engineering team

通用唯一按字典顺序排序的标识符 (ULID) 跳转到标题

键部分排序允许按时间顺序列出由时间戳和 ID 部分组成的键。通常，您可以使用以下方法生成键：Date.now() 和 crypto.randomUUID()

async function setUser(user) {
  await kv.set(["users", Date.now(), crypto.randomUUID()], user);
}

顺序多次运行，会生成以下键

["users", 1691377037923, "8c72fa25-40ad-42ce-80b0-44f79bc7a09e"]; // First user
["users", 1691377037924, "8063f20c-8c2e-425e-a5ab-d61e7a717765"]; // Second user
["users", 1691377037925, "35310cea-58ba-4101-b09a-86232bf230b2"]; // Third user

然而，在某些情况下，将时间戳和 ID 表示在单个键部分内可能更简单。您可以使用通用唯一按字典顺序排序的标识符 (ULID) 来实现这一点。这种类型的标识符编码 UTC 时间戳，可按字典顺序排序，并且默认情况下是加密随机的。

import { ulid } from "jsr:@std/ulid";

const kv = await Deno.openKv();

async function setUser(user) {
  await kv.set(["users", ulid()], user);
}

["users", "01H76YTWK3YBV020S6MP69TBEQ"]; // First user
["users", "01H76YTWK4V82VFET9YTYDQ0NY"]; // Second user
["users", "01H76YTWK5DM1G9TFR0Y5SCZQV"]; // Third user

此外，您可以使用 monotonicUlid 函数单调递增地生成 ULID。

import { monotonicUlid } from "jsr:@std/ulid";

async function setUser(user) {
  await kv.set(["users", monotonicUlid()], user);
}

// Strict ordering for the same timestamp by incrementing the least-significant random bit by 1
["users", "01H76YTWK3YBV020S6MP69TBEQ"]; // First user
["users", "01H76YTWK3YBV020S6MP69TBER"]; // Second user
["users", "01H76YTWK3YBV020S6MP69TBES"]; // Third user

值 跳转到标题

Deno KV 中的值可以是与 结构化克隆算法 兼容的任意 JavaScript 值。这包括：

  • undefined
  • null
  • boolean
  • number
  • string
  • bigint
  • Uint8Array
  • Array
  • Object
  • Map
  • Set
  • Date
  • RegExp

对象和数组可以包含上述任何类型，包括其他对象和数组。Map 和 Set 可以包含上述任何类型，包括其他 Map 和 Set。

支持值内的循环引用。

不支持具有非原始原型的对象（例如类实例或 Web API 对象）。函数和符号也不能被序列化。

Deno.KvU64 类型 跳转到标题

除了结构化可序列化值之外，特殊值 Deno.KvU64 也被支持作为值。此对象表示一个 64 位无符号整数，表示为 bigint。它可以与 sum、min 和 max KV 操作一起使用。它不能存储在对象或数组中。它必须作为顶级值存储。

可以使用 Deno.KvU64 构造函数创建它。

const u64 = new Deno.KvU64(42n);

值示例 跳转到标题

undefined;
null;
true;
false;
42;
-42.5;
42n;
"hello";
new Uint8Array([1, 2, 3]);
[1, 2, 3];
{ a: 1, b: 2, c: 3 };
new Map([["a", 1], ["b", 2], ["c", 3]]);
new Set([1, 2, 3]);
new Date("2023-04-23");
/abc/;

// Circular references are supported
const a = {};
const b = { a };
a.b = b;

// Deno.KvU64 is supported
new Deno.KvU64(42n);

版本戳 跳转到标题

Deno KV 键值空间中的所有数据都有版本控制。每次插入或修改值时，都会为其分配一个版本戳。版本戳是单调递增的、非连续的 12 字节值，表示值被修改的时间。版本戳不代表实际时间，而是代表值被修改的顺序。

由于版本戳是单调递增的，因此它们可以用来确定一个给定值是比另一个值更新还是更旧。这可以通过比较两个值的版本戳来完成。如果版本戳 A 大于版本戳 B，则值 A 比值 B 修改得更晚。

versionstampA > versionstampB;
"000002fa526aaccb0000" > "000002fa526aacc90000"; // true

由单个事务修改的所有数据都被分配相同的版本戳。这意味着如果在同一个原子操作中执行两个 set 操作，则新值的版本戳将相同。

版本戳用于实现乐观并发控制。原子操作可以包含检查，以确保它们操作的数据的版本戳与传递给操作的版本戳匹配。如果数据的版本戳与传递给操作的版本戳不同，则事务将失败，并且操作将不会应用。