Web Locks API 允许不同标签页、iframe 或 Worker 之间协调异步任务，防止多个执行上下文同时修改同一份状态。在 TypeScript 项目中，虽然 lib.dom 已经提供了基本的 LockManager 定义，但默认类型往往比较宽松，而且没有把竞争策略抽象成便于业务复用的形态。要在类型层面表达排他锁、共享锁、立即获取和可取消等待这些概念，需要我们自己定义若干接口和类型别名。下面从锁模式的基本类型开始，逐步构建一套安全的资源锁定类型工具。
一、锁模式与选项对象的基本类型
Web Locks API 的核心入口是 navigator.locks.request(name, options, callback)。第二个参数 options 决定锁的竞争策略，其中 mode 字段只能取 exclusive 或 shared 两个字符串字面量。在 TypeScript 中，如果将 mode 定义为宽泛的 string，就会丢失编译期检查能力。正确的做法是使用联合类型，让非法值在写入代码时立刻报错。同时，options 还包括 ifAvailable、steal 和 signal 三个会影响获取行为的字段：ifAvailable 为 true 时锁不可用就直接回调并传入 null，不会排队；steal 用于抢占已持有的锁，但兼容性较差；signal 允许通过 AbortSignal 取消等待中的请求。
定义这些字段时，建议将 mode 独立成类型别名，再组合成完整的选项接口。这样做的好处是后续业务代码可以单独引用 LockMode，而不必重复书写字符串字面量。下面是一个最小但完整的类型定义：
type LockMode = 'exclusive' | 'shared';
interface LockOptions {
mode?: LockMode;
ifAvailable?: boolean;
steal?: boolean;
signal?: AbortSignal;
}
这段代码中 LockMode 只有两个可取值。exclusive 代表排他锁，同一时刻只允许一个请求持有该名称的锁；shared 代表共享锁，允许多个共享持有者同时运行，但排他锁与共享锁之间互斥。理解这一点很关键，因为竞争策略不仅仅是先谁后谁的问题，还涉及锁的兼容性。例如，如果所有请求都使用 shared 模式，它们可以并发执行，而一旦出现 exclusive 请求，它必须等待所有现有的共享锁释放后才能进入。
ifAvailable 和 steal 进一步改变了排队行为。默认情况下，如果锁被占用，请求会进入 FIFO 队列等待。ifAvailable 为 true 时，锁不可用会立即以 null 结果回调，适合缓存更新、日志上报等可跳过任务。steal 则会打断当前持有者强行获取锁，虽然可能造成状态不一致，但在清理陈旧锁或紧急恢复场景中可能用到。signal 则提供了一种优雅的退出机制，避免页面关闭后请求仍然悬挂。
二、为回调函数和返回值加上泛型约束
直接调用 navigator.locks.request 时，TypeScript 可能推断出比较模糊的返回类型。比如 options 未指定泛型时，回调参数 lock 的类型可能是 Lock | null，返回值类型也会被拓宽为 Promise<unknown>。为了在业务中明确锁内任务的结果类型，我们需要封装一个泛型函数，把类型参数 T 传递给 request，并约定回调既可以同步返回也可以返回 Promise。
在定义泛型回调签名时，建议使用类型别名 LockCallback<T>，这样后续多个函数可以复用。回调的 lock 参数不能假设一定非空，因为 ifAvailable 为 true 时可能是 null。因此签名要写成 (lock: Lock | null) => Promise<T> | T。下面封装一个 withLock 函数，它在内部调用原生 API，但对外暴露更简洁的类型：
type LockCallback<T> = (lock: Lock | null) => Promise<T> | T;
async function withLock<T>(
name: string,
options: LockOptions,
callback: LockCallback<T>
): Promise<T> {
return navigator.locks.request(name, options, callback);
}
上面的泛型约束使得调用方在编写回调时就能获得正确的 lock 类型提示，同时返回值类型会被自动推导。例如，如果回调返回一个 User 对象，那么 withLock 的返回值就是 Promise<User>，不必再手动断言。需要注意的是，navigator.locks.request 在某些旧版本 TypeScript 的 DOM 类型中可能只接受两个参数，此时最好补充全局声明或使用类型断言，但建议优先升级到较新的 TypeScript 版本以获得完整的 Web Locks API 类型支持。
此外，可以在业务层进一步限制 options。比如大部分写操作只需要排他锁，那就可以定义 ExclusiveLockOptions 接口，将 mode 固定为 exclusive，避免误传共享模式。同理，读操作可以使用 SharedLockOptions。这样锁的语义就被编码进了类型系统，代码审查时也能一眼看出某个函数要求的锁级别。
三、处理取消、不可用与错误回退
实际使用 Web Locks API 时，光有类型定义还不够，运行时行为同样需要类型层面的指导。例如，当 signal 被触发中止时，navigator.locks.request 返回的 Promise 会以 DOMException 拒绝，其 name 属性为 AbortError。如果我们在封装函数中不处理这个错误，调用方就要自己写 try/catch，而且容易把 AbortError 和普通业务错误混在一起。
一个更友好的做法是封装 tryAcquireLock，它在 ifAvailable 为 true 且锁不可用时返回 null，在 signal 中止时也返回 null 或抛出自定义异常。这样调用方拿到的是明确的联合类型 T | null，可以很自然地写出分支逻辑。下面的示例演示了如何区分锁不可用和请求被取消两种情况：
async function tryAcquireLock<T>(
name: string,
callback: (lock: Lock) => Promise<T> | T,
signal?: AbortSignal
): Promise<T | null> {
try {
return await navigator.locks.request(
name,
{ mode: 'exclusive', ifAvailable: true, signal },
async (lock) => {
if (!lock) {
return null;
}
return callback(lock);
}
);
} catch (err) {
if (err instanceof DOMException && err.name === 'AbortError') {
return null;
}
throw err;
}
}
在这段代码中，回调内部先判断 lock 是否为 null，是则直接返回 null，表示锁当前不可用。如果请求在等待期间被 signal 取消，则会抛出一个 DOMException，我们在 catch 中识别 AbortError 并返回 null。对于其他异常则原样抛出，不影响调用方的错误处理链。这种设计让返回类型 T | null 真实反映了任务成功执行返回结果和未获取锁之间的区别。
还需要注意 signal 的传递时机。AbortSignal 应该由调用方创建并管理，它可以来自 AbortController，也可以由框架或请求库提供。在类型上 signal 字段被定义为 AbortSignal 可选，因此调用方可以按需传入。如果不想依赖 DOMException 的判断，也可以自定义一个 LockAcquireError 类，在 catch 中转换异常类型，从而让错误处理更符合业务习惯。
四、用常量派生的字面量类型构建更健壮的锁管理器
当项目中有多个锁名称和锁模式时，直接散落字符串常量很容易出现拼写错误。利用 TypeScript 的 as const 断言，我们可以定义一组锁模式常量，并从中推导出联合类型，同时保留运行时对象。这样既能在代码中引用 LOCK_MODES.EXCLUSIVE 这样的名字，也能在类型注解中继续使用 LockMode。
const LOCK_MODES = {
EXCLUSIVE: 'exclusive',
SHARED: 'shared',
} as const;
type LockMode = typeof LOCK_MODES[keyof typeof LOCK_MODES];
这种方式的好处是避免了类型与常量值不同步的问题。未来如果新增一种锁模式，只需要在 LOCK_MODES 对象中加入新键值，LockMode 类型会自动更新。对于锁名称也可以用类似方式管理，例如定义一个 RESOURCE_LOCKS 常量对象，将所有资源名集中起来，防止不同模块之间使用不同的大小写或拼写。同时，我们还可以在 LockOptions 之上建立更高层的锁管理器，把 name、mode、ifAvailable 等字段组合成有业务含义的配置对象，让上层调用更简洁。
除了字符串字面量，竞争策略类型还可以扩展到信号和回调的组合上。例如可以定义 LockRequestConfig<T>，包含回调以及可选的取消控制器，使得调用方在一个对象中描述完整的锁请求。这种类型驱动的封装可以减少 API 误用，也能让 IDE 的自动补全发挥更大作用。最终，锁的竞争策略从散落的选项对象变成了一套可检查、可复用的类型体系，无论是在单个页面还是跨 Worker 的场景下，都能显著降低资源竞争引发的隐性 bug。
TypeScriptWeb Locks API竞争策略类型修改时间：2026-10-01 01:33:40