尧图网页设计 
Swagger UI Models 列表虚拟化实战基于 TanStack Virtual 的 200 Schema 性能优化方案【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-ui导读当 OpenAPI 规范包含 200 个以上的 schema 定义时Swagger UI 的 Models/Schemas 区域会一次性挂载全部模型行产生可观的初始渲染开销与内存占用。本文基于 Swagger UI 仓库中perf-virtualization实施票phase-1-models-virtualization.md的完整方案讲解如何用 TanStack Virtual 将全量渲染改为窗口化windowed渲染包括真实性能基线校准、estimateSize/getItemKey/measureElement的核心用法、100-schema 自动阈值回退策略、DOM 契约与 CSS 审计清单、单元测试基础设施的两个硬性阻塞点以及 find-in-page 等可接受的用户可见行为变化。读完你将能独立评估并落地“组件列表虚拟化”这一典型的 React 性能优化路径。一、问题背景全量挂载的代价到底有多大1.1 现状每个 schema 一行全部同时挂载当前 Models 区域的渲染逻辑位于 models.jsx它在Collapse组件内部用definitions.entrySeq().map(...)无条件遍历所有 schema 定义第 77 行。一个包含约 800 个 schema 的 Kubernetes 风格 API 文档会一次性挂载 800 个模型行。需要先厘清一个常见误区这里挂载的不是 800 棵完整 schema 树而是 800 个轻量行。关键证据在 model-collapse.jsx{ this.state.expanded this.props.children }即ModelCollapse只在自身expanded状态下才渲染children也就是ModelWrapper的 schema 子树。一个折叠状态的模型实际挂载的开销仅为一个.model-containerdiv注意这是 CSS 类名项目中并不存在名为ModelContainer的组件一个JumpToPathconnected 组件一个ModelCollapse折叠按钮map 循环体models.jsx里的三次 selector 调用specSelectors.specResolvedSubtree(fullPath)、specSelectors.specJson().getIn(fullPath)、layoutSelectors.isShown(fullPath, false)。1.2 校准后的收益预期800 轻量行 → 约 15 行因此该方案的真实收益是800 个轻量行 → 视口内约 15 行而不是“800 棵完整 schema 树 → 15 棵”。即便如此优化依然值得800 个 connected 组件、800 个 DOM 子树、每次渲染 2400 次 selector 调用都是真实且可度量的开销。实施时务必先记录真实基线不要假设量级级order-of-magnitude的提升。1.3 为什么从 Models 列表开始选它作为虚拟化第一站Phase 1的原因是复杂度最低扁平列表、单一滚动轴、且整体被一个已有的可折叠包裹器Collapse包围是最理想的虚拟化目标。后续 Operations 列表虚拟化Phase 3与 OAS 3.1 模型渲染Phase 2都以此为铺垫。二、方案总览与影响范围维度内容包swagger-uicore主要改动文件models.jsxclass → 函数式组件样式src/style/_models.scss滚动容器max-height/overflow-y单元测试test/unit/core/plugins/json-schema-5/components/models.jsx现有 Enzymeshallow在 hook 化后失效需更新测试基础设施test/unit/jest-shim.js需补ResizeObserverpolyfillE2E 夹具test/e2e-cypress/static/documents/perf/新增 240-schema 大夹具E2E 用例test/e2e-cypress/e2e/features/新增 specSelenium 页面test/e2e-selenium/pages/main.js第 506–539 行含全部 12 处.model-container引用新依赖tanstack/react-virtual约 5KB mingzip2.1 新增测试夹具由于 models.jsx 会根据isOAS3()分支选择基础路径getSchemaBasePath()返回[components, schemas]或[definitions]且model-collapse.cy.js的每个场景都要在 Swagger 2 与 OpenAPI 3 下各跑一遍因此夹具按两个变体提供夹具Schemas 数说明test/e2e-cypress/static/documents/perf/many-schemas.swagger.yaml240 个definitionsSwagger 2.0test/e2e-cypress/static/documents/perf/many-schemas.openapi.yaml240 个components/schemasopenapi: 3.0.0选 240 是有意为之——它明显高于 100 阈值确保走的是虚拟化路径。两个文件均为生成文件带“重新生成勿手改”头部各自带一个平凡/ping操作以保证文档合法可解析。仓库中还存在第三个夹具many-schemas.openapi31.yamlopenapi: 3.1.0同样 240 个 schema但它是为 Phase 1bOAS 3.1 模型准备的不属于本票范围——在 3.1 文档上渲染的是oas31组件副本见 oas31/components/models而不是本组件。三、核心实现把全量 map 换成窗口化列表3.1 类组件转函数式组件models.jsx 目前是export default class Models extends Component。useVirtualizer是 hook因此第一步是把组件转换为函数式。转换中有 7 个易丢行为必须原样保留getCollapsedContent第 22–24 行给每个ModelCollapse提供collapsedContent第 122 行。注意其中的怪癖——它用name调用却声明为无参函数且永远返回单个空格 覆盖了ModelCollapse自己的{...}默认值model-collapse.jsx。按原样移植不要“简化”成默认值否则会改变每个模型的折叠渲染。getSchemaBasePath()第 17–20 行返回isOAS3() ? [components, schemas] : [definitions]。它同时供specPathBase、handleToggle和两个 ref 回调使用必须作为单一事实来源保留对specSelectors.isOAS3()做 memoize不能在各处内联复制。渲染期 inline dispatch第 94 行specActions.requestResolvedSubtree(fullPath)在渲染过程中被触发需保留该行为最好在转换时移入 effect。第 51 行早退!definitions.size || defaultModelsExpandDepth 0时整个 section 返回null。第 131 行初始展开门控每个模型的初始展开状态由defaultModelsExpandDepth 0 isShown决定。第 54 行默认展开状态layoutSelectors.isShown(specPathBase, defaultModelsExpandDepth 0 docExpansion ! none)。docExpansion在第 50 行解构后文件内再无其他使用转换时极易被当作未使用变量删掉——而这会静默改变docExpansion: none时的默认展开行为。handleToggle第 26–32 行展开时同时 dispatchlayoutActions.show和specActions.requestResolvedSubtree。这是惰性 schema 解析路径与第 94 行的 inline dispatch 相互独立两者都需要保留。3.2 窗口化渲染骨架import { useVirtualizer } from tanstack/react-virtual // 组件内部先完成 class → 函数式转换 const parentRef useRef(null) const definitionEntries useMemo( () definitions.entrySeq().toArray(), [definitions] ) const virtualizer useVirtualizer({ count: definitionEntries.length, getScrollElement: () parentRef.current, estimateSize: () 72, // 占位值——先测量真实的折叠 .model-container 高度 overscan: 5, // 必填——见“稳定 item key”。缺省时 vItem.key 退化为索引。 getItemKey: (index) models-section-${definitionEntries[index][0]}, })渲染循环div ref{parentRef} classNamemodels-scroll div style{{ height: virtualizer.getTotalSize(), position: relative }} {virtualizer.getVirtualItems().map((vItem) { const [name] definitionEntries[vItem.index] return ( div key{vItem.key} >.models-scroll { max-height: min(60vh, 800px); overflow-y: auto; }只在虚拟化分支应用legacy 分支保持今天无界布局不变。4.2 CSS 审计必做虚拟化会在.models与.model-container之间插入两层新 div.models-scroll包裹层 每个 item 的绝对定位 div。任何假设旧层级的后代选择器——子组合器、位置型/:first-child风格选择器——都会静默失效。编辑前先跑grep -rn model-container src/style/ src/core/plugins/*/components/**/*.scss grep -rn \.models\b src/style/已知的生产代码.model-container引用约 10 行、8 个文件_models.scss3 处、_layout.scsssrc/style/_layout.scss、_dark-mode.scsssrc/style/_dark-mode.scss、_variables.scsssrc/style/_variables.scss、两个 json-schema-2020-12 样式表加上models.jsx:117与model-example.jsx:123。model-example.jsx:123最要命它渲染了第二个.model-container——请求/响应示例视图不在虚拟化列表内。所以.model-container的样式绝不能重新限定到新的虚拟包裹层上否则会静默改坏或破坏示例面板。任何新选择器都必须是叠加式的并且只限定在.models-scroll内。相应增加验收项对 Models 区域以及某个操作的请求/响应示例面板做视觉 diff。4.3getScrollParent行为变化scrollToElementsrc/core/plugins/deep-linking/layout.js通过system.fn.getScrollParent(ref)定义于layout.js:138解析滚动容器。今天模型的最近滚动父级是window。引入有界.models-scroll后它成了滚动父级zenscroll 会滚动内层容器而不是页面——section 本身可能留在屏幕外。另外ModelCollapse.onLoad传的是ref.parentElementmodel-collapse.jsx改动后它是绝对定位的虚拟 item 包裹层而非.model-container。两者都要显式处理考虑给scrollToElement传显式container参数而不是依赖推断。五、可折叠包裹器与测量缓存阻塞点Models 列表位于Collapse isOpened{showModels}内models.jsx而Collapse关闭时返回noscript/src/core/components/layout-utils.jsx 的renderNotAnimated()241–249 行——这是真实的卸载。因此折叠 Schemas/Models 区域会销毁.models-scrollparentRef.current null且虚拟化器的测量缓存在每次折叠/展开循环中被丢弃。需要处理getScrollElement: () parentRef.current在折叠期间返回null——验证虚拟化器能容忍而不是抛错重新展开时从estimateSize重新测量之前展开过的模型高度被遗忘、滚动位置丢失可选方案保持虚拟化器挂载、仅对该包裹层把折叠改为 CSS 实现或通过initialMeasurementsCache跨卸载持久化virtualizer.measurementsCache。必须二选一并有意识地决定——这直接与验收项“折叠/展开 Schemas/Models 区域行为不变”冲突。六、Deep-link 引用机制虚惊一场但代码确实死了早期草案把“deep-link 到屏外模型”当作最高风险——这是错的。master上并不存在模型 deep-linking 功能无需保留任何桥接。models.jsx 确实注册了每模型 ref第 36、43 行来自第 34/40 行的onLoadModels/onLoadModel声明ModelCollapse.onLoad还注册了第三个model-collapse.jsx并在匹配时自动展开第 71 行。它们全部汇入readyToScrolldeep-linking/layout.js该函数只在Im.is(scrollToKey, fromJS(isShownKey))时触发。但scrollToKey永远不可能持有 schema 路径src/中layoutActions.scrollTo的唯一调用者是parseDeepLinkHashlayout.js它传的是isShownKeyFromUrlHashArray(hashArray)该 selectorlayout.js:175-184只返回[operations, tag, operationId]、[operations-tag, tag]或[]其第 177 行注释直言“We only put operations in the URL”。urlHashArrayFromIsShownKey第 185-194 行对称。所以[definitions, Pet]永不匹配#/definitions/SomeModel不是受认可的 hash 形式docs/usage/deep-linking.md 也未记载任何模型/schema 语法。佐证test/e2e-cypress/e2e/features/model-collapse.cy.js 确实定义了const urlFragment #/definitions/Pet并作为第二个参数传入——但接收函数签名是function ModelCollapseTest(baseUrl)第 13 行单参数fragment 被静默丢弃没有任何测试访问过它。仓库里唯一的引用也是死的。结论models.jsx:43与ModelCollapse.onLoad的自动展开今天就是死代码。没有东西可破坏、也没有桥要建。需要做的少量工作class → 函数式转换中原样保留readyToScrollref——它们不可达但无害删除超出性能票范围在 item 包裹层上与virtualizer.measureElement组合compose而不是二选一——测量 ref 是必需的现有 ref 必须保持原形状不要构建scrollToIndex桥。若将来实现模型 deep-linking那是一个独立功能票且应从设计之初就考虑虚拟化。真正到达模型的导航是普通浏览器锚点id{model-${name}}models.jsx——虚拟化确实会让屏外模型失效这归入“可接受行为变化”而非本节。七、单元测试基础设施两个硬阻塞点两点都同样影响 Phase 3且当前仓库都没有。阻塞 1jsdom 没有ResizeObserver。virtualizer.measureElement依赖它。test/unit/jest-shim.js 目前只 polyfill 了TextDecoder/TextEncodertest/unit/setup.js 配置 jsdom 与 Enzyme adapter且grep -rn ResizeObserver src/ test/零结果。Jest 下测量 ref 会抛错或静默失效。需在本票范围内给jest-shim.js加 polyfill或一个记录被观察元素的 stub 类。阻塞 2Enzymeshallow扛不住 class → 函数式转换。现有测试test/unit/core/plugins/json-schema-5/components/models.jsx对类组件做import { shallow } from enzyme。仓库是enzyme3.11.0cfaester/enzyme-adapter-react-18package.json、package.json在setup.js中配置。Hooks——useRef、useMemo、useVirtualizer——在该 adapter 的 shallow renderer 下不会有意义地执行getScrollElement: () parentRef.current会看到null一个 item 都渲染不出来。二选一并写进 PR用mount替代shallow需要 ResizeObserver polyfill 和一个非零高度的真实滚动元素——jsdom 默认高度全是 0虚拟化器可能一个窗口都开不出来或在单元测试里 mocktanstack/react-virtual让useVirtualizer返回确定性假对象固定的getVirtualItems()、no-op 的measureElement把真正的窗口行为交给 Cypress 覆盖。推荐第二种它让单元测试专注于本组件的逻辑配置门控、requestResolvedSubtreedispatch、key/DOM 契约而把真实滚动行为留给拥有真实布局引擎的 E2E。八、上线策略自动数量阈值已定无配置开关已决策2026-08-04只有 schema 数超过阈值才虚拟化。不新增配置键。import { VIRTUALIZE_MODELS_THRESHOLD } from core/utils // 建议值 100 if (definitionEntries.length VIRTUALIZE_MODELS_THRESHOLD) { // legacy 路径——今天的标记逐字节不变 return renderLegacyModels() } // 下面是窗口化路径这是全票最具决定性的指令因为它把大部分风险逆转了保留现有渲染路径不动。转换时不要删除或“清理”今天的标记——把它抽成仍产出相同 DOM 的函数/分支。前面所有 DOM 契约项与 CSS 审计只作用于虚拟化分支legacy 分支天然保留它们。每个现有测试原样通过。features/models.swagger.yaml只有3个 definitionsfeatures/models.openapi.yaml同理所以model-collapse.cy.js和 Selenium 的:nth-child选择器main.js:506-539全走 legacy 路径、不受影响整个从本票风险面移除。虚拟化路径现有覆盖为零。新的性能夹具是它唯一的 E2E 训练场所以必须超过 100 个 definitions下面要求 ≥200保持这个余量。低于阈值的夹具会静默测试 legacy 路径等于把虚拟化未经验证地上线。测试边界两侧——一个夹具刚好低于阈值一个刚好高于。class → 函数式转换仍作用于整个组件两个分支都住在转换后的函数组件里。注意 hooksuseVirtualizer、useRef必须无条件调用、先于阈值分支——不能把早退 return 放在它们上面。九、验收标准清单低于 100-schema 阈值的 spec 渲染出与今天逐字节一致的标记legacy 路径——model-collapse.cy.js不改一行通过高于阈值的 spec 走窗口化路径仅视口内可见模型被挂载React DevTools 验证边界两侧都测——一个夹具刚好低于、一个刚好高于阈值滚动 Models 列表能正确渲染/卸载条目折叠/展开 Schemas/Models 区域的行为与之前一致现有model-collapse.cy.js场景不改一行通过——其夹具各只有 3 个 definitions走 legacy 路径。若其任何选择器.models h4 .models-control、#model-User .model-box .model-box-control于第 40/44 行#model-Pet/#model-Order于第 18/28/34 行需要改动说明 legacy 路径被动过——视为回归而不是改测试defaultModelsExpandDepth 0仍把整个 section 短路为nullmodels.jsxdefaultModelsExpandDepth 0 isShown仍驱动初始逐模型展开第 131 行无视觉回归——布局、间距、单个模型的展开/折叠不变无无障碍回归——键盘导航与屏幕阅读器顺序保留性能200 模型夹具的初始渲染时间相对已记录基线下降React Profiler前后对比test/unit/core/plugins/json-schema-5/components/models.jsx 单元测试更新ResizeObserverpolyfill 加入 test/unit/jest-shim.js 且npm run test:unit通过阻塞性前置条件通过npm run deps-size记录前后包体积影响tanstack/react-virtual约增加 5KB mingzip实测增量显著更大时在 PR 中标注swagger-ui-react仍能正确渲染模型——该 flavor 重导出 core 因此零代码改动继承本变更但它是独立发布的包且不在 Cypress 套件覆盖内E2E新夹具下 Models 区域滚动与渲染正确#model-Name浏览器锚点导航在阈值以下仍可用阈值以上失效按“可接受行为变化”接受。注意这是普通浏览器锚点——模型 deep-linking 不存在展开模型 A、滚出视口再滚回A 仍保持展开且没有别的模型被错误展开守护下文getItemKey要求十、成功度量与可接受行为变化10.1 度量方法在http://localhost:3200/上用新的many-schemas.yaml夹具或 Kubernetes spec跑 React Profiler之前N 个模型的渲染时间——记录真实数字目前尚无基线之后虚拟化后的渲染时间无论 N 多大都应接近恒定10.2 可接受的行为变化构建前需与维护者确认虚拟化把屏外内容移出 DOM。以下全部只作用于超过 100-schema 阈值的 spec——低于它时走 legacy 路径行为与今天逐字节一致与 Phase 3 共享浏览器页内查找Ctrl/Cmd-F不再能找到屏外模型。这是虚拟化的经典权衡对文档工具是真实的、用户可见的能力损失——用户惯于对 schema 名按 Ctrl-F。打印 / “另存为 PDF”只捕获已渲染窗口而非完整 schema 列表。浏览器锚点导航#model-Name对未挂载模型失效id{model-${name}}models.jsx。由于模型 deep-linking 不存在这个普通锚点是今天链接 schema 的唯一方式——所以这才是 Phase 1 真正的导航回归而不是次要问题。数量阈值本身就是缓解手段它覆盖了绝大多数 spec。对超阈值场景除了不虚拟化没有更多缓解没有应用内模型过滤器可兜底见下节 Out of Scope调高overscan也只是把窗口加宽几行。接受它或者提高阈值。十一、风险登记与范围外事项11.1 风险与缓解风险缓解deep-link 到屏外模型失效——不是风险master 上不存在模型 deep-linking见第六章无需处理。原样保留死的readyToScrollref浏览器锚点#model-Name对屏外模型失效——这才是真正的导航路径阈值/开关交由维护者决策见可接受行为变化class → 函数式转换丢失配置门控第 51 行defaultModelsExpandDepth 0早退、第 131 行 0 isShown展开门控两个边界显式做单元测试渲染体重构时它们最容易丢Collapse卸载.models-scroll在每次 section 切换时销毁滚动元素与测量缓存提前定下持久化策略见第五章约束显式测试展开 section → 滚动 → 折叠 → 再展开getScrollParent现在解析到.models-scroll而非window滚动行为改变给scrollToElement传显式containerE2E 验证 section 也能滚进视口E2E 选择器因 DOM 重构失效——被数量阈值中和。所有现有夹具 ≤3 个 definitions每条现有 Cypress/Selenium 选择器都走 legacy 路径无需处理。转换时不要“清理”legacy 标记——那才会重新引入此问题虚拟化路径未经验证上线因为每个现有夹具都在阈值以下新性能夹具是它唯一覆盖必须超过 100 个 definitions加一组刚好低于/刚好高于的边界对两条渲染路径随时间分叉——修复只落在其中一支legacy 分支保持为今天 JSX 的薄抽取而非平行重实现两条分支都做单元测试页内查找 / 打印回归见上阈值或开关交由维护者决策measureElement校正展开模型时的 CSS 布局位移item 包裹层加min-height: 72px11.2 范围外Operations 列表虚拟化 → Phase 3Schema 属性列表——本 epic 范围外详见 README 的 “Out of scope” 中为何拒绝在那里虚拟化OAS 3.1 模型渲染src/core/plugins/oas31/components/models/models.jsx——按 CLAUDE.md 跨插件规则它是本组件的自包含第二副本→Phase 2.claude/implementation/perf-virtualization/phase-2-oas31-models.md同版本发布。注意在 OAS 3.1 文档上渲染的是那个副本而非本组件基准测试前先用 React DevTools 确认哪个组件存活并只用many-schemas.openapi.yaml3.0.0——不要用 3.1 夹具——来度量本票模型搜索/过滤——目前不存在。src/core/plugins/filter/只提供opsFilter且只过滤操作tagmodels.jsx 不含任何过滤逻辑十二、依赖与实施顺序小结本票不依赖其他阶段——Phase 1 是第一个实施并把tanstack/react-virtual加入 package.json。不被阻塞两个此前悬而未决的决策均已落定——上线方式是自动数量阈值无配置键滚动容器是max-height: min(60vh, 800px)见 Rollout 节。推荐的落地顺序给 test/unit/jest-shim.js 加ResizeObserverpolyfill阻塞性前置基准在 240-schema 夹具下用 React Profiler 记录当前渲染时间用npm run deps-size记录当前包体积完成 class → 函数式转换保留第七章的 7 个行为与 DOM 契约引入VIRTUALIZE_MODELS_THRESHOLD阈值分支实现窗口化渲染useVirtualizergetItemKeymeasureElementref补.models-scroll样式与 CSS 审计更新单元测试mocktanstack/react-virtual的推荐策略跑npm run test:unit用新夹具跑 Cypress验证滚动、展开状态保持、锚点行为复核swagger-ui-react渲染前后对比渲染时间与包体积写 PR 时标注实测增量并把“可接受行为变化”摆到维护者面前确认。【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Swagger UI Models 列表虚拟化实战：基于 TanStack Virtual 的 200+ Schema 性能优化方案
Swagger UI Models 列表虚拟化实战基于 TanStack Virtual 的 200 Schema 性能优化方案【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-ui导读当 OpenAPI 规范包含 200 个以上的 schema 定义时Swagger UI 的 Models/Schemas 区域会一次性挂载全部模型行产生可观的初始渲染开销与内存占用。本文基于 Swagger UI 仓库中perf-virtualization实施票phase-1-models-virtualization.md的完整方案讲解如何用 TanStack Virtual 将全量渲染改为窗口化windowed渲染包括真实性能基线校准、estimateSize/getItemKey/measureElement的核心用法、100-schema 自动阈值回退策略、DOM 契约与 CSS 审计清单、单元测试基础设施的两个硬性阻塞点以及 find-in-page 等可接受的用户可见行为变化。读完你将能独立评估并落地“组件列表虚拟化”这一典型的 React 性能优化路径。一、问题背景全量挂载的代价到底有多大1.1 现状每个 schema 一行全部同时挂载当前 Models 区域的渲染逻辑位于 models.jsx它在Collapse组件内部用definitions.entrySeq().map(...)无条件遍历所有 schema 定义第 77 行。一个包含约 800 个 schema 的 Kubernetes 风格 API 文档会一次性挂载 800 个模型行。需要先厘清一个常见误区这里挂载的不是 800 棵完整 schema 树而是 800 个轻量行。关键证据在 model-collapse.jsx{ this.state.expanded this.props.children }即ModelCollapse只在自身expanded状态下才渲染children也就是ModelWrapper的 schema 子树。一个折叠状态的模型实际挂载的开销仅为一个.model-containerdiv注意这是 CSS 类名项目中并不存在名为ModelContainer的组件一个JumpToPathconnected 组件一个ModelCollapse折叠按钮map 循环体models.jsx里的三次 selector 调用specSelectors.specResolvedSubtree(fullPath)、specSelectors.specJson().getIn(fullPath)、layoutSelectors.isShown(fullPath, false)。1.2 校准后的收益预期800 轻量行 → 约 15 行因此该方案的真实收益是800 个轻量行 → 视口内约 15 行而不是“800 棵完整 schema 树 → 15 棵”。即便如此优化依然值得800 个 connected 组件、800 个 DOM 子树、每次渲染 2400 次 selector 调用都是真实且可度量的开销。实施时务必先记录真实基线不要假设量级级order-of-magnitude的提升。1.3 为什么从 Models 列表开始选它作为虚拟化第一站Phase 1的原因是复杂度最低扁平列表、单一滚动轴、且整体被一个已有的可折叠包裹器Collapse包围是最理想的虚拟化目标。后续 Operations 列表虚拟化Phase 3与 OAS 3.1 模型渲染Phase 2都以此为铺垫。二、方案总览与影响范围维度内容包swagger-uicore主要改动文件models.jsxclass → 函数式组件样式src/style/_models.scss滚动容器max-height/overflow-y单元测试test/unit/core/plugins/json-schema-5/components/models.jsx现有 Enzymeshallow在 hook 化后失效需更新测试基础设施test/unit/jest-shim.js需补ResizeObserverpolyfillE2E 夹具test/e2e-cypress/static/documents/perf/新增 240-schema 大夹具E2E 用例test/e2e-cypress/e2e/features/新增 specSelenium 页面test/e2e-selenium/pages/main.js第 506–539 行含全部 12 处.model-container引用新依赖tanstack/react-virtual约 5KB mingzip2.1 新增测试夹具由于 models.jsx 会根据isOAS3()分支选择基础路径getSchemaBasePath()返回[components, schemas]或[definitions]且model-collapse.cy.js的每个场景都要在 Swagger 2 与 OpenAPI 3 下各跑一遍因此夹具按两个变体提供夹具Schemas 数说明test/e2e-cypress/static/documents/perf/many-schemas.swagger.yaml240 个definitionsSwagger 2.0test/e2e-cypress/static/documents/perf/many-schemas.openapi.yaml240 个components/schemasopenapi: 3.0.0选 240 是有意为之——它明显高于 100 阈值确保走的是虚拟化路径。两个文件均为生成文件带“重新生成勿手改”头部各自带一个平凡/ping操作以保证文档合法可解析。仓库中还存在第三个夹具many-schemas.openapi31.yamlopenapi: 3.1.0同样 240 个 schema但它是为 Phase 1bOAS 3.1 模型准备的不属于本票范围——在 3.1 文档上渲染的是oas31组件副本见 oas31/components/models而不是本组件。三、核心实现把全量 map 换成窗口化列表3.1 类组件转函数式组件models.jsx 目前是export default class Models extends Component。useVirtualizer是 hook因此第一步是把组件转换为函数式。转换中有 7 个易丢行为必须原样保留getCollapsedContent第 22–24 行给每个ModelCollapse提供collapsedContent第 122 行。注意其中的怪癖——它用name调用却声明为无参函数且永远返回单个空格 覆盖了ModelCollapse自己的{...}默认值model-collapse.jsx。按原样移植不要“简化”成默认值否则会改变每个模型的折叠渲染。getSchemaBasePath()第 17–20 行返回isOAS3() ? [components, schemas] : [definitions]。它同时供specPathBase、handleToggle和两个 ref 回调使用必须作为单一事实来源保留对specSelectors.isOAS3()做 memoize不能在各处内联复制。渲染期 inline dispatch第 94 行specActions.requestResolvedSubtree(fullPath)在渲染过程中被触发需保留该行为最好在转换时移入 effect。第 51 行早退!definitions.size || defaultModelsExpandDepth 0时整个 section 返回null。第 131 行初始展开门控每个模型的初始展开状态由defaultModelsExpandDepth 0 isShown决定。第 54 行默认展开状态layoutSelectors.isShown(specPathBase, defaultModelsExpandDepth 0 docExpansion ! none)。docExpansion在第 50 行解构后文件内再无其他使用转换时极易被当作未使用变量删掉——而这会静默改变docExpansion: none时的默认展开行为。handleToggle第 26–32 行展开时同时 dispatchlayoutActions.show和specActions.requestResolvedSubtree。这是惰性 schema 解析路径与第 94 行的 inline dispatch 相互独立两者都需要保留。3.2 窗口化渲染骨架import { useVirtualizer } from tanstack/react-virtual // 组件内部先完成 class → 函数式转换 const parentRef useRef(null) const definitionEntries useMemo( () definitions.entrySeq().toArray(), [definitions] ) const virtualizer useVirtualizer({ count: definitionEntries.length, getScrollElement: () parentRef.current, estimateSize: () 72, // 占位值——先测量真实的折叠 .model-container 高度 overscan: 5, // 必填——见“稳定 item key”。缺省时 vItem.key 退化为索引。 getItemKey: (index) models-section-${definitionEntries[index][0]}, })渲染循环div ref{parentRef} classNamemodels-scroll div style{{ height: virtualizer.getTotalSize(), position: relative }} {virtualizer.getVirtualItems().map((vItem) { const [name] definitionEntries[vItem.index] return ( div key{vItem.key} >.models-scroll { max-height: min(60vh, 800px); overflow-y: auto; }只在虚拟化分支应用legacy 分支保持今天无界布局不变。4.2 CSS 审计必做虚拟化会在.models与.model-container之间插入两层新 div.models-scroll包裹层 每个 item 的绝对定位 div。任何假设旧层级的后代选择器——子组合器、位置型/:first-child风格选择器——都会静默失效。编辑前先跑grep -rn model-container src/style/ src/core/plugins/*/components/**/*.scss grep -rn \.models\b src/style/已知的生产代码.model-container引用约 10 行、8 个文件_models.scss3 处、_layout.scsssrc/style/_layout.scss、_dark-mode.scsssrc/style/_dark-mode.scss、_variables.scsssrc/style/_variables.scss、两个 json-schema-2020-12 样式表加上models.jsx:117与model-example.jsx:123。model-example.jsx:123最要命它渲染了第二个.model-container——请求/响应示例视图不在虚拟化列表内。所以.model-container的样式绝不能重新限定到新的虚拟包裹层上否则会静默改坏或破坏示例面板。任何新选择器都必须是叠加式的并且只限定在.models-scroll内。相应增加验收项对 Models 区域以及某个操作的请求/响应示例面板做视觉 diff。4.3getScrollParent行为变化scrollToElementsrc/core/plugins/deep-linking/layout.js通过system.fn.getScrollParent(ref)定义于layout.js:138解析滚动容器。今天模型的最近滚动父级是window。引入有界.models-scroll后它成了滚动父级zenscroll 会滚动内层容器而不是页面——section 本身可能留在屏幕外。另外ModelCollapse.onLoad传的是ref.parentElementmodel-collapse.jsx改动后它是绝对定位的虚拟 item 包裹层而非.model-container。两者都要显式处理考虑给scrollToElement传显式container参数而不是依赖推断。五、可折叠包裹器与测量缓存阻塞点Models 列表位于Collapse isOpened{showModels}内models.jsx而Collapse关闭时返回noscript/src/core/components/layout-utils.jsx 的renderNotAnimated()241–249 行——这是真实的卸载。因此折叠 Schemas/Models 区域会销毁.models-scrollparentRef.current null且虚拟化器的测量缓存在每次折叠/展开循环中被丢弃。需要处理getScrollElement: () parentRef.current在折叠期间返回null——验证虚拟化器能容忍而不是抛错重新展开时从estimateSize重新测量之前展开过的模型高度被遗忘、滚动位置丢失可选方案保持虚拟化器挂载、仅对该包裹层把折叠改为 CSS 实现或通过initialMeasurementsCache跨卸载持久化virtualizer.measurementsCache。必须二选一并有意识地决定——这直接与验收项“折叠/展开 Schemas/Models 区域行为不变”冲突。六、Deep-link 引用机制虚惊一场但代码确实死了早期草案把“deep-link 到屏外模型”当作最高风险——这是错的。master上并不存在模型 deep-linking 功能无需保留任何桥接。models.jsx 确实注册了每模型 ref第 36、43 行来自第 34/40 行的onLoadModels/onLoadModel声明ModelCollapse.onLoad还注册了第三个model-collapse.jsx并在匹配时自动展开第 71 行。它们全部汇入readyToScrolldeep-linking/layout.js该函数只在Im.is(scrollToKey, fromJS(isShownKey))时触发。但scrollToKey永远不可能持有 schema 路径src/中layoutActions.scrollTo的唯一调用者是parseDeepLinkHashlayout.js它传的是isShownKeyFromUrlHashArray(hashArray)该 selectorlayout.js:175-184只返回[operations, tag, operationId]、[operations-tag, tag]或[]其第 177 行注释直言“We only put operations in the URL”。urlHashArrayFromIsShownKey第 185-194 行对称。所以[definitions, Pet]永不匹配#/definitions/SomeModel不是受认可的 hash 形式docs/usage/deep-linking.md 也未记载任何模型/schema 语法。佐证test/e2e-cypress/e2e/features/model-collapse.cy.js 确实定义了const urlFragment #/definitions/Pet并作为第二个参数传入——但接收函数签名是function ModelCollapseTest(baseUrl)第 13 行单参数fragment 被静默丢弃没有任何测试访问过它。仓库里唯一的引用也是死的。结论models.jsx:43与ModelCollapse.onLoad的自动展开今天就是死代码。没有东西可破坏、也没有桥要建。需要做的少量工作class → 函数式转换中原样保留readyToScrollref——它们不可达但无害删除超出性能票范围在 item 包裹层上与virtualizer.measureElement组合compose而不是二选一——测量 ref 是必需的现有 ref 必须保持原形状不要构建scrollToIndex桥。若将来实现模型 deep-linking那是一个独立功能票且应从设计之初就考虑虚拟化。真正到达模型的导航是普通浏览器锚点id{model-${name}}models.jsx——虚拟化确实会让屏外模型失效这归入“可接受行为变化”而非本节。七、单元测试基础设施两个硬阻塞点两点都同样影响 Phase 3且当前仓库都没有。阻塞 1jsdom 没有ResizeObserver。virtualizer.measureElement依赖它。test/unit/jest-shim.js 目前只 polyfill 了TextDecoder/TextEncodertest/unit/setup.js 配置 jsdom 与 Enzyme adapter且grep -rn ResizeObserver src/ test/零结果。Jest 下测量 ref 会抛错或静默失效。需在本票范围内给jest-shim.js加 polyfill或一个记录被观察元素的 stub 类。阻塞 2Enzymeshallow扛不住 class → 函数式转换。现有测试test/unit/core/plugins/json-schema-5/components/models.jsx对类组件做import { shallow } from enzyme。仓库是enzyme3.11.0cfaester/enzyme-adapter-react-18package.json、package.json在setup.js中配置。Hooks——useRef、useMemo、useVirtualizer——在该 adapter 的 shallow renderer 下不会有意义地执行getScrollElement: () parentRef.current会看到null一个 item 都渲染不出来。二选一并写进 PR用mount替代shallow需要 ResizeObserver polyfill 和一个非零高度的真实滚动元素——jsdom 默认高度全是 0虚拟化器可能一个窗口都开不出来或在单元测试里 mocktanstack/react-virtual让useVirtualizer返回确定性假对象固定的getVirtualItems()、no-op 的measureElement把真正的窗口行为交给 Cypress 覆盖。推荐第二种它让单元测试专注于本组件的逻辑配置门控、requestResolvedSubtreedispatch、key/DOM 契约而把真实滚动行为留给拥有真实布局引擎的 E2E。八、上线策略自动数量阈值已定无配置开关已决策2026-08-04只有 schema 数超过阈值才虚拟化。不新增配置键。import { VIRTUALIZE_MODELS_THRESHOLD } from core/utils // 建议值 100 if (definitionEntries.length VIRTUALIZE_MODELS_THRESHOLD) { // legacy 路径——今天的标记逐字节不变 return renderLegacyModels() } // 下面是窗口化路径这是全票最具决定性的指令因为它把大部分风险逆转了保留现有渲染路径不动。转换时不要删除或“清理”今天的标记——把它抽成仍产出相同 DOM 的函数/分支。前面所有 DOM 契约项与 CSS 审计只作用于虚拟化分支legacy 分支天然保留它们。每个现有测试原样通过。features/models.swagger.yaml只有3个 definitionsfeatures/models.openapi.yaml同理所以model-collapse.cy.js和 Selenium 的:nth-child选择器main.js:506-539全走 legacy 路径、不受影响整个从本票风险面移除。虚拟化路径现有覆盖为零。新的性能夹具是它唯一的 E2E 训练场所以必须超过 100 个 definitions下面要求 ≥200保持这个余量。低于阈值的夹具会静默测试 legacy 路径等于把虚拟化未经验证地上线。测试边界两侧——一个夹具刚好低于阈值一个刚好高于。class → 函数式转换仍作用于整个组件两个分支都住在转换后的函数组件里。注意 hooksuseVirtualizer、useRef必须无条件调用、先于阈值分支——不能把早退 return 放在它们上面。九、验收标准清单低于 100-schema 阈值的 spec 渲染出与今天逐字节一致的标记legacy 路径——model-collapse.cy.js不改一行通过高于阈值的 spec 走窗口化路径仅视口内可见模型被挂载React DevTools 验证边界两侧都测——一个夹具刚好低于、一个刚好高于阈值滚动 Models 列表能正确渲染/卸载条目折叠/展开 Schemas/Models 区域的行为与之前一致现有model-collapse.cy.js场景不改一行通过——其夹具各只有 3 个 definitions走 legacy 路径。若其任何选择器.models h4 .models-control、#model-User .model-box .model-box-control于第 40/44 行#model-Pet/#model-Order于第 18/28/34 行需要改动说明 legacy 路径被动过——视为回归而不是改测试defaultModelsExpandDepth 0仍把整个 section 短路为nullmodels.jsxdefaultModelsExpandDepth 0 isShown仍驱动初始逐模型展开第 131 行无视觉回归——布局、间距、单个模型的展开/折叠不变无无障碍回归——键盘导航与屏幕阅读器顺序保留性能200 模型夹具的初始渲染时间相对已记录基线下降React Profiler前后对比test/unit/core/plugins/json-schema-5/components/models.jsx 单元测试更新ResizeObserverpolyfill 加入 test/unit/jest-shim.js 且npm run test:unit通过阻塞性前置条件通过npm run deps-size记录前后包体积影响tanstack/react-virtual约增加 5KB mingzip实测增量显著更大时在 PR 中标注swagger-ui-react仍能正确渲染模型——该 flavor 重导出 core 因此零代码改动继承本变更但它是独立发布的包且不在 Cypress 套件覆盖内E2E新夹具下 Models 区域滚动与渲染正确#model-Name浏览器锚点导航在阈值以下仍可用阈值以上失效按“可接受行为变化”接受。注意这是普通浏览器锚点——模型 deep-linking 不存在展开模型 A、滚出视口再滚回A 仍保持展开且没有别的模型被错误展开守护下文getItemKey要求十、成功度量与可接受行为变化10.1 度量方法在http://localhost:3200/上用新的many-schemas.yaml夹具或 Kubernetes spec跑 React Profiler之前N 个模型的渲染时间——记录真实数字目前尚无基线之后虚拟化后的渲染时间无论 N 多大都应接近恒定10.2 可接受的行为变化构建前需与维护者确认虚拟化把屏外内容移出 DOM。以下全部只作用于超过 100-schema 阈值的 spec——低于它时走 legacy 路径行为与今天逐字节一致与 Phase 3 共享浏览器页内查找Ctrl/Cmd-F不再能找到屏外模型。这是虚拟化的经典权衡对文档工具是真实的、用户可见的能力损失——用户惯于对 schema 名按 Ctrl-F。打印 / “另存为 PDF”只捕获已渲染窗口而非完整 schema 列表。浏览器锚点导航#model-Name对未挂载模型失效id{model-${name}}models.jsx。由于模型 deep-linking 不存在这个普通锚点是今天链接 schema 的唯一方式——所以这才是 Phase 1 真正的导航回归而不是次要问题。数量阈值本身就是缓解手段它覆盖了绝大多数 spec。对超阈值场景除了不虚拟化没有更多缓解没有应用内模型过滤器可兜底见下节 Out of Scope调高overscan也只是把窗口加宽几行。接受它或者提高阈值。十一、风险登记与范围外事项11.1 风险与缓解风险缓解deep-link 到屏外模型失效——不是风险master 上不存在模型 deep-linking见第六章无需处理。原样保留死的readyToScrollref浏览器锚点#model-Name对屏外模型失效——这才是真正的导航路径阈值/开关交由维护者决策见可接受行为变化class → 函数式转换丢失配置门控第 51 行defaultModelsExpandDepth 0早退、第 131 行 0 isShown展开门控两个边界显式做单元测试渲染体重构时它们最容易丢Collapse卸载.models-scroll在每次 section 切换时销毁滚动元素与测量缓存提前定下持久化策略见第五章约束显式测试展开 section → 滚动 → 折叠 → 再展开getScrollParent现在解析到.models-scroll而非window滚动行为改变给scrollToElement传显式containerE2E 验证 section 也能滚进视口E2E 选择器因 DOM 重构失效——被数量阈值中和。所有现有夹具 ≤3 个 definitions每条现有 Cypress/Selenium 选择器都走 legacy 路径无需处理。转换时不要“清理”legacy 标记——那才会重新引入此问题虚拟化路径未经验证上线因为每个现有夹具都在阈值以下新性能夹具是它唯一覆盖必须超过 100 个 definitions加一组刚好低于/刚好高于的边界对两条渲染路径随时间分叉——修复只落在其中一支legacy 分支保持为今天 JSX 的薄抽取而非平行重实现两条分支都做单元测试页内查找 / 打印回归见上阈值或开关交由维护者决策measureElement校正展开模型时的 CSS 布局位移item 包裹层加min-height: 72px11.2 范围外Operations 列表虚拟化 → Phase 3Schema 属性列表——本 epic 范围外详见 README 的 “Out of scope” 中为何拒绝在那里虚拟化OAS 3.1 模型渲染src/core/plugins/oas31/components/models/models.jsx——按 CLAUDE.md 跨插件规则它是本组件的自包含第二副本→Phase 2.claude/implementation/perf-virtualization/phase-2-oas31-models.md同版本发布。注意在 OAS 3.1 文档上渲染的是那个副本而非本组件基准测试前先用 React DevTools 确认哪个组件存活并只用many-schemas.openapi.yaml3.0.0——不要用 3.1 夹具——来度量本票模型搜索/过滤——目前不存在。src/core/plugins/filter/只提供opsFilter且只过滤操作tagmodels.jsx 不含任何过滤逻辑十二、依赖与实施顺序小结本票不依赖其他阶段——Phase 1 是第一个实施并把tanstack/react-virtual加入 package.json。不被阻塞两个此前悬而未决的决策均已落定——上线方式是自动数量阈值无配置键滚动容器是max-height: min(60vh, 800px)见 Rollout 节。推荐的落地顺序给 test/unit/jest-shim.js 加ResizeObserverpolyfill阻塞性前置基准在 240-schema 夹具下用 React Profiler 记录当前渲染时间用npm run deps-size记录当前包体积完成 class → 函数式转换保留第七章的 7 个行为与 DOM 契约引入VIRTUALIZE_MODELS_THRESHOLD阈值分支实现窗口化渲染useVirtualizergetItemKeymeasureElementref补.models-scroll样式与 CSS 审计更新单元测试mocktanstack/react-virtual的推荐策略跑npm run test:unit用新夹具跑 Cypress验证滚动、展开状态保持、锚点行为复核swagger-ui-react渲染前后对比渲染时间与包体积写 PR 时标注实测增量并把“可接受行为变化”摆到维护者面前确认。【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考