添加新模块与新功能.md 21 KB

添加新模块与新功能

本文引用的文件

  • App.java
  • application.yaml
  • SystemController.java
  • LunarService.java
  • LunarMapper.java
  • AdminController.java
  • AdminAuthWebFilter.java
  • GatewayProperties.java
  • IpWhitelist.java
  • bridge.ts
  • main.ts
  • gateway.sql
  • external_tables.sql

目录

  1. 引言
  2. 项目结构概览
  3. 在 ai-server 中添加 Spring Boot 业务模块
  4. 通过 MyBatis-Plus 访问数据库
  5. 在 ai-gateway 中新增网关管理接口或过滤器
  6. 在前端 App.vue 与路由中注册页面和 IPC 接口
  7. 完整示例:查询外部表后端模块 + 前端页面 + SQL 初始化脚本
  8. API 版本兼容、配置项扩展、日志记录与测试建议
  9. 依赖关系分析
  10. 常见问题排查
  11. 结语

引言

本文面向需要在 ai-server、ai-gateway 和 ai-electron 三个子项目中同时扩展功能的开发者,给出“从后端模块到网关暴露、再到 Electron 前端页面”的完整实操指南。重点包括:

  • 如何在 ai-server 中添加 controller、service、mapper、entity。
  • 如何让 Spring Boot 扫描并注册这些组件。
  • 如何使用 MyBatis-Plus 读写数据库。
  • 如何在 ai-gateway 中新增管理接口或过滤逻辑。
  • 如何在前端 App.vue 或路由中注册页面,并通过 preload bridge 调用 Electron main 进程能力。
  • 如何通过 SQL 脚本初始化外部表数据。
  • 如何兼顾 API 版本兼容、配置扩展、日志记录和测试。

项目结构概览

本项目采用多模块仓库组织:

  • ai-server:Spring Boot 后端服务,使用 MyBatis-Plus 访问数据库,按 module/* 划分业务域。
  • ai-gateway:基于 Spring WebFlux 的网关,负责用户粘性路由、节点健康检查和管理接口。
  • ai-electron:Electron 桌面应用,包含 Electron main、preload bridge、Vue 前端。
  • sql:数据库初始化脚本,包括平台表、网关表和外部数据表等。

    graph TB
    Client["浏览器或桌面客户端"] --> Gateway["ai-gateway<br/>网关层"]
    Gateway --> Server["ai-server<br/>业务后端"]
    Server --> Database["PostgreSQL / DuckDB<br/>外部数据源"]
    Client --> Electron["ai-electron<br/>Electron 前端"]
    Electron --> Main["Electron main.ts"]
    Main --> Bridge["preload bridge.ts"]
    Electron --> Api["后端 REST 接口"]
    

图表来源

  • App.java:23-49
  • AdminController.java:18-153
  • main.ts:1-19
  • bridge.ts:1-10

章节来源

  • App.java:23-49
  • application.yaml:185-193
  • GatewayProperties.java:1-81
  • main.ts:1-19

在 ai-server 中添加 Spring Boot 业务模块

推荐目录约定

参考现有 plat、agent、trans、track 等模块,建议在 ai-server/src/main/java/com/zsjz/ai/module/<domain> 下新增模块,并按以下层次组织:

  • controller:HTTP 控制器。
  • service:业务逻辑。
  • service/impl:可选的实现类;若直接继承 ServiceImpl,可省略实现类。
  • mapper:MyBatis-Plus Mapper 接口。
  • entity:实体类(通常放在 common.model.<domain>.entity)。
  • dto / vo:请求参数和响应视图对象。

控制器写法要点

  • 使用 @RestController。
  • 使用 @RequestMapping 定义路径前缀,例如 /sys、/gateway/admin 等。
  • 返回统一结果包装类型(如 Result 或 ApiResult),避免普通 @Controller 被当成视图名导致 404。
  • 对耗时操作应放在 service 层,必要时使用异步线程池或响应式封装。

已有示例可以参考系统控制器的注释说明:它强调必须是 @RestController,否则返回实体会被当成视图名转发,最终出现 404,并影响健康检查和登录流程。

章节来源

  • SystemController.java:1-200

组件自动发现机制

当前启动类使用 @SpringBootApplication,并且存在多处 @Mapper 注解。根据 Mapper 注释,本项目未使用 @MapperScan,而是依赖每个 Mapper 接口上的 @Mapper 注解进行注册。因此新增 Mapper 时,必须显式添加 @Mapper。

章节来源

  • App.java:23-49
  • LunarMapper.java:1-9

通过 MyBatis-Plus 访问数据库

实体、Mapper、Service 的标准组合

典型三层结构如下:

  1. Entity:对应数据库表字段,放在 common.model.<domain>.entity。
  2. Mapper:继承 BaseMapper<Entity>,标注 @Mapper。
  3. Service:继承 ServiceImpl<Mapper, Entity>,标注 @Service。

已有 LunarService 和 LunarMapper 是极简实现:Service 只继承通用实现,Mapper 只继承 BaseMapper,适合快速 CRUD。

classDiagram
    class LunarEntity {
        +id
        +name
        +字段映射
    }

    class LunarMapper {
        +BaseMapper~LunarEntity~
    }

    class LunarService {
        +ServiceImpl~LunarMapper, LunarEntity~
    }

    LunarService --> LunarMapper : "继承 ServiceImpl"
    LunarMapper --> LunarEntity : "操作实体"

图表来源

  • LunarService.java:1-10
  • LunarMapper.java:1-9

MyBatis-Plus 装配位置

MyBatis-Plus 的实体别名包、Mapper XML 位置和日志实现集中在 application.yaml 的 mybatis-plus 段中。关键约定:

  • type-aliases-package 指向 com.zsjz.ai.common.model.*.entity。
  • mapper-locations 指向 classpath*:mappers/**/*.xml。
  • 枚举处理器使用 MybatisEnumTypeHandler。
  • 日志实现使用 Slf4j。

新增实体时,只要实体位于 common.model.<domain>.entity 且命名不与其它域重复,即可复用该别名包;如果后续出现实体重名,需关闭全局别名或使用全限定名。

章节来源

  • application.yaml:185-193

在 ai-gateway 中新增网关管理接口或过滤器

新增管理接口的步骤

现有网关管理接口集中在 /gateway/admin/**,由 AdminController 提供,例如服务创建、节点管理、路由绑定、重载等。新增管理接口时建议遵循:

  1. 在 admin 包下新增或扩展现有 Controller。
  2. 使用 @GetMapping、@PostMapping、@PutMapping、@DeleteMapping 定义 REST 风格接口。
  3. 阻塞型 JDBC 操作放入 boundedElastic,避免阻塞 Netty 事件循环。
  4. 统一使用 ApiResult 返回结果。
  5. 如有自定义异常,抛出后由 @ExceptionHandler 处理。

    sequenceDiagram
    participant Admin as "管理员客户端"
    participant Filter as "AdminAuthWebFilter"
    participant Controller as "AdminController"
    participant Service as "AdminService"
    
    Admin->>Filter: "GET /gateway/admin/services"
    Filter->>Filter: "校验开关、IP白名单、x-token、管理员权限"
    Filter-->>Admin: "拒绝或放行"
    Filter->>Controller: "转发请求"
    Controller->>Service: "查询服务列表"
    Service-->>Controller: "返回数据"
    Controller-->>Admin: "ApiResult.ok(data)"
    

图表来源

  • AdminAuthWebFilter.java:1-90
  • AdminController.java:18-153

新增过滤器的步骤

如果需要拦截某类请求,可新增实现 WebFilter 的组件,并设置合适的 @Order。现有 AdminAuthWebFilter 展示了典型模式:

  • 仅对特定路径前缀生效。
  • 支持开关控制。
  • 支持 IP 白名单。
  • 解析 token 并校验用户权限。
  • 将上下文信息写入 ServerWebExchange.attributes。
  • 失败时通过 JsonResponses.write 返回错误。

新增过滤器时应注意:

  • 不要覆盖已有高优先级过滤器。
  • 避免同步阻塞主事件循环。
  • 对敏感信息做脱敏或限制日志输出。

章节来源

  • AdminAuthWebFilter.java:1-90
  • IpWhitelist.java:1-87

网关配置扩展

网关配置通过 GatewayProperties 加载,支持:

  • gateway.admin.enabled:是否启用管理接口。
  • gateway.admin.ip-whitelist:IP 白名单,支持单 IP 和 CIDR。
  • gateway.health-check:健康检查间隔、超时、失败阈值。
  • gateway.cors:网关侧跨域开关。
  • gateway.services:首次启动播种的服务定义。
  • gateway.nodes:节点定义。

新增配置项时,应在 GatewayProperties 中新增嵌套类或字段,并在 YAML 中提供默认值,同时在文档和测试中说明其作用域。

章节来源

  • GatewayProperties.java:1-81

在前端 App.vue 与路由中注册页面和 IPC 接口

注册页面

前端 Vue 应用中,页面通常以 .vue 文件形式存在,并通过路由注册。新增页面时建议:

  1. 在业务目录下新建页面组件,例如 ai-electron/frontend/src/<domain>/views/<page>.vue。
  2. 在路由配置中注册该页面,设置路由名称、路径、标题和菜单标识。
  3. 如果页面需要菜单展示,还需在菜单配置中补充对应条目。
  4. 如果页面依赖权限,应在权限或角色配置中增加对应权限点。

虽然本仓库前端路由注册细节分布在多个文件中,但整体模式是:路由表驱动菜单,菜单驱动页面导航。新增页面时应确保路由、菜单、权限三者一致。

新增 IPC 接口

Electron 渲染进程通过 window.electron.ipcRenderer 与 main 进程通信。现有 bridge 暴露了 window.electron,其中包含 ipcRenderer。新增 IPC 接口时,应同时修改三部分:

  1. preload bridge:确保渲染进程能拿到 ipcRenderer。
  2. main 进程控制器或服务:监听对应 channel,执行业务逻辑并返回结果。
  3. 前端调用方:使用 ipcRenderer.invoke(channel, params) 调用。

    flowchart TD
    Start["前端发起 IPC 调用"] --> Renderer["渲染进程 ipcRenderer.invoke"]
    Renderer --> Bridge["preload bridge.ts<br/>window.electron.ipcRenderer"]
    Bridge --> Main["Electron main.ts<br/>控制器或服务方法"]
    Main --> Result["返回 Promise 结果"]
    Result --> Renderer
    Renderer --> Page["Vue 页面更新 UI"]
    

图表来源

  • bridge.ts:1-10
  • main.ts:1-19

章节来源

  • bridge.ts:1-10
  • main.ts:1-19

完整示例:查询外部表后端模块 + 前端页面 + SQL 初始化脚本

场景说明

假设需要新增一个“查询外部表”的功能:

  • 后端提供 REST 接口,接收查询条件。
  • 后端通过 MyBatis-Plus 或自定义 SQL 查询外部数据表。
  • 前端新增页面,提供表单输入和表格展示。
  • SQL 脚本初始化外部表结构。

第一步:SQL 初始化脚本

外部表结构可以参照 external_tables.sql。该脚本定义了多个外部数据表,例如出入境证件信息、机动车信息、违法犯罪人员信息等,字段多为字符串类型,并包含 fileId、sheetId 等元数据字段。

新增外部表时建议:

  1. 新建独立 SQL 文件,例如 sql/query_external_table_init.sql。
  2. 使用 DROP TABLE IF EXISTS 配合 CREATE TABLE,保证脚本可重复执行。
  3. 为常用查询字段建立索引。
  4. 在部署脚本中纳入该 SQL 文件。

章节来源

  • external_tables.sql:1-200

第二步:后端模块

实体

在 common.model.external.entity 下新增实体类,字段与 SQL 表结构对齐。建议使用 MyBatis-Plus 提供的注解标注主键、表名和字段映射。

Mapper

新增 Mapper 接口,继承 BaseMapper<ExternalTableEntity>,并标注 @Mapper。如需复杂查询,可在对应 mappers/**/*.xml 中编写 SQL。

Service

新增 Service,继承 ServiceImpl<ExternalTableMapper, ExternalTableEntity>,并在方法中封装查询逻辑,例如分页、条件构建、空值处理。

Controller

新增 Controller,标注 @RestController 和 @RequestMapping,对外暴露查询接口。返回统一结果包装,并对非法参数进行校验。

sequenceDiagram
    participant Frontend as "前端页面"
    participant Controller as "ExternalTableController"
    participant Service as "ExternalTableService"
    participant Mapper as "ExternalTableMapper"
    participant DB as "数据库"

    Frontend->>Controller: "POST /external/query"
    Controller->>Service: "封装查询参数"
    Service->>Mapper: "执行分页查询"
    Mapper->>DB: "SELECT ... FROM external_table"
    DB-->>Mapper: "结果集"
    Mapper-->>Service: "实体列表"
    Service-->>Controller: "分页结果"
    Controller-->>Frontend: "统一结果包装"

图表来源

  • SystemController.java:1-200
  • LunarService.java:1-10
  • LunarMapper.java:1-9

第三步:前端页面

新建 Vue 页面后:

  1. 在路由中注册页面路径。
  2. 在菜单配置中注册菜单项。
  3. 在页面中调用后端 REST 接口或 IPC 接口。
  4. 使用表格组件展示查询结果。
  5. 处理加载状态、错误状态和分页。

如果页面需要调用本地能力,例如选择目录、读取二进制文件,可通过 window.electron.ipcRenderer.invoke 调用 main 进程控制器方法。

章节来源

  • bridge.ts:1-10

API 版本兼容、配置项扩展、日志记录与测试建议

API 版本兼容

  • 对于向后兼容的新增字段,应允许旧客户端忽略未知字段。
  • 对于可能破坏行为的变更,优先使用新版本路径或版本号,例如 /v2/external/query。
  • 对必填参数增加校验,避免旧客户端传入缺失字段导致异常。
  • 对返回结构变化保留兼容字段,逐步废弃旧字段。

配置项扩展

  • 后端配置放在 application.yaml 或对应环境配置文件,新增配置项需提供默认值。
  • 网关配置放在 GatewayProperties,新增字段需在 YAML 中体现。
  • 对敏感配置(数据库密码、密钥)不要硬编码,使用环境变量或外部配置中心。
  • 对开关型配置增加日志输出,便于运维排查。

日志记录

  • 后端使用 SLF4J,在入口、关键分支、异常处记录日志。
  • 网关过滤器中对鉴权失败、IP 拒绝、token 失效等场景记录警告日志。
  • 前端对 IPC 调用失败和网络异常进行提示,并记录必要上下文。
  • 避免记录敏感信息,如密码、身份证号、完整令牌等。

测试建议

  • 单元测试:对 Service 层核心逻辑编写单元测试。
  • 集成测试:对 Controller 接口编写接口测试,验证参数校验和返回结构。
  • 网关测试:对 /gateway/admin/** 接口分别测试白名单、未登录、非管理员等场景。
  • 前端测试:对页面加载、表单提交、表格分页进行基础测试。
  • SQL 测试:在测试库执行初始化脚本,验证建表、索引和数据导入。

章节来源

  • AdminAuthWebFilter.java:1-90
  • application.yaml:185-193

依赖关系分析

后端模块依赖

  • Controller 依赖 Service。
  • Service 依赖 Mapper。
  • Mapper 依赖数据库。
  • 所有组件由 Spring 容器管理。

网关依赖

  • AdminController 依赖 AdminService。
  • AdminAuthWebFilter 依赖 GatewayProperties、TokenResolver、UserRouteRepository。
  • IpWhitelist 提供 IP/CIDR 匹配工具。

前端依赖

  • 页面组件依赖路由和菜单。
  • IPC 调用依赖 preload bridge。
  • main 进程通过控制器或服务处理 IPC 消息。

    graph LR
    Controller["Controller"] --> Service["Service"]
    Service --> Mapper["Mapper"]
    Mapper --> Database["数据库"]
    AdminController["网关 AdminController"] --> AdminService["AdminService"]
    AdminAuthFilter["AdminAuthWebFilter"] --> Properties["GatewayProperties"]
    AdminAuthFilter --> Whitelist["IpWhitelist"]
    Page["前端页面"] --> Route["路由"]
    Page --> Ipc["IPC 调用"]
    Ipc --> Bridge["bridge.ts"]
    Bridge --> MainProcess["main.ts"]
    

图表来源

  • SystemController.java:1-200
  • LunarService.java:1-10
  • LunarMapper.java:1-9
  • AdminController.java:18-153
  • AdminAuthWebFilter.java:1-90
  • GatewayProperties.java:1-81
  • IpWhitelist.java:1-87
  • bridge.ts:1-10
  • main.ts:1-19

章节来源

  • application.yaml:185-193
  • gateway.sql:1-107

常见问题排查

后端返回 404

  • 确认 Controller 使用了 @RestController。
  • 确认路径未被网关或其他中间件拦截。
  • 确认 Mapper 已标注 @Mapper。
  • 确认 MyBatis-Plus 的 mapper-locations 指向正确的 XML 路径。

管理接口 401 或 403

  • 检查 gateway.admin.enabled 是否开启。
  • 检查来源 IP 是否在白名单。
  • 检查请求头是否携带有效 x-token。
  • 检查用户是否为管理员且状态正常。

前端无法调用 IPC

  • 确认 preload bridge 已暴露 window.electron。
  • 确认 main 进程监听了对应 channel。
  • 确认前端使用的是 invoke 而非 send。
  • 在浏览器模式下,渲染进程可能没有 window.electron,需要降级处理。

SQL 初始化失败

  • 确认脚本可重复执行。
  • 确认目标库权限正确。
  • 确认外键约束和索引创建顺序。
  • 确认字符集和排序规则符合预期。

章节来源

  • SystemController.java:1-200
  • AdminAuthWebFilter.java:1-90
  • bridge.ts:1-10
  • gateway.sql:1-107

结语

添加新模块和新功能的核心思路是:先明确职责边界,再按 controller、service、mapper、entity 分层实现;通过 MyBatis-Plus 和 YAML 配置完成数据库装配;通过网关管理接口暴露管理能力;通过前端路由和 IPC bridge 完成用户交互。实际开发中应重视参数校验、错误处理、日志记录和测试覆盖,以保证新功能稳定上线。