Harbor Portal 前端 Mock API Server 实战基于 Node.js Express TypeScript 的接口模拟方案【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor导读本文围绕 Harbor 仓库中 src/portal/server/README.md 所描述的前端 Mock API Server 展开讲解如何在后端服务未就绪时用 Node.js Express TypeScript 为 Harbor PortalAngular 前端搭建独立的接口模拟服务并通过开发代理将指定 API 请求精准转发到 Mock 服务。读完本文你将掌握 Mock 服务的路由注册、Controller 实现、启动命令、代理配置的完整五步流程并理解其底层实现原理。Harbor Portal 是 Harbor 的 Web 界面构建于 Angular 与 Clarity Design System 之上见 src/portal/README.md。在前后端并行开发时前端常常要面对「后端接口尚未实现」或「联调环境不稳定」的困境。Harbor 仓库在src/portal/server目录下内置了一个轻量级的 Mock API Server专门用于解决这一问题开发者可以脱离真实 Harbor 后端独立调试前端页面与业务逻辑。一、Mock API Server 的定位与架构从 src/portal/server/README.md 的第一行即可确认其技术栈Mocked Api-server based on Node.js Express Typescript。它的整体工作方式分为两条链路Mock 服务链路一个独立的 Express 应用监听3000端口为前端声明并返回模拟数据代理转发链路Angular 开发服务器ng serve通过代理配置把匹配到特定context的请求转发到 Mock 服务而其余请求仍转发到真实 Harbor 后端。这种「Mock 与真实后端共存」的设计非常关键你不需要一次性 Mock 全部接口只需针对正在开发的页面所需接口进行局部 Mock其余功能仍可正常联调真实环境。二、仓库中的真实实现剖析仓库中src/portal/server目录的实际结构如下src/portal/server/ ├── controllers/ │ ├── index.ts # 统一导出所有 Controller │ └── scanners.ts # Scanner 接口的 Mock 实现 ├── src/ │ └── mock-api.ts # Express 应用入口与路由注册 ├── README.md # 本文依据的说明文档 └── tsconfig.json # TypeScript 编译配置1. 服务入口 mock-api.ts入口文件 src/portal/server/src/mock-api.ts 展示了核心骨架import express from express; import { Express } from express; import * as Controllers from ../controllers; const mockApi: Express express(); const CURRENT_BASE_HREF: string /api/v2.0; mockApi.get(/, (req, res) { res.send(Hello World!); }); mockApi.get(CURRENT_BASE_HREF /scanners, Controllers.getScanner); mockApi.listen(3000, () { console.log(Api server listening on port 3000!); }); export default mockApi;这里有几个值得注意的实现细节CURRENT_BASE_HREF常量值为/api/v2.0与 Harbor 后端 v2.0 API 的版本前缀保持一致保证 Mock 路由与真实接口路径风格统一路由注册方式mockApi.get(CURRENT_BASE_HREF /scanners, Controllers.getScanner)把 HTTP GET/api/v2.0/scanners绑定到 Controller 函数监听端口固定为3000这也是代理配置中target指向的端口默认首页访问根路径/会返回Hello World!可用于快速验证 Mock 服务是否存活。2. Controller 实现与统一导出Controller 放在controllers目录下由 controllers/index.ts 统一导出export * from ./scanners;实际的 Scanner Mock 实现在 controllers/scanners.tsimport { Request, Response } from express; import { Scanner } from ../../ng-swagger-gen/models/scanner; export function getScanner(req: Request, res: Response) { const scanners: Scanner[] [ { name: demo, vendor: test, version: 1.0, }, ]; res.json(scanners); }注意 Controller 直接复用了ng-swagger-gen生成的前端模型类型Scanner位于ng-swagger-gen/models/scanner这样返回的 Mock 数据在类型层面与真实 API 完全对齐避免类型漂移。3. 编译配置 tsconfig.jsonsrc/portal/server/tsconfig.json 为 Mock 服务单独定义了编译配置{ compilerOptions: { module: commonjs, esModuleInterop: true, allowSyntheticDefaultImports: true, target: es6, noImplicitAny: true, moduleResolution: node, sourceMap: true, outDir: dist, baseUrl: . }, include: [src/**/*] }关键点module: commonjs编译产物为 Node.js 可直接运行的 CommonJS 模块outDir: dist编译输出到dist目录与 package.json 中启动命令的路径相对应target: es6输出 ES6 语法适配现代 Node 版本。三、五步搭建第一个 Mock 接口原文档给出了一套完整的五步操作流程下面结合仓库源码逐一步骤展开。Step 1注册路由假设你要为前端如下代码所请求的接口提供 MockgetScannersByName(name: string): ObservableScanner[] { name encodeURIComponent(name); return this.http.get(/api/scanners?ex_name${name}) .pipe(catchError(error observableThrowError(error))) .pipe(map(response response as Scanner[])); }编辑 mock-api.ts在文件中添加路由注册代码mockApi.get(/api/v2.0/scanners, Controllers.getScanner);路径一致性提醒Mock 路由必须与前端http.get实际请求的路径一致。上面前端代码请求的是/api/scanners而注册的是/api/v2.0/scanners——实践中请务必以你前端 Service 中的真实请求路径为准否则代理无法命中路由。仓库自带的getScanner示例即挂在/api/v2.0/scanners下与 v2.0 API 前缀保持一致。Step 2在 controllers 目录实现并导出方法在controllers目录下新建或修改实现文件导出处理函数签名遵循 Express 的(req, res)约定export function getScanner(req: Request, res: Response) { const scanners: Scanner[] [new Scanner(), new Scanner()]; res.json(scanners); }记得在 controllers/index.ts 中导出该文件例如export * from ./scanners;这样mock-api.ts中的Controllers.getScanner才能正确解析。Step 3启动 Mock 服务在src/portal目录下执行npm run mock-api-server该命令在 package.json 中的真实定义是build-mock-api-server: tsc -p server, mock-api-server: npm run build-mock-api-server node server/dist/server/src/mock-api.js即两步动作先用tsc -p server按server/tsconfig.json将 TypeScript 编译到dist再用 Node 运行编译产物server/dist/server/src/mock-api.js。启动成功后控制台会输出Api server listening on port 3000!。Step 4配置开发代理编辑代理配置文件在数组最前面添加一个代理对象将 Mock 相关请求重定向到http://localhost:3000[ // redirect requests to the mocked api server { context: [ /api/v2.0/scanners ], target: http://localhost:3000, secure: false, changeOrigin: true, logLevel: debug }, // redirect requests to the back-end server { context: [ /api, /c, /i18n, /chartrepo, /LICENSE, /swagger.json, /swagger2.json, /devcenter-api-2.0, /swagger-ui.bundle.js ], target: https://hostname, secure: false, changeOrigin: true, logLevel: debug } ]为什么 Mock 对象必须放在最前面因为context采用前缀匹配若把 Mock 对象放在后面/api/v2.0/scanners会先被第二项的/api前缀捕获并转发到真实后端Mock 就失效了。原文档明确要求「add a proxy object at the top」正是这个原因。Step 5启动前端开发服务器npm run start根据 src/portal/package.json该命令实际执行node --max_old_space_size2048 ./node_modules/angular/cli/bin/ng serve --ssl true --host 0.0.0.0Angular CLI 通过 angular.json 中的proxyConfig: proxy.config.mjs读取代理配置。此时打开https://localhost:4200凡是命中 Mockcontext的请求都会被转发到 3000 端口的 Mock 服务其余请求仍转发到https://hostname指向的真实 Harbor 后端。四、代理配置深度解析1. 配置文件格式的演进原文档示例中使用的是proxy.config.jsonJSON 格式带注释。而当前仓库实际使用的代理配置文件为proxy.config.mjsES Module 格式其模板存放在 src/portal/proxy.config.mjs.temp需要按 src/portal/README.md 的指引复制启用cp proxy.config.mjs.temp proxy.config.mjs复制后再编辑proxy.config.mjs指定 Harbor 服务地址。2. 配置项含义一览配置项含义示例值说明context需要转发的 URL 前缀数组[/api/v2.0/scanners]命中任意前缀即触发转发Mock 项必须置于最前target转发目标地址http://localhost:3000Mock或https://hostname真实后端端口需与 Mock 服务监听端口一致secure是否校验目标 HTTPS 证书false目标为自签名证书时设为false否则会握手失败changeOrigin改写请求的 Host 头为目标主机true解决跨域与虚拟主机路由问题logLevel代理日志级别debug设为debug可观察每条请求的实际转发路径3. 企业代理Corporate Proxy支持当前仓库的代理模板还内置了对企业网络代理的适配逻辑。在 proxy.config.mjs.temp 中const useAgent false; const specifiedAgentServer ${An agent server}; function setupForCorporateProxy(proxyConfig) { if (useAgent) { const agentServer process.env.http_proxy || process.env.HTTP_PROXY || specifiedAgentServer; if (agentServer) { const agent new HttpsProxyAgent(agentServer); proxyConfig.forEach(function(entry) { entry.agent agent; }); } } return proxyConfig; }工作机制是将useAgent置为true后优先读取环境变量http_proxy或HTTP_PROXY若为空则回退到specifiedAgentServer中硬编码的代理地址找到代理服务器后通过https-proxy-agent为代理配置中每一项转发规则挂上agent使所有转发请求都走企业代理出口。这对于在防火墙后开发 Harbor 前端的场景非常实用。五、真实案例复盘Mock/api/v2.0/scanners仓库自带的scanners案例是理解全流程的最佳范本串起来看前端请求Harbor Portal 的扫描器配置页面如 config-scanner.component.ts会调用扫描器相关 Service 请求列表数据路由命中请求/api/v2.0/scanners命中代理配置第一项被转发到http://localhost:3000Mock 响应Express 路由GET /api/v2.0/scanners调用 controllers/scanners.ts 中的getScanner返回[{ name: demo, vendor: test, version: 1.0 }]类型对齐返回数据使用ng-swagger-gen生成的Scanner模型类型前端response as Scanner[]的强转不会出现类型缺口。这个闭环展示了 Mock 服务的完整价值不需要起任何 Harbor 后端容器就能驱动前端扫描器配置页面完成渲染与交互开发。六、使用建议与注意事项综合原文档与源码实现实践中有几点值得留意路径前缀要一致Mock 路由路径、代理context、前端 Service 请求路径三者的前缀必须完全对齐参考CURRENT_BASE_HREF的/api/v2.0约定代理配置修改后需重启proxy.config.mjs由 Angular CLI 在启动时读取修改后需重启npm run start才生效同理修改 Mock 路由或 Controller 后需重启npm run mock-api-server该命令本身包含重新编译Mock 数据尽量贴近模型直接复用ng-swagger-gen/models/*下的类型定义构造返回数据能最大限度降低前后端类型不一致导致的联调成本Mock 与真实后端可以并存只在代理配置最前面追加需要 Mock 的路由项其余/api、/c、/i18n、/chartrepo、/swagger.json等路径仍转发到真实 Harbor 后端实现局部 Mock、整体联调企业网络环境若开发机在代理之后启用模板中的useAgent机制避免请求绕过代理而失败。这套 Mock 方案轻量、无外部依赖仅 Express 与 TypeScript且完全内置于仓库任何开发者 clone 仓库后即可按上述五步快速搭建自己的前端联调环境是 Harbor Portal 开发流程中值得复用的基础设施。【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考