RedHatInsights/javascript-clients

# Javascript 客户端 自动生成的用于 Swagger API 的 Javascript 客户端 ### 概述 此存储库被设置为所有 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` 中。 **检查版本匹配：** ``` cat .nvmrc node --version ``` **切换到正确版本：** ``` nvm use # If version already installed # 重要提示： nvm install # If version not installed ``` **切换 Node 版本后，进行清洁重新安装：** ``` rm -r .nx node_modules packages/*/node_modules nvm use npm install ``` 这可以防止 `package-lock.json` 不匹配和过时的 Nx 缓存问题。 #### 发布到本地注册表 您可以将包发布到本地注册表以测试导入是否正常工作。 ``` # 保持所有专业术语、专有名词、工具/库/框架名称和技术术语的原英文形式。 docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio # 运行 Naabu 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 ``` 从包消费者角度进行测试。 ``` # 构建软件包 NPM_CONFIG_REGISTRY=http://127.0.0.1:4873 npm install @redhat-cloud-services/rbac-client@4.2.12-local # 发布软件包 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 版本。 ``` # 从本地注册表安装软件包 nvm use npm install # 构建 # 选项 1：在本地使用 nvm 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 守护进程 有时在运行 `build`/`generate` 任务时，NX 无法通过所有客户端包，并出现以下错误： ``` > 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 规范位置 在创建客户端后，将您的 OpenAPI 规范位置添加到客户端的 `project.json` NX 配置中的对象条目，作为 `client-generator` 执行器的 `openapi-spec.json` 中定义的规范。`client-generator` 支持多个规范条目。条目应遵循以下模式。 ``` { "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 进行 treeshaking。这将为每个端点创建一个新的文件夹，允许消费者仅导入他们将要使用的端点，而无需导入整个 API。此生成器应替换常规的 `typescript-axios` 生成器。以下是如何使用新生成器的示例脚本： ``` { "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 模式。类似地，也应该有一个指向 `tsconfig.integration.spec.json` 的专用 `jest.integration.config.ts`，在 `transform` 值中。此外，当创建集成测试时，每个客户端的 `project.json` 应该定义/添加一个 `integration` 目标。 ## 文档 | 文档 | 目的 | |------|------| | [CONTRIBUTING.md](CONTRIBUTING.md) | 设置、工作流程、提交约定、PR 指南 | | [AGENTS.md](AGENTS.md) | AI 代理入职、跨切面约定 | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 系统设计、依赖图、数据流 | | [docs/testing-guidelines.md](docs/testing-guidelines.md) | 测试类型、集成测试模式 | | [docs/api-contracts-guidelines.md](docs/api-contracts-guidelines.md) | OpenAPI 规范管理、代码生成管道 |

标签：API, Automated Testing, Client Library, CMS安全, Code Generation, Development Tools, Docker, Github Actions, GNU通用公共许可证, JavaScript, Local Registry, Maven, Node.js, npm, Nx, Package Management, Swagger, Version Management, 安全防御评估, 数据可视化, 漏洞验证, 自动化攻击