深入 Biome 代码评审：Workspace 访问并发模型、LSP 取消语义与数据库读写安全

• 开发工具
• Lint
• 格式化
• 静态分析
• 代码质量
• 前端

本文围绕 Biome（biome_servicecrate）的 Workspace 访问契约展开，系统讲解Workspace接口背后隐藏的两种数据库执行模式（CLI 共享只读快照 / LSP 独占可变数据库）、pending-write 取消的正常控制流语义、Read/Resolve/Commit 安全读写形状，以及一份可直接落地的代码评审严重性分级检查清单。读完你将掌握：如何在 Biome 源码中定位并验证 Workspace 相关竞态、死锁与取消处理缺陷，如何以源码证据（而非历史函数名）支撑评审结论。

背景：Workspace接口与数据库的两种执行模式

在 Biome 中，Workspace是服务端能力对外的统一抽象。它的定义位于 crates/biome_service/src/workspace.rs，签名要求实现类型满足Send + Sync + RefUnwindSafe：

pub trait Workspace: Send + Sync + RefUnwindSafe { // #region PROJECT-LEVEL METHODS fn open_project(&self, params: OpenProjectParams) -> Result<OpenProjectResult, WorkspaceError>; fn scan_project(&self, params: ScanProjectParams) -> Result<ScanProjectResult, WorkspaceError>; fn update_settings(&self, params: UpdateSettingsParams) -> Result<UpdateSettingsResult, WorkspaceError>; fn close_project(&self, params: CloseProjectParams) -> Result<(), WorkspaceError>; // #region FILE-LEVEL METHODS（open_file / change_file / process_file / pull_diagnostics / format_file ...） }

该接口同时被 CLI、LSP、daemon 进程桥接等多种客户端使用，但接口本身并不暴露存储模型——两种数据库模式被隐藏在接口背后。这正是代码评审的第一课：评审 Workspace 相关代码时，必须明确当前调用方运行在哪种模式下，因为同样的代码在不同模式下会产生完全不同的并发语义。

两种执行模式对照

依据 crates/biome_service/src/db/state.rs 的模块级文档，DbState支持两种存储模式：

两种模式共享同一套 Salsa 底层存储与 Workspace 集合句柄，区别在于DbState是否持有一个规范（canonical）的WorkspaceDb值：

• Shared 模式（DbStorage::Shared）：仅保留一个SharedWorkspaceDb，它包含共享的存储和集合句柄，但没有 Salsa 本地状态。每次操作从这些句柄构造一个临时的WorkspaceDb。不存在可供修改的规范数据库值，操作通过共享集合发布自己的结果。
• Owned 模式（DbStorage::Owned）：在OwnedDb内保留唯一一个规范的WorkspaceDb。读操作使用该数据库的克隆；需要写规范数据库的操作通过OwnedDb::with_setter运行，它会锁住数据库并协调写操作与未完成的读克隆之间的关系。

这一所有权差异直接决定了 Salsa 支撑值如何被更新：Shared 模式下的临时 fork 可以分配一个替换 input 并通过共享集合发布句柄，但绝不能调用 Salsa setter——setter 等待 Salsa 存储的独占访问，而只要保留的共享句柄还存活，独占访问就无法获得，必然死锁。Owned 模式下，Salsa 字段 setter 通过with_setter运行，Salsa 可以取消过期的查询，并在修改被跟踪字段前等待读克隆被丢弃。

源码中的ProjectUpdateMode枚举（crates/biome_service/src/db/mod.rs）精确地固化了这一约束：Replace（分配替换 input 并发布句柄，仅用于操作局部的 Shared fork）与Setters（保留既有 input、通过 Salsa setter 改字段，仅用于 Owned 模式下的OwnedDb::with_setter）。其文档直言：从 Shared 模式传Setters会因为 Salsa 无法在保留的共享句柄存活时获得独占存储访问而死锁；从 Owned 模式传Replace则会改变项目的 Salsa 身份并遗留已分配 input。

评审提示：Workspace内部结构会随版本演进。文档强调，在引用任何关于两种模式的结论前，应回到当前构造函数与调用点验证——例如LocalWorkspace::new、WorkspaceServer::new（见 crates/biome_service/src/workspace/server.rs）以及DbState::fork的当前实现。

CLI 模式审查：共享只读快照下的发布竞态

CLI 的项目扫描流程大体是：scan_project遍历整个项目、解析所有文件、提取服务数据并缓存（首次调用很慢，后续复用缓存，见 workspace.rs）；扫描完成后，per-file workers 并行处理文件。

在 Shared 模式下，扫描后数据库处于“共享、只读”状态：每个 worker 从共享句柄 fork 出临时数据库读取快照，而文件系统写入（格式化落盘、lint 修复等）发生在数据库之外，不经过数据库写 API。这意味着：

• 在并行处理期间，任何 worker不得向数据库发布（publish）workspace 状态，否则其他仍持有快照的 worker 会读到被并发修改的状态。
• 评审时必须追踪发布调用的快照生命周期与写顺序，建立可到达的竞态或死锁路径，而不能只凭“这个函数看起来在写”下结论——位置（location）本身不足以定罪，必须证明可达性（reachability）。

具体到 changed 同步（文件变更传播）：应基于当前执行契约检查读/写、写/写之间的重叠，而不是基于调度偏好（scheduling preferences）推测。也就是说，评审关注的是“这段代码在契约下是否可能重叠访问”，而非“某个调度器通常不会让它们重叠”。

源码侧的一个佐证：WorkspaceDbData（crates/biome_service/src/db/mod.rs）把files、modules、file_sources、projects等集合以Arc句柄形式与所有克隆共享，其文档明确指出：通过该类型做的更新对所有克隆立即可见、无需加锁。这正好对应 Shared 模式的发布通道——但如果在一个仍在读取快照的上下文中错误地发布，则会造成无锁的可见性变更，进而破坏一致性。评审应关注：发布方与快照持有方之间是否存在契约允许的并发窗口。

另外，WorkspaceServer中的node_cache是Mutex<FxHashMap<Utf8PathBuf, NodeCache>>（server.rs），其注释专门强调“node cache 只被 writers 使用……需要注意死锁，并尽快释放 mutex guard”——这提醒评审者：在只读路径中引入对该 Mutex 的持有，或跨数据库操作持有该 guard，都是典型死锁候选。

LSP 取消审查：PendingWrite 是正常控制流

LSP 使用 Owned 模式：数据库长期存活、可被修改。当一次写操作（如change_file触发的文档更新）通过with_setter获得独占访问权时，Salsa 会取消仍在使用旧数据读取的查询。这种取消不是错误，而是设计内的正常控制流。

取消如何映射到 LSP 响应

在 crates/biome_lsp/src/utils.rs 中，cancelled_to_lsp_error将salsa::Cancelled映射为 LSP 错误：

pub(crate) fn cancelled_to_lsp_error(cancelled: salsa::Cancelled) -> LspError { let mut error = match cancelled { salsa::Cancelled::PendingWrite => LspError::content_modified(), salsa::Cancelled::PropagatedPanic => LspError::internal_error(), _ => LspError::request_cancelled(), }; error.message = Cow::Owned(cancelled.to_string()); error.data = Some(format!("{cancelled:?}").into()); }

• PendingWrite→ContentModified：编辑器收到后会自动重新发送请求（重试路径）；
• PropagatedPanic→ internal error；
• 其他取消 → request cancelled。

LSP 会话层对ContentModified的定位在 crates/biome_lsp/src/session.rs 有明确注释：回答ContentModified会让编辑器重发请求。而 crates/biome_lsp/src/server.rs 中的catch_lsp_operation用salsa::Cancelled::catch包裹操作，确保取消以salsa::Cancelled值的形式被捕获并沿 LSP 错误通道传播，而不是变成 panic。

自动重试：RetryingWorkspace

对于不希望自行处理中断的调用方（典型如 CLI），Biome 提供RetryingWorkspace（workspace.rs）：它包装另一个Workspace，将除scan_project、fs、server_info之外的所有短操作通过retry_on_pending_write包装，被并发更新中断时自动重试。其文档明示：LSP 请求处理器如果更愿意自己处理中断（用ContentModified让编辑器重发），则应直接调用内部 workspace，而不是包一层RetryingWorkspace。同时，项目扫描被委派且不重试——因为 scanner epoch 会把基于 setter 的写操作排队到遍历完成之后。

对应地，ScannerTestState::enter_project_scan（server.rs）提供了一个测试钩子：在首次扫描尝试时以std::panic::resume_unwind(Box::new(salsa::Cancelled::PendingWrite))取消扫描，验证RetryingWorkspace会传播被中断的项目扫描而不是重启完整遍历——这直接印证了“scan_project 不重试”的契约。

取消边界检查清单

文档要求对 LSP 取消路径逐项核验：

1. 读处理器运行在当前的取消边界内——即读取必须经由salsa::Cancelled::catch等边界包裹，取消能够以值的形式逃逸，而不是绕过边界；
2. 取消映射到编辑器的 content-modified 响应或既定的重试路径——对应cancelled_to_lsp_error的PendingWrite → ContentModified；
3. 没有新的unwrap、panic、log-and-continue 或通用硬错误拦截取消——任何在取消路径上新增的unwrap/panic 都会把正常取消变成崩溃；log-and-continue会吞掉取消信号导致 LSP 卡在过期状态；
4. 调用方在发起写操作时不得保留数据库 fork——持有读 fork（DbReadGuard）的同时发起写，正是 Read/Resolve/Commit 一节要讲的死锁形态。

数据库侧的实现细节同样关键：DbState::fork()（state.rs）返回DbReadGuard；而 Owned 模式下，当有 setter pending 时再调用fork，实现会以salsa::Cancelled::PendingWrite展开（resume_unwind(Box::new(salsa::Cancelled::PendingWrite))，见 state.rs）而不是阻塞等待——这就是“有写 pending 时读可被取消”的落地实现。DbReadGuard被静态断言为!Send（state.rs），防止 guard 被跨线程携带。测试用例（state.rs）用salsa::Cancelled::catch验证：pending 写入期间 fork 得到Err(salsa::Cancelled::PendingWrite)而非阻塞。

Read / Resolve / Commit：避免自死锁的安全读写形状

文档给出一个关键的死锁形态：一个函数在同一个调用栈中通过数据库 fork 读、又通过同一个数据库写，会死锁等待自己的读句柄。

原因可以从 Salsa 语义推演：Salsa setter 需要存储的独占访问权，而只有当一个数据库的所有克隆都被丢弃后它才能获得该访问权；如果当前线程还持有自己的读 fork（DbReadGuard），那么写操作等待的“所有克隆被丢弃”永远不会发生——线程在等自己。WorkspaceDbData的文档（db/mod.rs）也印证了这一点：setter 只能在数据库的每个克隆都被 drop 后运行，而仍持有克隆的线程必须能够独立完成其工作，不能等待保护数据库的锁。

因此，凡是“读数据库 → 解析/变换 → 写回数据库”的流程，安全形状必须是文档给出的四步：

1. Extract（提取）：持有读 fork 时，提取 owned 输入（把需要的数据从数据库拷贝/克隆出来）；
2. Drop（丢弃）：通过离开其作用域（scope）丢弃 fork——显式离开作用域，让DbReadGuard在写操作开始前释放；
3. Resolve（解析/变换）：在 owned 数据上做解析、变换、计算；
4. Commit（提交）：通过写 API（Owned 模式下是with_setter）提交。

一个反例模式是：持有 fork 的同时调用with_setter或 Salsa setter——这必然自死锁。评审时应搜索当前 Workspace 实现中已经确立的范例（而非依赖某个历史函数名），比如在读 fork 作用域内完成get_file_content之类的数据提取，作用域结束后再进入change_file/update_settings的写路径。

类似的死锁风险同样存在于数据库之外的锁：WorkspaceServer::node_cache的 Mutex 注释（server.rs）专门警告“release guards to the mutex as soon as we can”，因为跨数据库操作持有普通锁 guard 同样会制造持锁等待链。

评审严重性分级：候选问题 ≠ 自动发现

文档明确强调：以下清单项是候选（candidates），不是自动发现（automatic findings）。评审者必须先建立可达性（reachability）并确认受影响行为（affected behavior），再按影响面定级。这符合 Biome 代码评审的严谨要求——位置证据不足，必须证明路径。

五项核心候选

关于“Salsa 查询遗漏依赖”的补充解读

第五项需要结合 state.rs 的模块文档理解：Salsa 会跟踪对已知 input 字段的读取，但不会自动跟踪对外部查找集合（如 Papaya map）的变化——包括新增 key、删除 key、既有 key 指向替换 input。因此：

• 如果查询用该集合发现 Salsa inputs，查询必须首先读取该集合的mutable Salsa-tracked change signal。一个路径、map key 或 Salsa input ID 都不是这样的信号：它标识条目，但不会在外部集合变化时改变。
• 两种成熟方案：整表代际计数器（每个 map 变更递增同一计数器，所有读取它的查询失效；ModuleGraphGeneration正是这个设计，因为模块路径 map 存储在 Salsa 外部）；或每个 map key 一个稳定 Salsa input（例如src/index.js始终对应同一 input，带 tracked 的exists: bool与revision: u64字段；删除文件将exists置false，重建/修改则更新exists或revision，Salsa 只失效读取该 input 的查询）。
• 修改外部集合时：Owned 模式可以在with_setter内用 Salsa setter 更新 change signal；Shared 模式不能调用 setter，必须设计集合专属的替换或失效机制——直接改共享集合而不提供该设计，即构成评审候选。

定级原则

• 建立可达性：该路径在当前执行契约下是否真的可能发生（如并行 worker 是否可能同时持有快照与发布句柄；LSP 写操作是否确实经过with_setter与取消边界）；
• 确认受影响行为：可达后，用户可观察的影响是什么（错误的诊断结果、格式结果、编辑器请求重发风暴、daemon 崩溃）；
• 按影响分级：影响仅限单文件结果异常 → 中低；影响整个 LSP 会话稳定性或 daemon 死锁 → 高。候选本身不应直接作为缺陷上报，必须带有路径推演与影响论证。

附：评审前的源码定位速查

• Workspacetrait 定义与全部方法签名：crates/biome_service/src/workspace.rs
• RetryingWorkspace与retry_on_pending_write宏：crates/biome_service/src/workspace.rs
• WorkspaceServer/LocalWorkspace/WorkspaceServerWithDb构造：crates/biome_service/src/workspace/server.rs
• DbState两种存储模式的权威文档：crates/biome_service/src/db/state.rs
• DbReadGuard、fork与PendingWrite展开逻辑：crates/biome_service/src/db/state.rs、crates/biome_service/src/db/state.rs
• WorkspaceDb与WorkspaceDbData结构：crates/biome_service/src/db/mod.rs
• LSP 取消到ContentModified的映射：crates/biome_lsp/src/utils.rs
• 扫描并发测试钩子（取消首次扫描验证不重试）：crates/biome_service/src/workspace/server.rs

最后再次强调文档的提醒：workspace 内部实现会变化。本文引用的结构、函数与行号均对应当前仓库快照；进行评审时，请先验证当前构造点与调用点，再引用这些结论。评审的价值不在于机械套用候选清单，而在于理解两种数据库模式的本质差异，用可达性推演替代位置判断，用影响面定级替代“看起来有问题”。

• 开发工具
• Lint
• 格式化
• 静态分析
• 代码质量
• 前端