Milestone 2.0.0-RELEASE

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

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 迁移指南

新特性亮点

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

升级步骤

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

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

模块

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

生产代码目录

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

{module}/
├── src/main/
│   ├── proto/                         → Proto 定义（手写）
│   │   └── {package_name}/
│   │       ├── api/                   → API 定义
│   │       ├── domain/                → 领域实体
│   │       └── infra/                 → 基础设施（枚举、错误）
│   ├── java/                          → 手写业务
│   ├── trait/                         → Repository扩展
│   └── resources/
│       └── hope-wire.json             → 模块配置
├── src/generated/main/                → 生成代码（只读）
│   ├── api/                           → API接口
│   ├── domain/                        → 领域实体
│   ├── wire/                          → DTO对象
│   ├── mcp/                           → 微服务契约
│   └── cloud/                         → 云适配器
├── src/test/
│   ├── java/                          → 单元测试
│   └── trait/                         → 测试扩展
└── src/generated/test/                → 生成测试代码（只读）
    ├── api/                           → API契约测试
    └── ...

Gradle 的配置约定：

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

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，以保持一致性。

使用建议

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

Stub 模块

自 SDK 2.1.4-RELEASE 合并为一个模块，不再有 stub 模块或命令!

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";

语法增强

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

Gradle 配置

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

参考

😆 快速入门指南：