RedHatInsights/javascript-clients 源代码: https://github.com/RedHatInsights/javascript-clients # Javascript 客户端 针对 Swagger API 自动生成的 Javascript 客户端 ### 概述 本仓库设置为一个单仓库（monorepo），用于统一所有 API 客户端的配置和发布周期。该仓库使用 NX (https://nx.dev/getting-started/intro) 作为单仓库管理器，并使用 Github Actions (https://docs.github.com/en/actions) 进行 CI/CD 以及将包发布到 NPM。 ### 本地开发 我们使用 Java 来安装和构建此生成器。请安装 Java 并最好也安装 Maven，以避免在构建此新生成器时遇到任何问题。 * 安装 Java 和 Maven 后，运行 npm install 安装依赖项 * 安装依赖项后，每当更改生成器内容时，可以运行 npm run build:generator 进行构建 ### 故障排查 #### Node 版本不匹配 本项目使用 nvm 管理 Node.js 版本。所需版本在 .nvmrc 中。 检查版本匹配： bash cat .nvmrc node --version 切换到正确版本： bash nvm use # 如果版本已安装 # 或者 nvm install # 如果版本未安装 切换 Node 版本后，干净地重新安装： bash rm -r .nx node_modules packages/*/node_modules nvm use npm install 这可以防止 package-lock.json 不匹配和过时的 Nx 缓存问题。 #### 发布到本地 registry 你可以将包发布到本地 registry 以测试导入是否正常工作。 sh # 启动本地 registry docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio # 添加用户并登录 npm adduser --registry http://127.0.0.1:4873 # 构建包 npx nx build @redhat-cloud-services/rbac-client # 发布包 NPM_CONFIG_REGISTRY=http://127.0.0.1:4873 npm publish --tag local ./packages/rbac 从包消费者的角度测试。 sh # 从本地 registry 安装包 NPM_CONFIG_REGISTRY=http://127.0.0.1:4873 npm install @redhat-cloud-services/[email protected] # 构建 NPM_CONFIG_REGISTRY=http://127.0.0.1:4873 npx tsc #### CI 因 package.json 和 package-lock.json 不匹配而失败 运行 GitHub Actions 的 Ubuntu 24.04 容器使用 .nvmrc 中的 Node 版本。因此，在运行 npm install 时，请确保使用相同的 Node 版本。 sh # 选项 1：在本地使用 nvm nvm use npm install # 选项 2：使用与 GitHub action 非常相似的容器（请查看 .nvmrc 获取版本） # 将 NODE_VERSION 替换为 .nvmrc 中的值 podman run --rm -it --userns=keep-id -v .:/workspace:Z -w /workspace -e PATH="/opt/acttoolcache/node/NODE_VERSION/x64/bin:$PATH" catthehacker/ubuntu:act-24.04 npm install #### NX 守护进程 有时 NX 在运行 build/generate 任务时无法遍历所有客户端包，并出现以下错误： bash > NX Daemon process terminated and closed the connection Please rerun the command, which will restart the daemon. If you get this error again, check for any errors in the daemon process logs found in: /RedHatInsights/javascript-clients/.nx/cache/d/daemon.log 如果发生这种情况，请尝试运行 npm run nx:reset 并重新触发 build/generate 任务。 #### 运行构建后看不到更改 默认情况下，NX 会在首次构建时缓存客户端构建结果。除非客户端发生更改，否则后续构建将使用缓存。为避免此缓存，请运行 npm run build:no-cache ### 创建新客户端 运行 npm run create-client 并输入新客户端名称（例如，输入 notifications 将生成 notifications-client）。所有必需的 TS 和 NX 配置文件将自动创建。 ### 指定 OpenAPI 规范位置 创建客户端后，在客户端的 project.json NX 配置中，为 client-generator 执行器添加 OpenAPI 规范位置作为对象条目。client-generator 支持多个规范条目。条目应遵循以下模式。 json { "name": "@redhat-cloud-services/CLIENTNAME-client", ... "targets": { "generate": { "executor": "@redhat-cloud-services/build-utils:client-generator", "options": { "specs": { "default": "https://raw.githubusercontent.com/RedHatInsights/insights-rbac/master/docs/source/specs/openapi.json", "v2": "https://raw.githubusercontent.com/RedHatInsights/insights-rbac/master/docs/source/specs/v2/openapi.v2.yaml" }, "clientName": "RbacClient" } }, ... } } 其中 specs 对象的键是导出端点的目录，对应的值是规范的位置。对于键，default 会将所有端点导出到客户端的根级别，而除 default 之外的任何键都会将端点导出到该路径下。以下是上述 default 和 v2 规范条目的导入示例： default: import { SomeEndpoint } from @redhat-cloud-services/some-client/dist/SomeEndpoint v2: import { SomeV2Endpoint } from @redhat-cloud-services/some-client/dist/v2/SomeV2Endpoint ### 生成和构建客户端 在根目录的 javascript-clients 文件夹下： * 要生成所有客户端，运行 npm run generate – NX 会通过位于 @redhat-cloud-services/build-utils 中的 client-generator 执行器执行 openapi-generator-cli 命令，根据客户端 openapi-spec.json 中定义的规范生成客户端。要生成单个客户端，运行 nx run @redhat-cloud-services/${your-client-name}-client:generate。如果未全局安装 openapi-generator-cli，则需要运行 npm install -g @openapitools/openapi-generator-cli * 要构建所有客户端并生成用于发布的 dist 目录，运行 npm run build – NX 仅在检测到客户端发生更改时构建包（否则引用缓存）。客户端构建完成后，我们的 builder（位于 packages/build-utils）会将每个客户端的 dist 移动到顶层的 dist 目录，以便在 PR 合并后发布到 NPM。如果希望无论是否发生更改都构建所有客户端，请使用 npx nx run-many --skip-nx-cache -t build --exclude=@redhat-cloud-services/CLIENTNAME-client。要构建单个客户端，运行 nx run @redhat-cloud-services/${your-client-name}-client:build。如果未全局安装 tsc，则需要运行 npm install -g @typescript ### 自定义模块联邦生成器 默认情况下，我们使用 typescript-axios 根据 OpenAPI 规范生成客户端。此外，我们还提供了一个自定义生成器，该生成器基于模块联邦思想构建，允许 webpack 进行 tree-shaking。这将为每个端点创建一个新文件夹，允许消费者仅导入他们要使用的端点，而无需导入整个 API。此生成器应能替代常规的 typescript-axios 生成器。下面是使用新生成器的示例脚本： json { "name": "@redhat-cloud-services/some-client-name", "version": "1.0.0", "scripts": { "generate": "TS_POST_PROCESS_FILE='../../postProcess.sh' openapi-generator-cli generate -i $SPEC --custom-generator=../../target/typescript-axios-webpack-module-federation-openapi-generator-1.0.0.jar -g typescript-axios-webpack-module-federation -o . --skip-validate-spec --enable-post-process-file" } } 如果以前使用的是 typescript-axios 生成器，则还需要将 openapitool.json 中的 generator-cli.version 版本至少更改为 6.6.0。 ## 运行客户端集成测试 某些客户端包中已添加集成测试。例如，在 packages/rbac/v2/tests/integration/workspaces.test.ts 中可以找到针对 Workspaces API 的端到端测试，该测试涵盖了 CRUD 操作的工作流程。要运行集成测试，请使用类似以下的命令： npm run test:integration 通常，模式是客户端有一个 tests/integration 文件夹，其中的测试文件名称匹配 *.test.ts。在每个客户端的文件夹（例如 packages/）中，应该有一个专用的 tsconfig.integration.spec.json，其中包含指向集成测试的 include glob 模式。同样，还应该有一个专用的 jest.integration.config.ts，在 transform 值中指向 tsconfig.integration.spec.json。此外，当创建集成测试时，每个客户端的 project.json 应该定义/添加一个 integration 目标。 ## 文档 | 文档 | 用途 | |–––––|———| | CONTRIBUTING.md | 设置、工作流程、提交约定、PR 指南 | | AGENTS.md | AI 代理入站、跨领域约定 | | docs/ARCHITECTURE.md | 系统设计、依赖关系图、数据流 | | docs/testing-guidelines.md | 测试类型、集成测试模式 | | docs/api-contracts-guidelines.md | OpenAPI 规范管理、代码生成管道 |