@scalar/workspace-store 深度指南：用分块加载与响应式工作区驾驭大型 OpenAPI 文档

scalar/workspace-store 深度指南用分块加载与响应式工作区驾驭大型 OpenAPI 文档【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar导读scalar/workspace-store是 Scalar 开源 API 平台中负责管理 OpenAPI 文档的存储层它同时提供**服务端Server-Side与客户端Client-Side**两套工作区存储实现服务端将大型 OpenAPI 文档拆分为可按需解析的分块chunk显著降低初始加载开销客户端则提供基于 Vue 响应式的内存工作区支持多文档管理、变更追踪、保存/回滚、覆盖与 rebase。读完本文你将掌握如何在 SSR 与静态站点两种模式下创建服务端工作区、如何按 JSON Pointer 按需取块以及如何在浏览器端构建可持久化、可覆盖、可合并上游变更的响应式文档工作区。一、为什么需要工作区存储大型 OpenAPI 文档的加载难题一个包含大量 schema、path operation 的 OpenAPI 文档可能高达数 MB。如果每次打开 API 文档页面都要把整份 JSON 一次性传输并解析初始加载时间会随文档体积线性恶化。scalar/workspace-store的解法是文档分块document chunking服务端在构建期把文档拆成稀疏文档 独立分块客户端只加载骨架与当前需要的块从而在源头上削减首屏载荷。从 package.json 可以看到该包定位为 Store interface for openapi documents依赖了scalar/openapi-upgrader版本升级、scalar/schemasschema 定义、scalar/validation校验、scalar/json-magic打包与 diff/merge、vue响应式与yaml序列化等内部与公共库包版本为 0.60.0要求 Node.js 22并以 ESM 方式发布。它对外暴露了./server、./client、./resolve、./schemas/*、./mutators、./persistence、./events等子路径便于按需引入。服务端与客户端分工明确能力服务端存储客户端存储分块/懒加载✅ 核心能力SSR/static✅ 消费分块并按需resolve响应式状态❌ 只读工作区载荷✅ Vuereactive工作区变更追踪❌✅ dirty 标记 插件事件广播持久化/导出❌✅ 双快照、JSON/YAML 导出上游合并rebase❌✅ 三方 diff/merge二、服务端工作区存储SSR 与静态两种模式服务端存储由createServerWorkspaceStore创建入口实现位于 server.ts。它接受三种文档输入document内存对象、url远程地址、path本地文件路径并根据mode分为两种行为ssr模式需要提供baseUrl生成的分块引用指向该 baseUrl 下的 API 端点如https://example.com/document-name/operations/~1planets/get#由服务端按需响应。static模式需要提供directory默认值为assets见 server.ts生成的引用指向文件系统中的相对路径如./chunks/document-name/operations/~1planets/get.json#适合静态站点托管。2.1 SSR 模式创建与使用// Create the store const store await createServerWorkspaceStore({ baseUrl: example.com, mode: ssr, meta: { x-scalar-active-document: document-name }, documents: [ { name: document-name, meta: {}, document: { openapi: 3.1.1, info: { title: Hello World, version: 1.0.0, }, components: { schemas: { Person: { type: object, properties: { name: { type: string }, }, }, User: { $ref: #/components/schemas/Person, }, }, }, }, }, ], }) // Add a new document to the store await store.addDocument( { openapi: 3.1.1, info: { title: Hello World, version: 1.0.0, }, components: { schemas: { Person: { type: object, properties: { name: { type: string }, }, }, User: { $ref: #/components/schemas/Person, }, }, }, }, { name: document-2, x-scalar-selected-server: server1, }, ) // Get the workspace // Workspace is going to keep all the sparse documents const workspace store.getWorkspace() // Get chucks using json pointers const chunk store.get(#/document-name/components/schemas/Person)getWorkspace()返回的 workspace 是稀疏文档集合每个文档只保留元数据、导航信息以及被外部化externalized为$ref的 components 与 operations。get(pointer)则按 JSON Pointer 从内存资产中取出对应分块指针既可以是#/document-name/...这种以#开头的本地形式也可以是绝对 URL——get内部会先剥离#前缀再把路径段经escapeJsonPointer处理后从资产树取值见 server.ts。2.2 static 模式生成文件系统分块// Create the store const store await createServerWorkspaceStore({ directory: assets, mode: static, meta: { x-scalar-active-document: document-name }, documents: [ { name: document-name, meta: {}, document: { openapi: 3.1.1, info: { title: Hello World, version: 1.0.0, }, components: { schemas: { Person: { type: object, properties: { name: { type: string }, }, }, User: { $ref: #/components/schemas/Person, }, }, }, }, }, ], }) // Add a new document to the store await store.addDocument( { openapi: 3.1.1, info: { title: Hello World, version: 1.0.0, }, components: { schemas: { Person: { type: object, properties: { name: { type: string }, }, }, User: { $ref: #/components/schemas/Person, }, }, }, }, { name: document-2, x-scalar-selected-server: server1, }, ) // Generate the workspace file system // This will write in the filesystem the workspace and all the chucks // which can be resolved by the consumer const workspace await store.generateWorkspaceChunks()generateWorkspaceChunks()仅在mode: static下可用否则直接抛出Mode has to be set to static to generate filesystem workspace chunks见 server.ts。它在directory默认assets下生成如下文件结构assets/ ├── scalar-workspace.json # 整个稀疏 workspaceWORKSPACE_FILE_NAME └── chunks/ └── document-name/ ├── components/ │ ├── schemas/ │ │ ├── Person.json │ │ └── User.json │ └── parameters/... └── operations/ └── ~1planets/ └── get.json这里有几个值得注意的源码级细节主文件名由常量WORKSPACE_FILE_NAME scalar-workspace.json定义server.ts。路径转义OpenAPI 的 path 键如/users/{id}与 component 键都会经escapeJsonPointer转义后写入磁盘/→~1。这不只是为了可寻址也是安全措施CHANGELOG 0.60.0 明确指出转义能防止文档里形如../../evil的键把分块文件写到 assets 目录之外CHANGELOG.md。分块维度components 按type/name拆成独立 JSON 文件operations 按path/method拆文件。filterHttpMethodsOnly只保留get/put/post/delete/options/head/patch/trace标准方法并跳过x-开头的扩展键server.tsescapePaths再对 path 键做 JSON Pointer 转义server.ts。引用外部化externalizeComponentReferences与externalizePathReferences把原文档中的 components 和 operations 替换为带$global: true的$ref。SSR 模式指向${baseUrl}/${name}/...static 模式指向./chunks/${name}/...server.ts。2.3 从外部源加载文档服务端存储内置了fetchUrlsNode 环境 fetch与readFiles两个加载插件见 server.ts因此可以直接从 URL 或文件系统初始化// Initialize the store with documents from external sources const store await createServerWorkspaceStore({ mode: static, documents: [ { name: remoteFile, url: http://localhost/document.json, }, { name: fsFile, path: ./document.json, }, ], }) // Output: { openapi: x.x.x, ... } console.log(store.getWorkspace().documents.remoteFile) // Output: { openapi: x.x.x, ... } console.log(store.getWorkspace().documents.fsFile)加载失败或处理失败的文档会被跳过而不是让整个工作区崩溃——初始文档是并发批量摄入的Promise.all一份畸形描述不应拖垮整次文档构建server.ts。此外文档名还会经过preventPollution校验像__proto__这样的危险名称会被直接拒绝防止原型污染。2.4 AsyncAPI 文档的特殊处理从源码看服务端存储对 AsyncAPI 文档走的是独立摄入路径AsyncAPI 的内容位于channels与operations而非paths因此不做分块外部化而是整体保留它会用scalar/asyncapi-upgrader把 1.x/2.x 升级到 3.x 形态并记录原始版本号到x-original-aas-versionserver.ts。这意味着该包同时是 OpenAPI 与 AsyncAPI 文档的统一工作区。三、客户端工作区存储响应式的 OpenAPI 文档工作区客户端存储createWorkspaceStore是一个Vue 响应式工作区入口实现在 client.ts。它与服务端存储天然配套客户端消费服务端生成的稀疏文档与分块按需resolve并对用户的每一次编辑做出响应。与构造时一次性灌入文档的服务端不同客户端 store以空状态启动通过addDocument逐个加载文档。3.1 基础用法// Initialize a new (empty) workspace store const store createWorkspaceStore({ meta: { x-scalar-active-document: default, }, }) // Add the default document await store.addDocument({ name: default, document: { openapi: 3.1.0, info: { title: OpenApi document, version: 1.0.0, }, }, }) // Add another OpenAPI document to the workspace await store.addDocument({ name: document, document: { openapi: 3.1.0, info: { title: Another document, version: 1.0.0, }, }, }) // Get the currently active document store.workspace.activeDocument // Retrieve a specific document by name store.workspace.documents[document] // Update global workspace settings store.update(x-scalar-color-mode, true) // Update settings for the active document store.updateDocument(active, x-scalar-selected-server, production) // Resolve and load document chunks including any $ref references await store.resolve([paths, /users, get])各 API 的行为要点均有源码注释佐证见 client.tsstore.workspaceVuereactive工作区对象额外带一个activeDocumentgetter。活跃文档由x-scalar-active-document元数据决定未指定时回退到工作区中的第一份文档。update(key, value)更新工作区级元数据例如x-scalar-color-mode、x-scalar-active-document。updateDocument(name, key, value)更新指定文档的元数据name传active即可作用于当前活跃文档。返回布尔值表示是否成功。resolve(path)按路径数组如[paths, /users, get]在活跃文档中解析引用遇到$ref会加载对应分块并在解析期间设置 loading 状态。3.2 变更追踪与响应式底层工作区对象的构建顺序很有讲究先用createDetectChangesProxy包裹原始数据再交给 Vue 的reactive——注释明确警告外层必须是 Vue 的响应式代理顺序颠倒会导致失去响应式client.ts。变更检测代理在每次写入后触发onAfterChange钩子文档内容被修改时自动置x-scalar-is-dirty true并把变更事件广播给注册的插件fireWorkspaceChange。x-scalar-is-dirty与x-scalar-registry-meta被列为metadata-only 键对它们的写入属于程序化簿记如提交哈希、冲突缓存不会误标 dirtyclient.ts。客户端 store 还支持传入verbose: true开启内部计时日志默认关闭以及plugins、fileLoader非浏览器环境加载本地文件用、fetch覆盖等构造参数。3.3 从外部源加载文档const store createWorkspaceStore() // Load a document into the store from a remote url await store.addDocument({ name: default, url: http://localhost/document.json, }) // Output: { openapi: x.x.x, ... } console.log(store.workspace.documents.default)客户端addDocument同样支持url、path需配置fileLoader与document三种输入返回布尔值表示是否添加成功client.ts。远程加载走scalar/json-magic/bundle的fetchUrls插件且受EXTERNAL_FETCH_CONCURRENCY_LIMIT 10并发上限约束——防止大型文档引用成千上万个外部示例时一次性打开无界连接client.ts。四、文档持久化与导出original 与 active 双快照客户端工作区在运行期对每份文档维护两份快照original原始基线用户最近一次通过saveDocument提交的已保存状态也是文档刚载入工作区时的状态。active活跃文档响应式的内存状态可能包含未保存的编辑。Deprecated已弃用额外的intermediateDocuments映射及其辅助方法getIntermediateDocument/promoteIntermediateToOriginal仅为向后兼容而保留不再是权威数据。新代码应依赖getOriginalDocument与活跃文档中间映射在保存/回滚/rebase 时同步维护直到该层被彻底移除。大部分持久化方法都以这两份快照为锚点。4.1 导出文档ExportexportDocument按 JSON 或 YAML 导出指定文档。导出读取的是已保存基线与revertDocumentChanges恢复的内容一致因此永远反映用户最后一次保存而不是未保存的编辑// Export the specified document as JSON const jsonString store.exportDocument(documentName, json) // Export the specified document as YAML const yamlString store.exportDocument(documentName, yaml) // Or export the currently active document directly const activeJson store.exportActiveDocument(json)导出路径会先经过purgeInternalDocumentKeys清理x-ext、x-ext-urls打包器临时元数据、x-scalar-navigation、x-scalar-is-dirty、x-original-oas-version、x-scalar-original-document-hash、x-scalar-original-source-url、x-scalar-registry-meta等内部键都会被剔除确保导出的文档干净、可分发client.ts。4.2 保存文档变更SavesaveDocument把当前内存文档提升为新的已保存基线将响应式文档序列化回普通对象剥离打包器内部键写入 original 文档映射并清除x-scalar-is-dirty标记// Save the specified document state const ok await store.saveDocument(documentName) if (!ok) { console.warn(Document does not exist or could not be serialised) }saveDocument成功返回true文档不存在或无法序列化回 original 映射时返回false。4.3 回滚文档变更Revert// Revert the specified document to its last saved state await store.revertDocumentChanges(documentName)revertDocumentChanges从 original 文档映射恢复活跃文档——即saveDocument最后一次写入的内容若从未保存过则是文档首次载入工作区时的状态。它通过原地更新现有响应式对象来保留 Vue 响应性。警告该操作会丢弃指定文档的全部未保存更改。4.4 完整示例const store createWorkspaceStore() await store.addDocument({ name: api, document: { openapi: 3.0.0, info: { title: My API, version: 1.0.0 }, paths: {}, }, }) // Make some changes to the document store.workspace.documents[api].info.title Updated API Title // Restore the saved baseline since the changes were never saved await store.revertDocumentChanges(api)五、工作区状态持久化导出与恢复整个工作区exportWorkspace/loadWorkspace用于把完整工作区状态全部文档、配置、元数据、original 与中间映射以及移除 Vue 响应式后的文档对象序列化后保存或从序列化结果恢复。这是跨会话保存工作、分享工作区配置的基础const client createWorkspaceStore() // Get the current workspace state const currentWorkspaceState client.exportWorkspace() // Persist on some kind of storage // Reload the workspace state client.loadWorkspace(currentWorkspaceState)exportWorkspace返回的InMemoryWorkspace对象可直接JSON.stringify存储对应源码中的InMemoryWorkspace类型见 inmemory-workspace.tsloadWorkspace则整体替换当前工作区的文档、元数据与配置。六、整体替换文档replaceDocument当拿到一份全新或已更新的 OpenAPI 文档、需要覆盖既有文档时replaceDocument会在原位置原子地更新整份文档它先计算新旧内容的差异再只应用必要变更兼顾正确性与性能const client createWorkspaceStore() await client.addDocument({ name: document-name, document: { openapi: 3.1.0, info: { title: Document Title, version: 1.0.0, }, paths: {}, components: { schemas: {}, }, servers: [], }, }) // Update the document with the new changes await client.replaceDocument(document-name, { openapi: 3.1.0, info: { title: Updated Document, version: 1.0.0, }, paths: {}, components: { schemas: {}, }, servers: [], })其 diff/apply 能力来自scalar/json-magic/diffdiff、apply函数与 rebase 的三方合并共用同一套差异引擎client.ts。七、从工作区规范创建importWorkspaceFromSpecification可以用一份工作区规范对象一次性初始化工作区规范里的documents通过$ref指向各文档来源overrides可为每个文档注入定制配置info与x-scalar-*键则作为工作区元数据await store.importWorkspaceFromSpecification({ workspace: draft, info: { title: My Workspace }, documents: { api: { $ref: /examples/api.yaml }, petstore: { $ref: /examples/petstore.yaml }, }, overrides: { api: { servers: [ { url: http://localhost:9090, }, ], }, }, x-scalar-color-mode: true, })该方法为规范中的每个文档调用addDocument使用各自的$ref与可选overrides返回一个布尔数组表示各文档是否添加成功client.ts。八、字段覆盖overrides覆盖overrides用于在不改动原始来源的前提下定制文档中的特定字段。所有覆盖都只存在于内存中永远不会写回原始文档原始来源保持不变修改被隔离在当前会话内const store createWorkspaceStore() await store.addDocument({ name: default, document: { openapi: 3.1.0, info: { title: Document Title, version: 1.0.0, }, paths: {}, components: { schemas: {}, }, servers: [], }, // Override the servers field overrides: { servers: [ { url: http://localhost:8080, description: Default dev server, }, ], }, })覆盖通过scalar/json-magic的 magic proxy 与createOverridesProxy辅助函数在运行时层叠生效overrides-proxy.ts这也是WorkspaceDocumentMetaInput.overrides被类型化为PartialDeepOpenApiDocument的原因client.ts。九、与上游同步rebaseDocument 三方合并rebaseDocument将工作区文档与新的上游来源origin对齐执行三方合并合入两路差异incoming changes上游变更diff(originalDocument, newOrigin)local changes本地变更diff(originalDocument, activeDocument)调用返回一个可判别discriminated的结果ok: false时type字段说明未执行原因CORRUPTED_STATE、FETCH_FAILED或NO_CHANGES_DETECTED。ok: true时返回可自动合并的changes、需要用户介入的conflicts以及把合并结果写回工作区的applyChanges回调。// Fetch the latest origin and start a rebase const result await store.rebaseDocument({ name: api, // Any WorkspaceDocumentInput is accepted - inline document, url, or path url: https://example.com/api/openapi.json, }) if (!result.ok) { console.warn(Rebase did not run: ${result.type}) return } if (result.conflicts.length 0) { // No conflicts - just apply with an empty resolution set await result.applyChanges({ resolvedConflicts: [] }) return } // Surface the conflicts to the user. Each conflict is a tuple of // [incomingDiffs, localDiffs] - resolve by picking either side, or by // providing a fully resolved document. const resolvedConflicts result.conflicts.flatMap(([incoming]) incoming) await result.applyChanges({ resolvedConflicts }) // Or, pass a complete document to use as-is (overrides the merge result): await result.applyChanges({ resolvedDocument: newDocument })关键语义applyChanges返回后合并结果会同时成为新的活跃文档与新的已保存基线——因此紧接着执行revertDocumentChanges会回滚到 rebase 后的状态而不是 rebase 前的 original。这一行为来自合并引擎scalar/json-magic/diff的merge函数测试覆盖见 client.test.ts。十、源码结构继续深入的地图如果希望进一步理解实现以下文件是很好的起点服务端核心server.ts——createServerWorkspaceStore、分块生成、引用外部化、get/getWorkspace客户端核心client.ts——createWorkspaceStore、响应式工作区、双快照持久化、rebase、导出导入服务端测试server.test.ts——SSR 与 static 模式的行为断言例如验证生成的$ref指向https://example.com/${name}/operations/~1planets/get#server.test.ts客户端测试client.test.ts——覆盖插件事件、持久化、rebase 等场景引用解析工具resolve.ts——resolve.schema用于合并兄弟引用后解析 schema打包器与插件plugins/bundler、plugins/client变更记录CHANGELOG.md——包含分块转义安全、AsyncAPI 导航等演进细节。小结scalar/workspace-store用服务端分块 客户端响应式的组合为大型 OpenAPI/AsyncAPI 文档提供了一套完整的生命周期管理方案服务端在构建期把重内容拆成按需加载的分块并暴露统一工作区载荷客户端则以双快照模型支撑保存、回滚、导出、整体替换、字段覆盖与上游 rebase。无论你是在构建自己的 API 文档站点、离线优先的 API 客户端还是需要一套可持久化的多文档工作区这个包的设计都值得直接借鉴——其全部实现、测试与类型定义都可在本仓库的 packages/workspace-store 目录中查阅。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考