ApiHug API 设计助手 FAQ

Proto 模块编译问题

IDEA plugin

Plugin Release

JVM 版本兼容性对 Proto 模块的顺利编译至关重要。

涉及两个 JVM 版本:

项目中 gradle/java.gradle 文件定义的工具链版本。
构建环境的 JVM 版本（即 Gradle 运行时所使用的版本）。

这两个版本不一致时，可能导致 Protobuf Wire 编译器静默失败。

为避免问题，请遵循以下原则:

确保 Proto 模块的目标编译版本 <= 构建环境的 JVM 版本。

Java 版本对应关系:

项目工具链版本	编译环境(Gradle)	Proto 模块版本要求
21	21	默认或 `<=21`
21	17	必须设置为 `<=17`
17	21	默认或 `<=21`

项目工具链java 版本{project-root}/gradle/java.gradle:

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

Gradle JVM 版本, 在启动编译时会输出:

Java version: 19.0.1
Gradle version: 8.14.3
Current dir: /user/home/project/myproject
Spring Boot version: 3.5.5
Spring Dependency version: 1.1.7
Spring Ai version: 1.0.0
Spring Cloud version: 2024.0.1
ApiHug version: 1.4.3-M8
All Modules: [project ':sample-proto',':sample-app']

当面每个模块都可以在自己的 build.gradle 覆盖新的 java 版本。

ProtoBuf

Proto 文件无法识别

目前 IDE 支持的 Proto buffer 插件主要有两种：

IDE 自带的，供应商为 JetBrains s.r.o. ✅✅✅
第三方 HIGAN 插件 ❌❌❌

这两个插件存在冲突，只能启用其中一个。⚠️

ApiHug Plugin 依赖于 IDE 自带的 Proto Editor 插件进行 AST 语法树解析，因此必须启用 JetBrains s.r.o. ✅ Proto 插件：

Proto 文件无法导入，无法识别 proto import

ApiHug SDK proto 导入 import "swagger/annotations.proto"; 时报错：

ApiHug SDK proto import import "swagger/annotations.proto"; 失败：

01: 编译项目, compile the project (通过 markdown 或 gradle 任务)

02: 编译完成后，查看 proto 项目的 build 缓存，after compile success, check the project proto build cache:

{PROJECT}/{PROTO-MODULE}/build/extracted-include-protos:

03：如果仍未成功导入，手动配置 proto import；if still not import then please add path manually：

打开 Settings 面板
找到 Protocol Buffers
取消勾选 Configure Automatically
将 {PROJECT}/{PROTO-MODULE}/build/extracted-include-protos 添加到 Import Paths 中：

从 Plugin 0.7.6 版本起，插件已内置这些预定义的 proto 文件。

最终所有 import 语句都应变为绿色，Eventually all the import should turn green!

⚠️ 有时官方的 proto editor 可能会崩溃，请留意崩溃提示！

若即使重启 IDEA 问题依旧存在，请向我们报告：report issue

Gradle

无法识别 Gradle 项目

IDE 应弹出 Load Gradle Project 提示，若通知被关闭，请打开 Notification 面板手动触发。

IDE should pop up a notification: Load Gradle Project，if notification pop up was forbidden, then please open the Notification panel to load it manually!