ApiHug home page
ApiHug
  1. Milestone
  2. Milestone 2.0.0-RELEASE

2.0.0-RELEASE 是 ApiHug 的一个重要里程碑版本，引入了多项破坏性变更，旨在构建面向下一代、大语言模型（LLM）友好的 API 规范与工具生态。

😆 快速入门指南：

  1. ApiHug101 - 哔哩哔哩
  2. ApiHug101 - YouTube

ApiHug - API 设计智能助手（IntelliJ 插件）

SDK [2.0.0-RELEASE] - 2025-12-10

  • 将 JavaPoet 从 Square 迁移至 Palantir 分支版本
  • 使用 Square 的 Wire 引擎替代 Google 的 Protobuf 解析器
  • 初步支持 Protobuf Schema Catalog 功能

插件 [1.0.0] - 2025-12-10

  • 升级至 SDK 2.0.0-RELEASE
  • 移除旧版 Protocol Buffer 插件依赖
  • 采用轻量级、纯 Wire 驱动的 Protobuf 编译器
  • 移除 AI 相关组件，聚焦核心功能
  • 元数据以人类可读的文本格式缓存，提升 LLM 友好性
  • 多项 Bug 修复

⚠️⚠️⚠️ 请勿升级至 Spring Boot 4.0 及以上版本（截至 2025 年 12 月） —— 当前 SDK 尚未兼容 Spring Boot 4.0 引入的破坏性变更。⚠️⚠️⚠️

强行升级可能导致大量难以排查的构建或运行时错误，严重影响开发效率。

如需了解 Spring Boot 4.0 中的具体破坏性变更，请参考官方迁移指南：

Spring Boot 4.0 迁移指南

新特性亮点

  1. 多态支持：通过 Protocol Buffers 的 oneof 语法实现。
  2. 精简 OpenAPI 输出：利用 OAS allOf 展开并简化响应包装结构。
  3. 极速轻量编译器：显著提升生成与迭代效率。
  4. 丰富的元数据导出能力：为高级工具链和集成提供支撑。
  5. LLM 就绪的规范格式：为未来规范驱动开发（Specification-Driven Development）奠定基础（待完善）。

升级步骤

请参考 apihug-demo/libs.versions.toml

  1. 升级 ApiHug SDK：在 {PROJECT_ROOT}/gradle/libs.versions.toml 中将 apihug = "1.0.0-RELEASE" 更新为 2.0.0-RELEASE 或更高版本。
  2. 升级 IntelliJ IDEA 插件 至 1.0.0+：ApiHug - API 设计智能助手
  3. 确保 Spring Boot 版本 < 4.0，推荐使用 3.8.x 系列，因 Spring Boot 4.0 存在破坏性变更。
  4. 更新构建命令：轻量编译器现已在构建前自动运行，无需再显式指定 wire 或 stub 命令。
  5. 项目结构变更如下：

Wire 模块

生成目录与手写目录

  • 生成目录（_*_）：凡是名称被前后下划线包裹的目录（例如 _api_），均由 apihug 工具生成，属于只读区域。
  • 请勿在这些目录中手工修改代码。
  • 生成过程可能会覆盖其中的文件，如需修改应通过调整生成配置或上游契约来完成。
  • 手写目录：java、proto 等普通目录用于存放开发者手写的源码与 Schema。
  • Java 应用代码与测试应放在 java 目录下。
  • Protocol Buffer 定义（.proto 文件）应放在 proto 目录下。

生产代码目录（src/main）

生产环境相关源码布局如下：

src/main/
  java/        → 核心应用逻辑（手写 Java 代码）
  _api_/       → 基于 Wire/契约生成的 Java 类（生产代码，只读）
  proto/       → `.proto` Schema 文件（作为资源参与代码生成）

Gradle 的配置约定：

  • src/main/_api_ 会被加入 sourceSets.main.java.srcDirs，作为主 Java 源的一部分参与编译。
  • src/main/proto 会被加入 sourceSets.main.resources.srcDir，作为资源输出，方便生成器或工具在构建时读取 .proto 文件。

测试代码目录（src/test）

测试代码沿用相同的目录约定：

src/test/
  java/        → 常规单元测试与集成测试（JUnit 等）
  _api_/       → API 守卫/契约测试，作为 `test` 任务的一部分编译与执行

src/test/_api_ 会被加入 sourceSets.test.java.srcDirs，与标准测试源码一起编译和运行。

Kola 契约测试目录（src/test-kola）

Kola 测试通过单独的 Source Set 与 Task，支持契约式的端到端测试：

src/
  main/
    java/          // 生产环境 Java 源码
    resources/     // 生产环境资源
  test/
    java/          // 常规单元/集成测试（JUnit 等）
    resources/     // 常规测试资源
  test-kola/
    java/          // 自动生成的 Java 测试类（编译并执行）
    groovy/        // Groovy DSL 脚本（作为资源，不参与编译）
    resources/     // 额外测试资源（契约、样例数据、配置等）

Gradle 中定义了 testKola Source Set：

  • src/test-kola/java：用于存放生成的 Java 测试类。
  • src/test-kola/resources 与 src/test-kola/groovy：均注册为资源目录。
  • groovy 下的 DSL 文件不会被编译，而是由代码生成器或测试工具在构建过程中读取。
  • testKola 的类路径包含 main 与 test 两个 Source Set 的输出，方便复用公共工具类与基础测试类。

同时定义了专用的 testKola Gradle 任务，仅运行 Kola 生成的测试（基于 JUnit Platform）；默认的 test 任务同样启用 JUnit Platform，以保持一致性。

使用建议

  • 不要直接修改 _api_ 目录中的生成代码；如需变更，请调整 proto/契约并重新生成。
  • 业务逻辑建议集中在 src/main/java，测试集中在 src/test/java，保持结构清晰。
  • 将契约与 Schema 放在 src/main/proto，Kola DSL 放在 src/test-kola/groovy，避免不同类型的文件混放。
  • 常规单元/集成测试使用 test 任务，契约式端到端验证使用 testKola 任务，有利于分层执行与排查问题。

Stub 模块

生成目录与手写目录

  • 生成目录（_*_）：凡是名称被前后下划线包裹的目录（例如 _api_、_mcp_、_domain_、_cloud_），均由 apihug 工具生成，属于只读区域。
  • 请勿在这些目录中手工修改代码。
  • 代码会在生成过程中被覆盖，只能通过调整生成配置/输入来间接修改。
  • 手写目录：java、trait 等普通目录用于存放开发者手写的源码。
  • 业务逻辑、服务、控制器以及自定义的 trait 类应放在这些目录中。

生产代码目录（src/main）

生产环境相关源码按职责拆分到多个目录中：

src/main/
  java/        → 手写业务逻辑、服务、控制器等
  _api_/       → 生成的 DTO 与 REST 接口（apihug 生成，只读）
  trait/       → 可由开发者自定义和复用的 trait/mixin 类
  _mcp_/       → 生成的微服务契约或协议代码（只读）
  _domain_/    → 生成的核心领域模型、聚合、值对象等（只读）
  _cloud_/     → 生成的云端/集成相关 stub、端点或适配器（只读）

虽然物理上拆分在多个子目录中，但这些目录共同组成同一个生产模块。Gradle 会通过 sourceSets.main.java.srcDirs 将上述目录全部加入编译路径，最终打包为同一个 JAR。

测试代码目录（src/test）

测试代码在结构上尽量镜像生产目录，方便按领域组织测试用例：

src/test/
  java/        → 核心逻辑的单元测试与集成测试
  _api_/       → API 层的契约/守卫测试（通常依赖生成的 DTO）
  trait/       → trait/mixin 行为相关的测试
  _mcp_/       → 协议契约的校验测试
  _domain_/    → 领域模型不变式与行为测试
  _cloud_/     → 云端/集成契约测试及相关生成 stub

上述测试目录均通过 sourceSets.test.java.srcDirs 注册到 Gradle 中，作为标准 test Source Set 的一部分， 由默认的 test 任务统一编译和执行，并共享同一套（main + test 输出以及测试依赖）类路径。

使用建议

  • 不要直接修改生成目录（_api_、_mcp_、_domain_、_cloud_）中的代码，如需变更，请调整契约/模型或生成配置并重新生成。
  • 业务与自定义逻辑尽量集中在 java 与 trait，以避免在重新生成时被覆盖。
  • 测试代码按生产目录进行“就近”组织，在 src/test 下选择对应的子目录，保持结构一致性，便于维护和定位。

Proto 变更

// 旧路径
import "extend/version.proto";
import "swagger/annotations.proto";
import "extend/domain.proto";

// 新路径
import "apihug/protobuf/extend/version.proto";
import "apihug/protobuf/swagger/annotations.proto";
import "apihug/protobuf/extend/domain.proto";

语法增强

  1. 支持通过 oneof 实现多态（OpenAPI 映射为 allOf）
  2. 支持流式定义（语义等同于 gRPC，服务端暂未实现）：包括定义与实现
  3. 支持上传/下载接口定义（服务端暂未实现）
  4. 优化单响应类型定义（非引用类型）
  5. 支持复杂类型定义
  6. 支持 Schema 定义
  7. 支持 internal / external / hide 等 API 可见性标记

Gradle 配置

  1. wire 项目支持 protoImport 语法，用于引入第三方 Protobuf 依赖。
  2. stub 项目应使用 wireImport 语法引入 Wire 模块依赖；若误用 implementation，虽无语法错误，但会导致 stub 命令生成内容为空。