当前位置：首页 > news >正文

微服务架构下前端如何配置 OpenAPI 接口

news 来源：原创 2025/4/30 17:15:37

在微服务架构中，后端通常由多个独立的服务组成，每个服务可能提供自己的 API 接口。为了在前端项目中高效地调用这些 API，可以使用 OpenAPI 规范生成客户端代码。以下是详细的配置步骤和最佳实践：

1. 理解 OpenAPI 规范
OpenAPI 是一种用于描述 RESTful API 的规范（以前称为 Swagger 规范）。它定义了 API 的接口、参数、返回值等信息，并可以通过工具生成客户端代码。

OpenAPI 规范文件：通常是 `swagger.json` 或 `openapi.json`，可以通过后端服务的 `/v2/api-docs` 或 `/v3/api-docs` 路径获取。
生成客户端代码：使用 OpenAPI 工具（如 `openapi-typescript-codegen` 或 `openapi-generator-cli`）生成前端可用的 API 客户端代码。

2. 生成客户端代码

2.1 **安装工具
安装 `openapi-typescript-codegen` 或 `openapi-generator-cli`：

npm install openapi-typescript-codegen --save-dev
# 或
npm install @openapitools/openapi-generator-cli -g

2.2 生成代码
为每个微服务生成客户端代码。

# 生成 judge 服务的客户端代码
openapi --input http://localhost:8101/api/judge/v2/api-docs --output ./src/generated/judge --client axios

# 生成 question 服务的客户端代码
openapi --input http://localhost:8101/api/question/v2/api-docs --output ./src/generated/question --client axios

# 生成 user 服务的客户端代码
openapi --input http://localhost:8101/api/user/v2/api-docs --output ./src/generated/user --client axios

2.3 生成的代码结构
生成的代码会输出到指定目录（如 `./src/generated`），结构如下：

./src/generated/
  ├── judge/
  │   ├── api.ts          # API 客户端
  │   ├── models.ts       # 数据模型（类型定义）
  │   └── index.ts        # 入口文件
  ├── question/
  │   ├── api.ts
  │   ├── models.ts
  │   └── index.ts
  └── user/
      ├── api.ts
      ├── models.ts
      └── index.ts

3. 在前端项目中使用生成的代码 3.1 引入生成的客户端代码
在项目中引入生成的客户端代码

// 引入 judge 服务的客户端代码
import { DefaultApi as JudgeApi } from '@/generated/judge';

// 引入 question 服务的客户端代码
import { DefaultApi as QuestionApi } from '@/generated/question';

// 引入 user 服务的客户端代码
import { DefaultApi as UserApi } from '@/generated/user';

通过以上步骤，你可以在微服务架构下高效地配置和使用 OpenAPI 接口，提升开发效率和代码质量。