Milestone 2.0.0-RELEASE

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

😆 快速入门指南：

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

新特性亮点

多态支持：通过 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 命令。
项目结构变更如下：

Wire 模块

模块结构

src/
├── main/
│   ├── java/        → 手写的核心业务逻辑代码  
│   ├── api/         → 由 Wire 编译器生成的 Java 类（用于生产环境）  
│   └── proto/       → `.proto` 协议定义文件（作为资源包含，此处不编译为 Java）  
│
├── test/
│   ├── java/        → 标准的单元测试与集成测试  
│   └── api/         → API 契约/守卫测试（在 `test` 阶段编译并执行）  
│
└── test-kola/
    ├── java/        → 自动生成的 Java 测试类（通过 JUnit Platform 编译并执行）  
    ├── groovy/      → 人工编写的 Groovy DSL 脚本（作为资源处理，**不编译**）  
    └── resources/   → 其他测试资源（如契约、测试数据、配置等）

说明

test-kola/groovy 目录中的 Groovy DSL 脚本由开发者编写，用于定义测试契约或行为，不会被 Gradle 编译。
构建过程中，这些脚本作为资源被复制到 testKola 源集的输出目录，供自定义代码生成器在构建时读取。
基于这些 DSL 脚本生成的 Java 测试类位于 test-kola/java，由 testKola Gradle 任务编译，并通过 JUnit Platform 执行。

Stub 模块

生产源码布局

为提升可读性与可维护性，应用的生产代码按逻辑拆分至 src/main/ 下多个子目录：

src/main/
├── java/      → 手写业务逻辑（服务、控制器等）
├── api/       → 自动生成的 DTO 与 REST 接口
├── trait/     → 自动生成或共享的 Mixin/Trait 类
├── mcp/       → 自动生成的微服务契约或协议代码
└── domain/    → 核心领域模型（聚合根、值对象等）

尽管物理路径分离，所有源码均属于同一生产模块，需一并编译打包为单一 JAR。

测试源码布局

测试代码采用对称结构，保持逻辑一致性：

src/test/
├── java/      → 核心逻辑的单元/集成测试
├── api/       → API 层契约/守卫测试
├── trait/     → Trait/Mixin 行为验证
├── mcp/       → 协议契约校验测试
└── domain/    → 领域模型不变性与行为测试

所有测试源码均属于标准 test 源集，通过 test 任务统一执行，共享主模块与测试模块的类路径及依赖（如 JUnit、Mockito 等）。

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 命令生成内容为空。

On this page