本文引用的文件
本文面向需要在 ai-server、ai-gateway 和 ai-electron 三个子项目中同时扩展功能的开发者,给出“从后端模块到网关暴露、再到 Electron 前端页面”的完整实操指南。重点包括:
本项目采用多模块仓库组织:
module/* 划分业务域。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 接口"]
图表来源
章节来源
参考现有 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。已有示例可以参考系统控制器的注释说明:它强调必须是 @RestController,否则返回实体会被当成视图名转发,最终出现 404,并影响健康检查和登录流程。
章节来源
当前启动类使用 @SpringBootApplication,并且存在多处 @Mapper 注解。根据 Mapper 注释,本项目未使用 @MapperScan,而是依赖每个 Mapper 接口上的 @Mapper 注解进行注册。因此新增 Mapper 时,必须显式添加 @Mapper。
章节来源
典型三层结构如下:
common.model.<domain>.entity。BaseMapper<Entity>,标注 @Mapper。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 : "操作实体"
图表来源
MyBatis-Plus 的实体别名包、Mapper XML 位置和日志实现集中在 application.yaml 的 mybatis-plus 段中。关键约定:
type-aliases-package 指向 com.zsjz.ai.common.model.*.entity。mapper-locations 指向 classpath*:mappers/**/*.xml。MybatisEnumTypeHandler。新增实体时,只要实体位于 common.model.<domain>.entity 且命名不与其它域重复,即可复用该别名包;如果后续出现实体重名,需关闭全局别名或使用全限定名。
章节来源
现有网关管理接口集中在 /gateway/admin/**,由 AdminController 提供,例如服务创建、节点管理、路由绑定、重载等。新增管理接口时建议遵循:
admin 包下新增或扩展现有 Controller。@GetMapping、@PostMapping、@PutMapping、@DeleteMapping 定义 REST 风格接口。boundedElastic,避免阻塞 Netty 事件循环。ApiResult 返回结果。如有自定义异常,抛出后由 @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)"
图表来源
如果需要拦截某类请求,可新增实现 WebFilter 的组件,并设置合适的 @Order。现有 AdminAuthWebFilter 展示了典型模式:
ServerWebExchange.attributes。JsonResponses.write 返回错误。新增过滤器时应注意:
章节来源
网关配置通过 GatewayProperties 加载,支持:
gateway.admin.enabled:是否启用管理接口。gateway.admin.ip-whitelist:IP 白名单,支持单 IP 和 CIDR。gateway.health-check:健康检查间隔、超时、失败阈值。gateway.cors:网关侧跨域开关。gateway.services:首次启动播种的服务定义。gateway.nodes:节点定义。新增配置项时,应在 GatewayProperties 中新增嵌套类或字段,并在 YAML 中提供默认值,同时在文档和测试中说明其作用域。
章节来源
前端 Vue 应用中,页面通常以 .vue 文件形式存在,并通过路由注册。新增页面时建议:
ai-electron/frontend/src/<domain>/views/<page>.vue。虽然本仓库前端路由注册细节分布在多个文件中,但整体模式是:路由表驱动菜单,菜单驱动页面导航。新增页面时应确保路由、菜单、权限三者一致。
Electron 渲染进程通过 window.electron.ipcRenderer 与 main 进程通信。现有 bridge 暴露了 window.electron,其中包含 ipcRenderer。新增 IPC 接口时,应同时修改三部分:
ipcRenderer。前端调用方:使用 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"]
图表来源
章节来源
假设需要新增一个“查询外部表”的功能:
外部表结构可以参照 external_tables.sql。该脚本定义了多个外部数据表,例如出入境证件信息、机动车信息、违法犯罪人员信息等,字段多为字符串类型,并包含 fileId、sheetId 等元数据字段。
新增外部表时建议:
sql/query_external_table_init.sql。DROP TABLE IF EXISTS 配合 CREATE TABLE,保证脚本可重复执行。章节来源
在 common.model.external.entity 下新增实体类,字段与 SQL 表结构对齐。建议使用 MyBatis-Plus 提供的注解标注主键、表名和字段映射。
新增 Mapper 接口,继承 BaseMapper<ExternalTableEntity>,并标注 @Mapper。如需复杂查询,可在对应 mappers/**/*.xml 中编写 SQL。
新增 Service,继承 ServiceImpl<ExternalTableMapper, ExternalTableEntity>,并在方法中封装查询逻辑,例如分页、条件构建、空值处理。
新增 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: "统一结果包装"
图表来源
新建 Vue 页面后:
如果页面需要调用本地能力,例如选择目录、读取二进制文件,可通过 window.electron.ipcRenderer.invoke 调用 main 进程控制器方法。
章节来源
/v2/external/query。application.yaml 或对应环境配置文件,新增配置项需提供默认值。GatewayProperties,新增字段需在 YAML 中体现。/gateway/admin/** 接口分别测试白名单、未登录、非管理员等场景。章节来源
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"]
图表来源
章节来源
@RestController。@Mapper。mapper-locations 指向正确的 XML 路径。gateway.admin.enabled 是否开启。x-token。window.electron。invoke 而非 send。window.electron,需要降级处理。章节来源
添加新模块和新功能的核心思路是:先明确职责边界,再按 controller、service、mapper、entity 分层实现;通过 MyBatis-Plus 和 YAML 配置完成数据库装配;通过网关管理接口暴露管理能力;通过前端路由和 IPC bridge 完成用户交互。实际开发中应重视参数校验、错误处理、日志记录和测试覆盖,以保证新功能稳定上线。