- REST API入口"] -NacosServiceImpl["NacosServiceImpl
- 核心业务逻辑"] -DTO["DTO
- CreateNacosParam, NacosResult"] -end -subgraph "portal-dal" -NacosInstance["NacosInstance
- 数据实体"] -Repository["NacosInstanceRepository
- JPA数据访问"] -end -NacosController --> NacosServiceImpl -NacosServiceImpl --> Repository -DTO --> NacosController -DTO --> NacosServiceImpl -NacosInstance --> Repository -``` - -**图示来源** -- [NacosController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/NacosController.java) -- [NacosServiceImpl.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/service/impl/NacosServiceImpl.java) -- [NacosInstance.java](file://portal-dal/src/main/java/com/alibaba/apiopenplatform/entity/NacosInstance.java) - -**本节来源** -- [NacosController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/NacosController.java) -- [NacosInstance.java](file://portal-dal/src/main/java/com/alibaba/apiopenplatform/entity/NacosInstance.java) - -## 核心组件 -核心组件包括`NacosController`（API入口）、`NacosServiceImpl`（业务逻辑）、`NacosInstance`（数据模型）和`NacosInstanceRepository`（数据访问层）。这些组件共同实现了对Nacos实例的全生命周期管理。 - -**本节来源** -- [NacosController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/NacosController.java) -- [NacosServiceImpl.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/service/impl/NacosServiceImpl.java) -- [NacosInstance.java](file://portal-dal/src/main/java/com/alibaba/apiopenplatform/entity/NacosInstance.java) -- [NacosInstanceRepository.java](file://portal-dal/src/main/java/com/alibaba/apiopenplatform/repository/NacosInstanceRepository.java) - -## 架构概览 -系统采用典型的分层架构，从上至下分为控制器层、服务层和数据访问层。`NacosController`接收HTTP请求并调用`NacosServiceImpl`，后者通过`NacosInstanceRepository`操作数据库，并使用Nacos官方客户端与外部Nacos集群通信。 - -```mermaid -graph TB -Client[客户端] --> NacosController["NacosController
- 处理REST请求"] -NacosController --> NacosServiceImpl["NacosServiceImpl
- 实现业务逻辑"] -NacosServiceImpl --> Repository["NacosInstanceRepository
- JPA持久化"] -NacosServiceImpl --> NacosClient["Nacos Maintainer Client
- 外部集群通信"] -Repository --> Database[(数据库)] -NacosClient --> ExternalNacos[Nacos集群] -``` - -**图示来源** -- [NacosController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/NacosController.java) -- [NacosServiceImpl.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/service/impl/NacosServiceImpl.java) -- [NacosInstanceRepository.java](file://portal-dal/src/main/java/com/alibaba/apiopenplatform/repository/NacosInstanceRepository.java) - -## 详细组件分析 - -### NacosController分析 -`NacosController`是Nacos功能的RESTful API入口，提供了对Nacos实例的增删改查操作。 - -#### REST API接口 -```mermaid -classDiagram -class NacosController { -+listNacosInstances(Pageable) PageResult~NacosResult~ -+fetchNacos(QueryNacosParam, Pageable) PageResult~MseNacosResult~ -+getNacosInstance(String) NacosResult -+createNacosInstance(CreateNacosParam) void -+updateNacosInstance(String, UpdateNacosParam) void -+deleteNacosInstance(String) void -+fetchMcpServers(String, String, Pageable) PageResult~NacosMCPServerResult~ -+fetchNamespaces(String, Pageable) PageResult~NacosNamespaceResult~ -} -NacosController --> NacosService : "依赖" -``` - -**图示来源** -- [NacosController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/NacosController.java) - -#### API调用流程 -```mermaid -sequenceDiagram -participant Client as "客户端" -participant Controller as "NacosController" -participant Service as "NacosServiceImpl" -participant Repository as "NacosInstanceRepository" -participant NacosClient as "Nacos Maintainer Client" -Client->>Controller : POST /nacos -Controller->>Service : createNacosInstance(param) -Service->>Repository : findByNacosName(name) -alt 实例已存在 -Repository-->>Service : 返回实例 -Service-->>Controller : 抛出BusinessException -Controller-->>Client : 400 Bad Request -else 实例不存在 -Repository-->>Service : null -Service->>Service : param.convertTo() -Service->>Repository : save(instance) -Repository-->>Service : 保存成功 -Service-->>Controller : 返回 -Controller-->>Client : 200 OK -end -``` - -**图示来源** -- [NacosController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/NacosController.java) -- [NacosServiceImpl.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/service/impl/NacosServiceImpl.java) - -**本节来源** -- [NacosController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/NacosController.java) - -### NacosServiceImpl分析 -`NacosServiceImpl`实现了Nacos相关的所有业务逻辑，包括与数据库和外部Nacos集群的交互。 - -#### 服务方法调用关系 -```mermaid -flowchart TD -A[createNacosInstance] --> B[检查实例名是否已存在] -B --> C{已存在?} -C --> |是| D[抛出RESOURCE_EXIST异常] -C --> |否| E[转换参数为实体] -E --> F[生成或验证nacosId] -F --> G[设置管理员ID] -G --> H[保存到数据库] -I[fetchNamespaces] --> J[查找Nacos实例] -J --> K[构建NamingMaintainerService] -K --> L[调用getNamespaceList()] -L --> M{调用成功?} -M --> |是| N[转换为NacosNamespaceResult] -M --> |否| O[抛出INTERNAL_ERROR异常] -``` - -**图示来源** -- [NacosServiceImpl.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/service/impl/NacosServiceImpl.java) - -#### 连接配置处理 -`NacosServiceImpl`在构建与外部Nacos集群的连接时，会将`NacosInstance`实体中的连接信息（如服务器地址、用户名、密码、AK/SK）转换为Nacos客户端所需的`Properties`对象。 - -```java -private Properties buildProperties(NacosInstance instance, String namespace) { - Properties properties = new Properties(); - properties.setProperty(PropertyKeyConst.SERVER_ADDR, instance.getServerUrl()); - if (instance.getUsername() != null) { - properties.setProperty(PropertyKeyConst.USERNAME, instance.getUsername()); - } - if (instance.getPassword() != null) { - properties.setProperty(PropertyKeyConst.PASSWORD, instance.getPassword()); - } - properties.setProperty(PropertyKeyConst.CONTEXT_PATH, "nacos"); - properties.setProperty(PropertyKeyConst.NAMESPACE, namespace); - if (instance.getAccessKey() != null) { - properties.setProperty(PropertyKeyConst.ACCESS_KEY, instance.getAccessKey()); - } - if (instance.getSecretKey() != null) { - properties.setProperty(PropertyKeyConst.SECRET_KEY, instance.getSecretKey()); - } - return properties; -} -``` - -**本节来源** -- [NacosServiceImpl.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/service/impl/NacosServiceImpl.java) - -### 数据模型分析 -`NacosInstance`实体类定义了Nacos实例在数据库中的存储结构。 - -```mermaid -erDiagram -NacosInstance { -string nacosId PK -string nacosName UK -string serverUrl -string username -string password Encrypted -string accessKey Encrypted -string secretKey Encrypted -string description -string adminId -datetime createAt -} -``` - -**图示来源** -- [NacosInstance.java](file://portal-dal/src/main/java/com/alibaba/apiopenplatform/entity/NacosInstance.java) - -## 依赖分析 -系统依赖关系清晰，各层职责分明。`NacosController`依赖`NacosService`接口，`NacosServiceImpl`依赖`NacosInstanceRepository`和Nacos客户端库。 - -```mermaid -graph TD -NacosController --> NacosService -NacosServiceImpl --> NacosInstanceRepository -NacosServiceImpl --> NacosClientLibrary -NacosInstanceRepository --> JPA -NacosInstanceRepository --> Database -``` - -**图示来源** -- [NacosController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/NacosController.java) -- [NacosServiceImpl.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/service/impl/NacosServiceImpl.java) -- [NacosInstanceRepository.java](file://portal-dal/src/main/java/com/alibaba/apiopenplatform/repository/NacosInstanceRepository.java) - -**本节来源** -- [NacosController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/NacosController.java) -- [NacosServiceImpl.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/service/impl/NacosServiceImpl.java) -- [NacosInstanceRepository.java](file://portal-dal/src/main/java/com/alibaba/apiopenplatform/repository/NacosInstanceRepository.java) - -## 性能考虑 -- **连接池**：Nacos客户端内部维护连接池，避免频繁创建销毁连接。 -- **分页查询**：所有列表接口均支持分页，防止一次性加载过多数据。 -- **缓存机制**：虽然当前代码未显式实现缓存，但Nacos客户端本身具有缓存能力。 -- **异步处理**：外部API调用（如MSE）可能耗时，建议在高并发场景下考虑异步化。 - -## 故障排除指南 -### 连接测试与错误处理 -当系统无法连接到外部Nacos集群时，会抛出相应的业务异常。 - -#### 连接失败场景 -```mermaid -stateDiagram-v2 -[*] --> 连接测试 -连接测试 --> 连接成功 : 网络可达
认证通过 -连接测试 --> 连接失败 : 网络不可达
或权限不足 -连接失败 --> 抛出异常 -抛出异常 --> ErrorCode.NACOS_CONNECT_FAILED : 错误码 -抛出异常 --> 日志记录 : 记录详细错误信息 -``` - -#### 常见错误码 -- **ErrorCode.RESOURCE_NOT_FOUND**：指定的Nacos实例ID不存在。 -- **ErrorCode.RESOURCE_EXIST**：尝试创建的Nacos实例名称已存在。 -- **ErrorCode.INTERNAL_ERROR**：内部错误，如调用外部API失败。 -- **ErrorCode.NACOS_CONNECT_FAILED**：无法连接到Nacos集群（代码中体现为`NacosException`被包装为`INTERNAL_ERROR`）。 - -#### 恢复建议 -1. **检查网络连通性**：确保服务器地址和端口可访问。 -2. **验证认证信息**：检查用户名/密码或AK/SK是否正确。 -3. **查看日志**：检查`NacosServiceImpl`中的错误日志获取详细信息。 -4. **测试外部API**：如果是从MSE获取集群，确保MSE的Region和凭证正确。 - -**本节来源** -- [NacosServiceImpl.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/service/impl/NacosServiceImpl.java) -- [ErrorCode.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/core/exception/ErrorCode.java) - -## 结论 -本文档全面分析了Nacos集成API的设计与实现。系统通过清晰的分层架构，实现了对Nacos实例的高效管理。`NacosController`提供了标准化的RESTful接口，`NacosServiceImpl`封装了复杂的业务逻辑和外部通信，而数据模型和仓库确保了数据的持久化。该设计具有良好的扩展性和可维护性，为后续功能迭代奠定了坚实基础。 \ No newline at end of file diff --git "a/.qoder/repowiki/zh/content/RESTful API \346\226\207\346\241\243/\345\244\226\351\203\250\347\263\273\347\273\237\351\233\206\346\210\220API/\345\244\226\351\203\250\347\263\273\347\273\237\351\233\206\346\210\220API.md" "b/.qoder/repowiki/zh/content/RESTful API \346\226\207\346\241\243/\345\244\226\351\203\250\347\263\273\347\273\237\351\233\206\346\210\220API/\345\244\226\351\203\250\347\263\273\347\273\237\351\233\206\346\210\220API.md" deleted file mode 100644 index e7c1351bf..000000000 --- "a/.qoder/repowiki/zh/content/RESTful API \346\226\207\346\241\243/\345\244\226\351\203\250\347\263\273\347\273\237\351\233\206\346\210\220API/\345\244\226\351\203\250\347\263\273\347\273\237\351\233\206\346\210\220API.md" +++ /dev/null @@ -1,295 +0,0 @@ -# 外部系统集成API - - -**本文档引用的文件** -- [GatewayController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/GatewayController.java) -- [NacosController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/NacosController.java) -- [ImportGatewayParam.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/dto/params/gateway/ImportGatewayParam.java) -- [CreateNacosParam.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/dto/params/nacos/CreateNacosParam.java) -- [GatewayOperator.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/service/gateway/GatewayOperator.java) -- [NacosService.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/service/NacosService.java) - - -## 目录 -1. [简介](#简介) -2. [核心组件概览](#核心组件概览) -3. [网关管理API详解](#网关管理api详解) -4. [Nacos服务发现API详解](#nacos服务发现api详解) -5. [配置参数结构分析](#配置参数结构分析) -6. [外部系统交互机制](#外部系统交互机制) -7. [完整调用示例](#完整调用示例) -8. [配置验证与错误排查](#配置验证与错误排查) - -## 简介 -本文档详细说明了外部系统集成API的功能，重点涵盖Higress和APIG网关实例的导入与管理，以及MSE Nacos服务发现实例的创建与同步。文档解析了`GatewayController`和`NacosController`中的各个端点，包括其HTTP方法、路径、请求参数和响应结果。同时，解释了不同网关类型的配置差异、连接测试机制、命名空间同步逻辑，以及`GatewayOperator`和`NacosService`如何与外部系统进行交互。 - -## 核心组件概览 - -系统通过`GatewayController`和`NacosController`提供RESTful API，用于管理外部网关和Nacos实例。`GatewayService`和`NacosService`作为业务逻辑层，协调数据持久化与外部系统通信。`GatewayOperator`和`NacosService`中的客户端（如`HigressClient`、`APIGClient`）负责与外部API进行实际交互。 - -**Section sources** -- [GatewayController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/GatewayController.java) -- [NacosController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/NacosController.java) - -## 网关管理API详解 - -`GatewayController`提供了对Higress和APIG等网关实例的全生命周期管理。 - -### 端点列表 - -| HTTP方法 | 路径 | 功能 | 请求参数 | -| :--- | :--- | :--- | :--- | -| `GET` | `/gateways` | 获取已导入的网关列表 | `Pageable` | -| `POST` | `/gateways` | 导入一个新的网关实例 | `ImportGatewayParam` | -| `DELETE` | `/gateways/{gatewayId}` | 删除指定的网关实例 | `gatewayId` (路径参数) | -| `GET` | `/gateways/apig` | 从阿里云获取APIG网关列表 | `QueryAPIGParam` | -| `POST` | `/gateways/adp` | 获取ADP AI网关列表 | `QueryAdpAIGatewayParam` | -| `GET` | `/gateways/{gatewayId}/rest-apis` | 获取指定网关的REST API列表 | `gatewayId` (路径参数) | -| `GET` | `/gateways/{gatewayId}/mcp-servers` | 获取指定网关的MCP Server列表 | `gatewayId` (路径参数) | -| `GET` | `/gateways/{gatewayId}/dashboard` | 获取指定网关的仪表板URL | `gatewayId` (路径参数) | - -### 导入网关流程 - -导入网关的核心是`/gateways`端点的`POST`请求。系统首先通过`GatewayType`判断网关类型，然后验证对应的配置对象（`apigConfig`, `higressConfig`等）是否有效。 - -```mermaid -sequenceDiagram -participant Client as "客户端" -participant Controller as "GatewayController" -participant Service as "GatewayService" -participant Operator as "GatewayOperator" -participant External as "外部网关 (Higress/APIG)" -Client->>Controller : POST /gateways (ImportGatewayParam) -Controller->>Service : importGateway(param) -Service->>Service : validateConfig(param) -alt 配置有效 -Service->>Operator : testConnection(config) -Operator->>External : 发送连接测试请求 -External-->>Operator : 返回连接状态 -alt 连接成功 -Operator-->>Service : true -Service->>Service : 保存网关信息到数据库 -Service-->>Controller : void -Controller-->>Client : 200 OK -else 连接失败 -Operator-->>Service : false -Service-->>Controller : 抛出连接异常 -Controller-->>Client : 400 Bad Request -end -else 配置无效 -Service-->>Controller : 抛出验证异常 -Controller-->>Client : 400 Bad Request -end -``` - -**Diagram sources** -- [GatewayController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/GatewayController.java#L58-L62) -- [GatewayService.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/service/GatewayService.java) -- [GatewayOperator.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/service/gateway/GatewayOperator.java) - -**Section sources** -- [GatewayController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/GatewayController.java) - -## Nacos服务发现API详解 - -`NacosController`负责管理与Nacos服务发现实例的连接，支持从阿里云MSE获取集群列表和同步服务。 - -### 端点列表 - -| HTTP方法 | 路径 | 功能 | 请求参数 | -| :--- | :--- | :--- | :--- | -| `GET` | `/nacos` | 获取已创建的Nacos实例列表 | `Pageable` | -| `POST` | `/nacos` | 创建一个新的Nacos实例 | `CreateNacosParam` | -| `PUT` | `/nacos/{nacosId}` | 更新指定的Nacos实例 | `UpdateNacosParam` | -| `DELETE` | `/nacos/{nacosId}` | 删除指定的Nacos实例 | `nacosId` (路径参数) | -| `GET` | `/nacos/mse` | 从阿里云MSE获取Nacos集群列表 | `QueryNacosParam` | -| `GET` | `/nacos/{nacosId}/mcp-servers` | 获取指定Nacos实例中的MCP Server列表 | `nacosId`, `namespaceId` (可选) | -| `GET` | `/nacos/{nacosId}/namespaces` | 获取指定Nacos实例的命名空间列表 | `nacosId` | - -### Nacos命名空间同步逻辑 - -系统通过`fetchNamespaces`和`fetchMcpServers`端点实现命名空间和服务的同步。当用户请求获取MCP Server时，系统会使用`namespaceId`作为过滤条件，从Nacos实例中拉取对应命名空间下的服务。 - -```mermaid -flowchart TD -A["客户端: GET /nacos/{nacosId}/mcp-servers?namespaceId=xxx"] --> B[NacosController] -B --> C[NacosService.fetchMcpServers(nacosId, namespaceId)] -C --> D{namespaceId 是否为空?} -D --> |是| E["NacosService: 使用默认命名空间"] -D --> |否| F["NacosService: 使用指定的 namespaceId"] -E --> G[NacosService 调用 NacosClient] -F --> G -G --> H["NacosClient: 向 Nacos 服务器发送 /nacos/v1/ns/service/list 请求"] -H --> I["Nacos服务器返回服务列表"] -I --> J["NacosService: 过滤出 MCP Server 类型的服务"] -J --> K["NacosService: 转换为 NacosMCPServerResult"] -K --> L["NacosController: 返回 PageResult
{username, password} -Controller->>Service : login(username, password) -Service-->>Controller : AuthResponseResult(token, admin) -Controller-->>Client : 返回token和管理员信息 -Client->>Controller : GET /admins
Authorization : Bearer token -Controller->>TokenUtil : 验证token有效性 -TokenUtil-->>Controller : 验证通过 -Controller->>Service : getAdministrator() -Service-->>Controller : AdminResult -Controller-->>Client : 返回管理员信息 -``` - -**Diagram sources** -- [AdministratorController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/AdministratorController.java#L28-L73) -- [TokenUtil.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/core/utils/TokenUtil.java) - -## 权限控制机制 -系统通过自定义注解`@AdminAuth`实现管理员权限控制。该注解应用于需要管理员身份才能访问的接口上。 - -**工作原理**: -1. 请求到达带有`@AdminAuth`注解的接口 -2. 框架触发权限验证逻辑 -3. 从请求头提取JWT令牌 -4. 验证令牌是否有效且未过期 -5. 检查令牌是否在黑名单中（已登出） -6. 若验证通过，则允许访问；否则返回401未授权错误 - -此机制确保只有经过身份验证的管理员才能执行敏感操作。 - -```mermaid -flowchart TD -Start([接收到请求]) --> HasAuthHeader{"是否存在Authorization头?"} -HasAuthHeader --> |否| Return401["返回401 Unauthorized"] -HasAuthHeader --> |是| ExtractToken["提取Bearer Token"] -ExtractToken --> IsValidJWT{"是否为有效JWT?"} -IsValidJWT --> |否| Return401 -IsValidJWT --> |是| IsBlacklisted{"令牌是否在黑名单?"} -IsBlacklisted --> |是| Return401 -IsBlacklisted --> |否| Proceed["继续执行业务逻辑"] -Return401 --> End([响应结束]) -Proceed --> End -``` - -**Diagram sources** -- [AdministratorController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/AdministratorController.java#L34-L39) -- [TokenUtil.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/core/utils/TokenUtil.java) - -## 使用示例 - -### 创建管理员（初始化） -```bash -curl -X POST http://localhost:8080/admins/init \ - -H "Content-Type: application/json" \ - -d '{ - "username": "admin", - "password": "admin123" - }' -``` - -### 管理员登录 -```bash -curl -X POST http://localhost:8080/admins/login \ - -H "Content-Type: application/json" \ - -d '{ - "username": "admin", - "password": "admin123" - }' -``` -**预期响应**: -```json -{ - "token": "eyJhbGciOiJIUzI1NiIs...", - "admin": { - "adminId": "1", - "username": "admin", - "createAt": "2023-01-01T10:00:00", - "updatedAt": "2023-01-01T10:00:00" - } -} -``` - -### 获取管理员信息（需认证） -```bash -curl -X GET http://localhost:8080/admins \ - -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." -``` - -## 常见错误码 -| 状态码 | 错误类型 | 含义 | 处理方式 | -|--------|----------|------|----------| -| 400 | Bad Request | 请求参数无效（如用户名为空） | 检查请求体格式和必填字段 | -| 401 | Unauthorized | 未提供令牌或令牌无效/过期 | 重新登录获取新令牌 | -| 403 | Forbidden | 无权访问（如未初始化时尝试登录） | 先调用`/init`初始化管理员 | -| 409 | Conflict | 用户名已存在（初始化时） | 使用其他用户名或确认是否已初始化 | -| 410 | Gone | 系统已初始化，无法再次初始化 | 不再调用`/init`接口 | -| 422 | Unprocessable Entity | 旧密码错误（修改密码时） | 确认旧密码输入正确 | - -## 依赖关系图 -```mermaid -classDiagram -class AdministratorController { -+login(AdminLoginParam) AuthResponseResult -+logout(HttpServletRequest) void -+needInit() Boolean -+initAdmin(AdminCreateParam) AdminResult -+resetPassword(ResetPasswordParam) void -+getAdministrator() AdminResult -} -class AdminCreateParam { -+username String -+password String -} -class AdminLoginParam { -+username String -+password String -} -class ResetPasswordParam { -+oldPassword String -+newPassword String -} -class AdminResult { -+adminId String -+username String -+createAt LocalDateTime -+updatedAt LocalDateTime -} -class AuthResponseResult { -+token String -+admin AdminResult -} -class TokenUtil { -+revokeToken(HttpServletRequest) void -} -class AdministratorService { -+login(String, String) AuthResponseResult -+initAdmin(String, String) AdminResult -+needInit() Boolean -+resetPassword(String, String) void -+getAdministrator() AdminResult -} -AdministratorController --> AdministratorService : "依赖" -AdministratorController --> TokenUtil : "调用" -AdministratorController --> AdminLoginParam : "接收" -AdministratorController --> AdminCreateParam : "接收" -AdministratorController --> ResetPasswordParam : "接收" -AdministratorController --> AuthResponseResult : "返回" -AdministratorController --> AdminResult : "返回" -``` - -**Diagram sources** -- [AdministratorController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/AdministratorController.java) -- [AdministratorService.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/service/AdministratorService.java) -- [TokenUtil.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/core/utils/TokenUtil.java) -- [AdminCreateParam.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/dto/params/admin/AdminCreateParam.java) -- [AdminLoginParam.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/dto/params/admin/AdminLoginParam.java) -- [ResetPasswordParam.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/dto/params/admin/ResetPasswordParam.java) -- [AdminResult.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/dto/result/AdminResult.java) \ No newline at end of file diff --git "a/.qoder/repowiki/zh/content/\345\211\215\347\253\257\346\236\266\346\236\204\344\270\216\347\273\204\344\273\266/API\345\256\242\346\210\267\347\253\257\344\270\216\347\212\266\346\200\201\347\256\241\347\220\206.md" "b/.qoder/repowiki/zh/content/\345\211\215\347\253\257\346\236\266\346\236\204\344\270\216\347\273\204\344\273\266/API\345\256\242\346\210\267\347\253\257\344\270\216\347\212\266\346\200\201\347\256\241\347\220\206.md" deleted file mode 100644 index 0b4264869..000000000 --- "a/.qoder/repowiki/zh/content/\345\211\215\347\253\257\346\236\266\346\236\204\344\270\216\347\273\204\344\273\266/API\345\256\242\346\210\267\347\253\257\344\270\216\347\212\266\346\200\201\347\256\241\347\220\206.md" +++ /dev/null @@ -1,288 +0,0 @@ -# API客户端与状态管理 - - -**本文档引用的文件** -- [api.ts](file://portal-web/api-portal-admin/src/lib/api.ts#L1-L252) -- [LoadingContext.tsx](file://portal-web/api-portal-admin/src/contexts/LoadingContext.tsx#L1-L30) -- [utils.ts](file://portal-web/api-portal-admin/src/lib/utils.ts#L1-L100) -- [LayoutWrapper.tsx](file://portal-web/api-portal-admin/src/components/LayoutWrapper.tsx#L1-L46) - - -## 目录 -1. [引言](#引言) -2. [API通信策略](#api通信策略) -3. [状态管理机制](#状态管理机制) -4. [数据状态管理与缓存](#数据状态管理与缓存) -5. [API调用与上下文使用示例](#api调用与上下文使用示例) - -## 引言 -本文档全面阐述前端应用在 `himarket` 项目中如何通过 `axios` 实现与 `portal-server` 的 RESTful API 通信，并利用 React Context 进行全局加载状态管理。重点分析 `lib/api.ts` 中的请求/响应拦截器、JWT 令牌注入、错误处理机制，以及 `LoadingContext.tsx` 如何协调 UI 加载状态，提升用户体验。 - -## API通信策略 - -### Axios客户端配置 -前端通过 `axios` 封装了一个统一的 API 客户端，集中管理所有与后端 `portal-server` 的通信。该客户端在 `portal-web/api-portal-admin/src/lib/api.ts` 中定义。 - -```typescript -const api: AxiosInstance = axios.create({ - baseURL: import.meta.env.VITE_API_BASE_URL, - timeout: 10000, - headers: { - 'Content-Type': 'application/json', - }, - withCredentials: true, -}) -``` - -**配置说明**： -- **baseURL**: 从环境变量 `VITE_API_BASE_URL` 读取，实现开发、测试、生产环境的灵活切换。 -- **timeout**: 设置 10 秒超时，防止请求无限等待。 -- **headers**: 默认设置 `Content-Type` 为 `application/json`。 -- **withCredentials**: 设置为 `true`，确保跨域请求时能携带 Cookie，用于会话保持。 - -**Section sources** -- [api.ts](file://portal-web/api-portal-admin/src/lib/api.ts#L5-L13) - -### 请求拦截器：JWT令牌注入 -在请求发送前，拦截器会自动从 `localStorage` 中读取 JWT 令牌，并将其添加到请求头的 `Authorization` 字段中。 - -```typescript -api.interceptors.request.use( - (config: InternalAxiosRequestConfig) => { - const token = getToken() - if (token && config.headers) { - config.headers.Authorization = `Bearer ${token}` - } - return config - }, - (error) => { - return Promise.reject(error) - } -) -``` - -**流程分析**： -1. 调用 `getToken()` 函数（定义于 `utils.ts`）从本地存储获取令牌。 -2. 如果令牌存在，则在请求头中设置 `Authorization: Bearer
-
-
- );
-};
-
-export default MyComponent;
-```
\ No newline at end of file
diff --git "a/.qoder/repowiki/zh/content/\345\211\215\347\253\257\346\236\266\346\236\204\344\270\216\347\273\204\344\273\266/\345\205\263\351\224\256UI\347\273\204\344\273\266\350\257\246\350\247\243/AdvancedSearch \347\273\204\344\273\266\350\257\246\350\247\243.md" "b/.qoder/repowiki/zh/content/\345\211\215\347\253\257\346\236\266\346\236\204\344\270\216\347\273\204\344\273\266/\345\205\263\351\224\256UI\347\273\204\344\273\266\350\257\246\350\247\243/AdvancedSearch \347\273\204\344\273\266\350\257\246\350\247\243.md"
deleted file mode 100644
index bde8d4dfa..000000000
--- "a/.qoder/repowiki/zh/content/\345\211\215\347\253\257\346\236\266\346\236\204\344\270\216\347\273\204\344\273\266/\345\205\263\351\224\256UI\347\273\204\344\273\266\350\257\246\350\247\243/AdvancedSearch \347\273\204\344\273\266\350\257\246\350\247\243.md"
+++ /dev/null
@@ -1,271 +0,0 @@
-# AdvancedSearch 组件详解
-
-
-**本文档引用的文件**
-- [AdvancedSearch.tsx](file://portal-web/api-portal-admin/src/components/common/AdvancedSearch.tsx)
-- [ApiProducts.tsx](file://portal-web/api-portal-admin/src/pages/ApiProducts.tsx)
-- [ProductController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/ProductController.java)
-- [DeveloperController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/DeveloperController.java)
-- [PortalDevelopers.tsx](file://portal-web/api-portal-admin/src/components/portal/PortalDevelopers.tsx)
-
-
-## 目录
-1. [简介](#简介)
-2. [项目结构](#项目结构)
-3. [核心组件](#核心组件)
-4. [架构概览](#架构概览)
-5. [详细组件分析](#详细组件分析)
-6. [依赖分析](#依赖分析)
-7. [性能考量](#性能考量)
-8. [故障排除指南](#故障排除指南)
-9. [结论](#结论)
-
-## 简介
-`AdvancedSearch` 是一个可复用的高级搜索组件，用于支持多条件组合搜索功能。该组件广泛应用于 `ApiProducts` 和 `PortalDevelopers` 页面中，为用户提供灵活的字段筛选、操作符选择和值输入交互逻辑。本文档将深入解析其设计机制、与后端 API 的集成方式以及在实际场景中的应用模式。
-
-## 项目结构
-`AdvancedSearch` 组件位于前端项目 `api-portal-admin` 的通用组件目录中，体现了高内聚、低耦合的设计原则。其结构清晰，便于在多个页面间复用。
-
-```mermaid
-graph TB
-subgraph "前端 (portal-web)"
-subgraph "管理后台 (api-portal-admin)"
-AS[AdvancedSearch.tsx]
-AP[ApiProducts.tsx]
-PD[PortalDevelopers.tsx]
-end
-end
-subgraph "后端 (portal-server)"
-PC[ProductController.java]
-DC[DeveloperController.java]
-end
-AS --> AP : "在 ApiProducts 中使用"
-AS --> PD : "在 PortalDevelopers 中使用"
-AP --> PC : "调用 /products 接口"
-PD --> DC : "调用 /developers 接口"
-```
-
-**图示来源**
-- [AdvancedSearch.tsx](file://portal-web/api-portal-admin/src/components/common/AdvancedSearch.tsx)
-- [ApiProducts.tsx](file://portal-web/api-portal-admin/src/pages/ApiProducts.tsx)
-- [PortalDevelopers.tsx](file://portal-web/api-portal-admin/src/components/portal/PortalDevelopers.tsx)
-- [ProductController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/ProductController.java)
-- [DeveloperController.java](file://portal-server/src/main/java/com/alibaba/apiopenplatform/controller/DeveloperController.java)
-
-## 核心组件
-`AdvancedSearch` 组件的核心功能包括：
-- 支持动态配置搜索字段（`searchParamsList`）
-- 提供输入框和下拉选择两种输入类型
-- 支持即时搜索与标签化筛选条件展示
-- 允许清除单个或全部筛选条件
-- 通过回调函数 `onSearch` 和 `onClear` 与父组件通信
-
-该组件使用 React 函数式组件 + Hooks 实现状态管理，结合 Ant Design 的 Select、Input、Tag 等 UI 组件构建交互界面。
-
-**组件来源**
-- [AdvancedSearch.tsx](file://portal-web/api-portal-admin/src/components/common/AdvancedSearch.tsx#L1-L206)
-
-## 架构概览
-`AdvancedSearch` 组件作为前端搜索功能的统一入口，通过标准化接口与业务页面集成，并最终与后端分页查询 API 交互，形成完整的数据过滤闭环。
-
-```mermaid
-sequenceDiagram
-participant UI as "用户界面"
-participant AS as "AdvancedSearch"
-participant Page as "业务页面"
-participant API as "后端API"
-participant DB as "数据库"
-UI->>AS : 选择字段并输入值
-AS->>AS : 更新 activeSearchName 和 activeSearchValue
-UI->>AS : 点击搜索按钮
-AS->>Page : 调用 onSearch(searchName, searchValue)
-Page->>Page : 更新 filters 状态
-Page->>API : 调用 getApiProducts(filters, page, size)
-API->>DB : 执行分页查询
-DB-->>API : 返回结果集
-API-->>Page : 返回 PageResult
-
-
-
-
-
-
-
-
-
-
- )}
- ```
- - **字段**: Region、Access Key、Secret Key。
- - **验证规则**: 所有字段均为必填项。
-
-2. **ADP_AI_GATEWAY 类型**:
- ```tsx
- {['ADP_AI_GATEWAY'].includes(gatewayType) && gatewayList.length === 0 && (
- 认证信息
-
-
-
-
-
-
-
-
-
-
- {authType === 'Seed' && (
-
-
-
- )}
- {authType === 'Header' && (
-
-
- {/* 动态Header列表 */}
-
-
- )}
-
-
- )}
- ```
- - **字段**: 服务地址（需以 `http://` 或 `https://` 开头）、端口（1-65535）、认证方式（下拉选择）。
- - **联动逻辑**: 使用 `Form.useWatch('authType', importForm)` 监听“认证方式”字段的变化，动态显示 `Seed` 输入框或 `Headers` 列表。
- - **动态列表**: `Form.List` 组件用于管理可增删的Header键值对。
-
-#### 第二阶段：网关实例选择
-成功获取网关列表后，进入第二阶段，用户从表格中选择一个实例进行导入。
-```tsx
-{gatewayList.length > 0 && (
- 认证信息
-
- handleGatewaySelect(selectedRows[0]),
- }}
- pagination={gatewayPagination}
- />
-
-)}
-```
-- **数据展示**: 使用 `Table` 组件展示从后端获取的网关列表。
-- **选择机制**: `rowSelection` 配置为单选（radio），用户选择后通过 `handleGatewaySelect` 函数更新 `selectedGateway` 状态。
-- **分页**: 支持分页，`onChange` 回调会重新调用 `fetchGateways` 或 `fetchAdpGateways` 获取新页数据。
-
-**Section sources**
-- [ImportGatewayModal.tsx](file://portal-web/api-portal-admin/src/components/console/ImportGatewayModal.tsx#L100-L325)
-
-### ImportHigressModal 表单结构
-`ImportHigressModal` 是一个更简单的表单，用于导入 Higress 网关。
-```tsx
-
-```
-- **字段**: 网关名称（必填）、描述（可选）、服务地址（必填）、用户名（必填）、密码。
-- **验证规则**: 除描述外，其余字段均有必填验证。
-- **提交**: 使用 `onFinish` 回调处理表单提交。
-
-**Section sources**
-- [ImportHigressModal.tsx](file://portal-web/api-portal-admin/src/components/console/ImportHigressModal.tsx#L1-L109)
-
-## 网关类型选择机制
-
-`GatewayTypeSelector` 组件提供了一个模态框，让用户在导入网关前选择其类型。
-
-```tsx
-
选择网关实例
-|
diff --git a/himarket-bootstrap/pom.xml b/himarket-bootstrap/pom.xml
index e0e20cee9..cc235d6ec 100644
--- a/himarket-bootstrap/pom.xml
+++ b/himarket-bootstrap/pom.xml
@@ -11,12 +11,6 @@
处理三类异常: 1. 业务异常 {@link BusinessException}: 业务异常 2. 参数校验异常 {@link - * MethodArgumentNotValidException}: 请求参数校验不通过 3. 系统异常 {@link Exception}: 非预期的系统异常 + * Handles three types of exceptions: 1. {@link BusinessException}: Business errors 2. {@link + * MethodArgumentNotValidException}: Request validation errors 3. {@link Exception}: Unexpected + * system errors * - * 所有异常都会被转换为统一的响应格式: { "code": "错误码", "message": "错误信息", "data": null } + * All exceptions are converted to unified response: { "code": "error_code", "message":
+ * "error_message", "data": null }
*/
@Slf4j
@RestControllerAdvice
@@ -59,7 +61,7 @@ public ResponseEntity 用于封装接口响应数据为统一格式： { "code": "Success", "message": "操作成功", "data": T }
+ * Wraps API responses into standard format: { "code": "Success", "message": "Operation
+ * successful", "data": T }
*
- * 以下情况不会被包装: 1. 返回值已经是 {@link ResponseEntity} 2. 返回值已经是 {@link Response} 3. ExceptionAdvice
- * 已经处理的异常响应（避免二次包装）
+ * Skips wrapping for: 1. {@link ResponseEntity} 2. {@link Response} 3. Exception responses
+ * handled by ExceptionAdvice (avoid double wrapping)
*/
@RestControllerAdvice
@Slf4j
@@ -49,7 +50,7 @@ public class ResponseAdvice implements ResponseBodyAdvice |