用 Scalar CLI 搭建 OpenAPI Mock Server从入门到源码级原理【免费下载链接】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 开源仓库中的 CLI 与scalar/mock-server包把一份 OpenAPI/Swagger 文档一键变成可交互的 mock HTTP 服务器。你将掌握scalar document mock的安装、三种常用选项--port/--watch/--once理解 mock 响应如何从 schema 生成、参数与认证如何校验、CI 中如何一次性运行并看到背后完整的请求处理链路源码证据。一、安装 Scalar CLI打开终端全局安装 Scalar CLInpm -g install scalar/cli安装完成后运行scalar document mock指向你的 OpenAPI 文档即可——无论它是JSON 还是 YAML、本地文件还是远程 URLscalar document mock https://cdn.jsdelivr.net/npm/scalar/galaxy/dist/3.1.json注意命令名冲突有一个scalarCLI 随 Git 一起捆绑分发。如果你遇到命名冲突且不会用到那个 Git 自带的 CLI可以用--force强制覆盖安装npm -g --force install scalar/cli或者如果你想保留 Git 自带的scalarCLI可以完全不安装改用npx/pnpm dlx临时执行详见 CLI 快速开始npx scalar/cli help # 不安装直接执行npm pnpm dlx scalar/cli help # 不安装直接执行pnpm启动后终端会打印一份按 HTTP 方法着色标记的路径清单列出 OpenAPI 文档中所有可请求的端点。接下来用 curl 或其他 HTTP 客户端发起请求就能收到这个服务器真实存在一般的响应数据基于你 schema 中的类型、格式与示例生成完全匹配 API 规格。二、三个最常用的自定义选项mock server 提供以下选项来定制行为选项作用默认值--port修改监听端口3000--watch监听 OpenAPI 文件变化修改后自动重载关闭--once只运行一次启动服务器、响应请求、然后退出适合 CI 流水线关闭典型用法# 换端口启动 scalar document mock ./openapi.yaml --port 8080 # 边改文档边自动重载 scalar document mock ./openapi.yaml --watch # 在 CI 中校验一次后退出 scalar document mock ./openapi.yaml --once从源码看create-mock-server.ts是这一切的核心入口它接收一份文档字符串 URL/路径或对象返回一个可独立启动的 Hono 应用实例。默认端口3000在 Docker 服务端实现中同样作为回退值出现见 server.ts。三、为什么 OpenAPI mock 值得关注Mock server 不只是假 API它能解锁多种加速开发、降低依赖的工作流并行开发前端与后端团队无需等待真实 API 落地可以独立并行推进。无风险测试针对 mock server 安全地运行测试与自动化脚本不会碰到生产或预发环境的真实故障。快速原型验证在编写任何业务逻辑之前尽早构建并验证 API 契约。减少第三方依赖接入第三方 API 时不再受对方的速率限制、调用成本与可用性约束。一个好的 mock server 能让你对 API 契约充满信心同时让整个团队保持推进速度。四、scalar document mock背后发生了什么按照官方文档的说明CLI 底层依赖开源的mock-server包来生成路由并服务请求整个请求流程如下加载与处理文档CLI 检测输入是文件还是 URL然后用scalar/openapi-parser完成加载、解引用dereference与校验。生成 Hono 路由mock-server包根据文档中的每个 path 生成 Hono 语法的路由并根据 schema 生成响应同时校验参数、按安全方案设置认证并返回恰当的 HTTP 状态码。Hono 提供服务生成的路由由轻量快速的 Hono HTTP 框架承载负责路由匹配、认证检查、参数提取与 mock 响应生成。schema 生成真实数据mock 响应使用开源的oas-utils包从 OpenAPI schema 生成真实感数据优先使用文档中定义的 examples。遵守 schema 约束生成的数据尊重类型、格式与校验规则等约束保证 mock 响应与 API 规格一致。这一切让开发者可以在数秒内启动一个快速、符合规范、对开发者友好的 mock server。五、源码级解析请求处理的完整链路5.1 文档的加载、打包与升级在 process-openapi-document.ts 中文档会经历三个阶段Bundle打包外部引用通过scalar/json-magic的bundle插件体系读取本地文件readFiles与远程 URLfetchUrls并启用blockPrivateNetworks防内网探测同时用parseJson/parseYaml支持字符串输入。本地$ref被限定在文档自身目录或工作目录内避免任意文件读取。Upgrade升级到 3.1用scalar/openapi-upgrader的upgrade(bundled, 3.1)将文档统一升级为 OpenAPI 3.1。Magic Proxy惰性解引用返回一个createMagicProxy包装的文档内部$ref保持原样、按需通过getResolvedRef解析避免一次性扁平化复制整个文档。输入为空时它还会返回一个最小可用的 OpenAPI 3.1 文档openapi: 3.1.0保证服务不会直接崩溃。5.2 从 path 到 Hono 路由在 create-mock-server.ts 中每个 path key 经过splitPathKey拆出路径与钉住的查询参数例如/v1/messages?betatrue再通过 hono-route-from-path.ts 转成 Hono 路由。这里有两个值得注意的工程细节防 ReDoSOpenAPI 文档是不可信输入模板路径段{name}被转成正则时会做字面量转义并精心构造匹配范围避免多个贪婪[^/]分组在恶意请求上指数回溯阻塞事件循环。变体路由排序钉住查询参数的 path key 会被移动到同路径兄弟路由之前注册并按照钉住参数数量排序保证更具体的变体优先匹配。每个 operation 会注册一串中间件middleware先记录被 mock 的 operation 上下文 → 认证检查 → 可选的onRequest回调 → 请求校验默认开启→ 响应生成。任意中间件抛错都会进入app.onError返回一个指明失败 operation 名称与错误消息的 JSON 500 响应而不是 Hono 默认的纯文本Internal Server Error。5.3 请求校验默认开启请求校验由 validate-request.ts 实现默认开启对应MockServerOptions.validateRequest默认true见 types.ts校验 path / query 参数与application/json请求体校验器只编译一次、跨请求复用没有逐请求重编译开销。违反契约时返回422响应体为application/problemjson列出每条违规的位置body/query/path/header/cookie、JSON 指针路径与消息。校验基于 Ajvajv/dist/2020.jsajv-formats递归 schema 中的[circular]标记会被替换为可编译形态见replaceCircularMarkers。5.4 mock 响应的生成核心实现在 mock-any-response.ts响应选择的优先级如下Prefer头精确指定状态码Prefer: code404命中定义的响应时优先采用。默认首选 key否则按default→200→201等顺序取首选响应2XX这类范围模式会映射为最低具体状态码如200。204 No Content返回空 body 且不设 Content-Type。响应头按 schema 示例生成各响应头值。Content-Type 协商根据请求Accept头在content中选取默认优先application/json。body 生成遵循这样的优先级见 select-response-example.tsPrefer: examplename显式指定的命名示例Media Type 上的单个example字段examples映射的第一项都没有时才用getExampleFromSchema来自scalar/workspace-store的 request-example 工具从 schema 生成支持将 path 参数注入为变量、空字符串策略等mode: read。Prefer头的解析遵循 RFC 7240见 parse-prefer-header.ts逗号/分号分隔的keyvaluetoken未知指令静默忽略。因此你可以这样精确选择返回内容# 强制返回 404 curl -H Prefer: code404 http://localhost:3000/pets/1 # 强制使用命名示例 notFound curl -H Prefer: examplenotFound http://localhost:3000/pets/1另外当响应 Content-Type 为text/event-stream时服务端会以 SSE 流的形式逐事件输出collectSseEvents HonostreamSSE而不是一次性缓冲整个 body。5.5 认证与安全方案handle-authentication.ts 按 OpenAPI 的 OR-of-ANDs 语义评估security只要任一 requirement 完全满足即放行requirement 内的每个 scheme 都要满足。支持的方案包括httpBasic只校验Basic base64(user:password)形态合法不做真实凭据校验httpBearer校验Bearer后存在非空 tokenapiKey在 header / query / cookie 中查找对应名字的参数oauth2/openIdConnect按 Bearer token 处理。认证失败时返回401WWW-Authenticate质询头如Basic realmScalar Mock Server并附 JSON 错误体。此外还提供了 OAuth 授权页 / token 端点相关路由见routes/respond-with-authorize-page.ts与set-up-authentication-routes.ts。5.6 扩展能力x-handler与x-seed从 create-mock-server.ts 与 x-seed.test.ts 可以看到mock server 支持两个 OpenAPI 扩展x-seed在components.schemas上声明一段种子代码启动时向内置 store 预置数据支持seed.count(n, ...)与seed(array)两种写法且集合为空时才播种幂等。x-handler在 operation 上声明自定义处理逻辑可返回store.list(Article)等自定义响应替代 schema 自动生成。例如components: schemas: Article: type: object properties: id: { type: string } title: { type: string } x-seed: | seed.count(3, () ({ id: faker.string.uuid(), title: faker.lorem.sentence() })) paths: /articles: get: x-handler: return store.list(Article); responses: 200: { description: OK }对应测试 x-seed.test.ts 验证了启动即播种、GET /articles返回 3 条带id/title/content的记录。5.7 内置文档端点无论文档来自哪里服务启动后都会暴露/openapi.json与/openapi.yaml返回原始 OpenAPI 文档便于配合 API Reference 消费/scalar内置的 Scalar API Reference 页面见 server.ts。也就是说mock server 同时还是一个可浏览的 API 文档站点。六、Docker 与 CI 中的使用仓库中提供了现成的 Docker 封装packages/mock-server/docker其startMockServer会自动识别 AsyncAPI 文档并切换到createAsyncApiMockServerWebSocket 通道否则走createMockServer见 server.ts并打印监听地址与 API Reference 地址。在 CI 中--once模式是最佳实践启动服务器 → 响应自动化测试请求 → 自动退出让流水线不会悬挂。若配合 openapi-validator 先校验文档再 mock可以在提交前就拦截规格错误如果文档定义了 security schemes记得在测试脚本里带上认证头避免被401挡住。七、小结scalar document mock用一条命令把 OpenAPI 文档变成可交互的 mock 服务schema 驱动的真实数据、默认开启的请求校验、认证支持、Prefer头精确控制响应、x-seed/x-handler扩展以及--watch/--once的 CI 友好选项。它的每一步——从文档打包升级、路由生成、参数校验到响应生成——都能在仓库的packages/mock-server源码与测试中找到对应实现非常适合作为团队并行开发、契约先行与自动化测试的基础设施。本文依据 原始博客、CLI 快速开始 与packages/mock-server源码撰写命令行为以当前仓库实际实现为准。【免费下载链接】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），仅供参考 用 Scalar CLI 搭建 OpenAPI Mock Server：从入门到源码级原理
用 Scalar CLI 搭建 OpenAPI Mock Server从入门到源码级原理【免费下载链接】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 开源仓库中的 CLI 与scalar/mock-server包把一份 OpenAPI/Swagger 文档一键变成可交互的 mock HTTP 服务器。你将掌握scalar document mock的安装、三种常用选项--port/--watch/--once理解 mock 响应如何从 schema 生成、参数与认证如何校验、CI 中如何一次性运行并看到背后完整的请求处理链路源码证据。一、安装 Scalar CLI打开终端全局安装 Scalar CLInpm -g install scalar/cli安装完成后运行scalar document mock指向你的 OpenAPI 文档即可——无论它是JSON 还是 YAML、本地文件还是远程 URLscalar document mock https://cdn.jsdelivr.net/npm/scalar/galaxy/dist/3.1.json注意命令名冲突有一个scalarCLI 随 Git 一起捆绑分发。如果你遇到命名冲突且不会用到那个 Git 自带的 CLI可以用--force强制覆盖安装npm -g --force install scalar/cli或者如果你想保留 Git 自带的scalarCLI可以完全不安装改用npx/pnpm dlx临时执行详见 CLI 快速开始npx scalar/cli help # 不安装直接执行npm pnpm dlx scalar/cli help # 不安装直接执行pnpm启动后终端会打印一份按 HTTP 方法着色标记的路径清单列出 OpenAPI 文档中所有可请求的端点。接下来用 curl 或其他 HTTP 客户端发起请求就能收到这个服务器真实存在一般的响应数据基于你 schema 中的类型、格式与示例生成完全匹配 API 规格。二、三个最常用的自定义选项mock server 提供以下选项来定制行为选项作用默认值--port修改监听端口3000--watch监听 OpenAPI 文件变化修改后自动重载关闭--once只运行一次启动服务器、响应请求、然后退出适合 CI 流水线关闭典型用法# 换端口启动 scalar document mock ./openapi.yaml --port 8080 # 边改文档边自动重载 scalar document mock ./openapi.yaml --watch # 在 CI 中校验一次后退出 scalar document mock ./openapi.yaml --once从源码看create-mock-server.ts是这一切的核心入口它接收一份文档字符串 URL/路径或对象返回一个可独立启动的 Hono 应用实例。默认端口3000在 Docker 服务端实现中同样作为回退值出现见 server.ts。三、为什么 OpenAPI mock 值得关注Mock server 不只是假 API它能解锁多种加速开发、降低依赖的工作流并行开发前端与后端团队无需等待真实 API 落地可以独立并行推进。无风险测试针对 mock server 安全地运行测试与自动化脚本不会碰到生产或预发环境的真实故障。快速原型验证在编写任何业务逻辑之前尽早构建并验证 API 契约。减少第三方依赖接入第三方 API 时不再受对方的速率限制、调用成本与可用性约束。一个好的 mock server 能让你对 API 契约充满信心同时让整个团队保持推进速度。四、scalar document mock背后发生了什么按照官方文档的说明CLI 底层依赖开源的mock-server包来生成路由并服务请求整个请求流程如下加载与处理文档CLI 检测输入是文件还是 URL然后用scalar/openapi-parser完成加载、解引用dereference与校验。生成 Hono 路由mock-server包根据文档中的每个 path 生成 Hono 语法的路由并根据 schema 生成响应同时校验参数、按安全方案设置认证并返回恰当的 HTTP 状态码。Hono 提供服务生成的路由由轻量快速的 Hono HTTP 框架承载负责路由匹配、认证检查、参数提取与 mock 响应生成。schema 生成真实数据mock 响应使用开源的oas-utils包从 OpenAPI schema 生成真实感数据优先使用文档中定义的 examples。遵守 schema 约束生成的数据尊重类型、格式与校验规则等约束保证 mock 响应与 API 规格一致。这一切让开发者可以在数秒内启动一个快速、符合规范、对开发者友好的 mock server。五、源码级解析请求处理的完整链路5.1 文档的加载、打包与升级在 process-openapi-document.ts 中文档会经历三个阶段Bundle打包外部引用通过scalar/json-magic的bundle插件体系读取本地文件readFiles与远程 URLfetchUrls并启用blockPrivateNetworks防内网探测同时用parseJson/parseYaml支持字符串输入。本地$ref被限定在文档自身目录或工作目录内避免任意文件读取。Upgrade升级到 3.1用scalar/openapi-upgrader的upgrade(bundled, 3.1)将文档统一升级为 OpenAPI 3.1。Magic Proxy惰性解引用返回一个createMagicProxy包装的文档内部$ref保持原样、按需通过getResolvedRef解析避免一次性扁平化复制整个文档。输入为空时它还会返回一个最小可用的 OpenAPI 3.1 文档openapi: 3.1.0保证服务不会直接崩溃。5.2 从 path 到 Hono 路由在 create-mock-server.ts 中每个 path key 经过splitPathKey拆出路径与钉住的查询参数例如/v1/messages?betatrue再通过 hono-route-from-path.ts 转成 Hono 路由。这里有两个值得注意的工程细节防 ReDoSOpenAPI 文档是不可信输入模板路径段{name}被转成正则时会做字面量转义并精心构造匹配范围避免多个贪婪[^/]分组在恶意请求上指数回溯阻塞事件循环。变体路由排序钉住查询参数的 path key 会被移动到同路径兄弟路由之前注册并按照钉住参数数量排序保证更具体的变体优先匹配。每个 operation 会注册一串中间件middleware先记录被 mock 的 operation 上下文 → 认证检查 → 可选的onRequest回调 → 请求校验默认开启→ 响应生成。任意中间件抛错都会进入app.onError返回一个指明失败 operation 名称与错误消息的 JSON 500 响应而不是 Hono 默认的纯文本Internal Server Error。5.3 请求校验默认开启请求校验由 validate-request.ts 实现默认开启对应MockServerOptions.validateRequest默认true见 types.ts校验 path / query 参数与application/json请求体校验器只编译一次、跨请求复用没有逐请求重编译开销。违反契约时返回422响应体为application/problemjson列出每条违规的位置body/query/path/header/cookie、JSON 指针路径与消息。校验基于 Ajvajv/dist/2020.jsajv-formats递归 schema 中的[circular]标记会被替换为可编译形态见replaceCircularMarkers。5.4 mock 响应的生成核心实现在 mock-any-response.ts响应选择的优先级如下Prefer头精确指定状态码Prefer: code404命中定义的响应时优先采用。默认首选 key否则按default→200→201等顺序取首选响应2XX这类范围模式会映射为最低具体状态码如200。204 No Content返回空 body 且不设 Content-Type。响应头按 schema 示例生成各响应头值。Content-Type 协商根据请求Accept头在content中选取默认优先application/json。body 生成遵循这样的优先级见 select-response-example.tsPrefer: examplename显式指定的命名示例Media Type 上的单个example字段examples映射的第一项都没有时才用getExampleFromSchema来自scalar/workspace-store的 request-example 工具从 schema 生成支持将 path 参数注入为变量、空字符串策略等mode: read。Prefer头的解析遵循 RFC 7240见 parse-prefer-header.ts逗号/分号分隔的keyvaluetoken未知指令静默忽略。因此你可以这样精确选择返回内容# 强制返回 404 curl -H Prefer: code404 http://localhost:3000/pets/1 # 强制使用命名示例 notFound curl -H Prefer: examplenotFound http://localhost:3000/pets/1另外当响应 Content-Type 为text/event-stream时服务端会以 SSE 流的形式逐事件输出collectSseEvents HonostreamSSE而不是一次性缓冲整个 body。5.5 认证与安全方案handle-authentication.ts 按 OpenAPI 的 OR-of-ANDs 语义评估security只要任一 requirement 完全满足即放行requirement 内的每个 scheme 都要满足。支持的方案包括httpBasic只校验Basic base64(user:password)形态合法不做真实凭据校验httpBearer校验Bearer后存在非空 tokenapiKey在 header / query / cookie 中查找对应名字的参数oauth2/openIdConnect按 Bearer token 处理。认证失败时返回401WWW-Authenticate质询头如Basic realmScalar Mock Server并附 JSON 错误体。此外还提供了 OAuth 授权页 / token 端点相关路由见routes/respond-with-authorize-page.ts与set-up-authentication-routes.ts。5.6 扩展能力x-handler与x-seed从 create-mock-server.ts 与 x-seed.test.ts 可以看到mock server 支持两个 OpenAPI 扩展x-seed在components.schemas上声明一段种子代码启动时向内置 store 预置数据支持seed.count(n, ...)与seed(array)两种写法且集合为空时才播种幂等。x-handler在 operation 上声明自定义处理逻辑可返回store.list(Article)等自定义响应替代 schema 自动生成。例如components: schemas: Article: type: object properties: id: { type: string } title: { type: string } x-seed: | seed.count(3, () ({ id: faker.string.uuid(), title: faker.lorem.sentence() })) paths: /articles: get: x-handler: return store.list(Article); responses: 200: { description: OK }对应测试 x-seed.test.ts 验证了启动即播种、GET /articles返回 3 条带id/title/content的记录。5.7 内置文档端点无论文档来自哪里服务启动后都会暴露/openapi.json与/openapi.yaml返回原始 OpenAPI 文档便于配合 API Reference 消费/scalar内置的 Scalar API Reference 页面见 server.ts。也就是说mock server 同时还是一个可浏览的 API 文档站点。六、Docker 与 CI 中的使用仓库中提供了现成的 Docker 封装packages/mock-server/docker其startMockServer会自动识别 AsyncAPI 文档并切换到createAsyncApiMockServerWebSocket 通道否则走createMockServer见 server.ts并打印监听地址与 API Reference 地址。在 CI 中--once模式是最佳实践启动服务器 → 响应自动化测试请求 → 自动退出让流水线不会悬挂。若配合 openapi-validator 先校验文档再 mock可以在提交前就拦截规格错误如果文档定义了 security schemes记得在测试脚本里带上认证头避免被401挡住。七、小结scalar document mock用一条命令把 OpenAPI 文档变成可交互的 mock 服务schema 驱动的真实数据、默认开启的请求校验、认证支持、Prefer头精确控制响应、x-seed/x-handler扩展以及--watch/--once的 CI 友好选项。它的每一步——从文档打包升级、路由生成、参数校验到响应生成——都能在仓库的packages/mock-server源码与测试中找到对应实现非常适合作为团队并行开发、契约先行与自动化测试的基础设施。本文依据 原始博客、CLI 快速开始 与packages/mock-server源码撰写命令行为以当前仓库实际实现为准。【免费下载链接】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），仅供参考