配置 ApiHug 应用侧 UI 模块

配置应用模块中的前端开关、UI 工作目录与运行时承载方式。

本页说明

这一页介绍应用模块如何连接 ApiHug 生成的 Vue UI 模块。

当你已经理解 Vue UI 输出结构，并且需要把应用模块、UI 工程和运行时打通时，请阅读这一页。

适用场景

当你的项目采用前后端分模块结构，同时又希望由 ApiHug 统一协调前端生成、静态资源复制和运行时入口时，就应该配置这一层。

操作步骤

1. 在应用模块开启 Vue 生成

在 {app}/build.gradle 中启用前端生成：

Groovy

hopeStub {
    enableFrontVue = true
}

2. 指定真实 UI 工程目录

创建或更新 {app}/ui.json：

JSON

{
  "projectDir": "../good-app-ui"
}

这个文件告诉应用模块：真实的 UI 工程位于哪里。

3. 理解生成边界

在 ApiHug 工作流中：

proto 定义契约
应用模块消费契约生成结果
UI 模块接收服务层、模型、i18n 和页面辅助代码

所以应用模块是契约输出与前端生成策略之间的桥梁。

4. 执行生成流程

完成上述配置后，可以从应用模块执行：

Terminal

./gradlew.bat {app}:clean stub build -x test -x stubTest

常见生成结果包括：

i18n 语言包
API service stub
request / response model
form / table 支撑类型
公共类型声明

关键文件

文件	作用
`{app}/build.gradle`	打开 Vue 生成开关
`{app}/ui.json`	指向真实 UI 工程
`{ui}/router.json`	配置 UI 模块内部的自动路由生成规则

路由说明

ApiHug 的 UI 工作流默认认为：路由生成发生在 UI 模块内部，而不是后端运行时内部。

一个典型的 router.json 结构如下：

JSON

{
  "items": [
    {
      "moduleDir": "apps/web1"
    },
    {
      "moduleDir": "apps/web2"
    }
  ]
}

当一个 UI 仓库中包含多个独立应用入口时，可以用这种方式分别配置。

运行时说明

运行时通常有两个关键点：

把 UI 的 dist 复制到后端静态资源目录
把非 API 路径转发到 SPA 的 index.html

静态资源复制示例：

Groovy

tasks.register('copyUIResources', Copy) {
    dependsOn project(':good-app-ui').tasks.named('build')
    from project(':good-app-ui').layout.projectDirectory.dir('dist')
    into "${layout.buildDirectory.get()}/resources/main/static"
}

tasks.named('processResources') {
    dependsOn 'copyUIResources'
}

SPA 转发规则示例：

Java

SpaPathChecker DEFAULT =
      path ->
          !path.startsWith("/api")
              && !path.startsWith("/management")
              && !path.startsWith("/v3/api-docs")
              && !path.startsWith("/hope/meta")
              && !path.startsWith("/h2-console")
              && !path.contains(".")
              && path.matches("/(.*)");

这样可以保证：

/api/... 继续走后端接口
普通页面路由继续走前端 SPA
静态文件路径仍然按资源方式返回

结果

完成这一步后，应用模块会成为 ApiHug 契约生成与真实 Vue UI 工程之间的稳定衔接点，而不是靠人工临时拼接前后端流程。