快速开始

创建一个 ApiHug 项目，理解模块结构，并跑通 contract-first 工具链。

这一页带你从空目录走到一个可运行的 ApiHug 演示项目。路径很直接：先准备环境，再生成项目，接着跑通 wire、和应用启动，最后检查生成出来的 OAS 接口文档。

ApiHug 3.x 面向 Spring Boot 4.0 及以上版本。升级老项目之前，建议先阅读 Spring Boot 4.0 迁移指南。

你会完成什么

第一次体验通常会完成以下几件事：

初始化一个 ApiHug 工作目录
通过 IntelliJ 向导（ApiHug REPL）生成一个演示项目
执行 wire、然后应用启动
打开生成出来的 OAS 文档

开始之前

初始化工作目录

ApiHug 为常见 shell 提供了启动脚本。

iex (irm 'https://raw.githubusercontent.com/apihug/apihug.github.io/main/helper/apihug-install.ps1')

如果你是在现有 Spring 项目上升级，请先阅读 Spring Boot 4.0 Migration Guide，再推进 ApiHug SDK 升级。

准备开发环境

先准备好基础环境：

JDK 17 或更高版本
Gradle 8 或更高版本
IntelliJ IDEA 2022 或更高版本
ApiHug - API design Copilot 插件
可访问的 Spring Initializr，或你们团队自己的等价初始化流程

Maven Central version badge for com.apihug/it-bom

IntelliJ 插件

先从 JetBrains Marketplace 安装插件，然后重启 IntelliJ。

如果你后续更偏好命令行工作流，可以再配合 ApiHug REPL 使用。首次上手时，IntelliJ 向导仍然是理解项目结构最快的入口。

插件安装路径

打开 File > Settings > Plugins
搜索 ApiHug
安装插件
重启 IntelliJ

生成项目

IntelliJ 向导会直接给出一个适合 contract-first 开发的起点。

1. 创建 ApiHug 项目

打开 File > New > Project
选择 ApiHug
进入项目设置步骤

2. 填写项目设置

设置 package、项目名、描述、SDK 选项、数据库厂商、缓存和端口。

第一次使用时，除非团队已经有固定模板，否则建议先保留默认配置。

一个典型的 ApiHug 项目通常从两个模块开始：

Text

order
|- order-app
`- order-app-proto

order 是根工作区
order-app 是手写业务逻辑所在的应用模块
order-app-proto 是驱动生成的契约模块

3. 选择 Spring 组件

这一段的心智模型和 Spring Initializr 一致：先选项目类型，再按需加入像 Spring Web 这样的 starter。

完成后点击 Create -> Open Project。

4. 以 Gradle 方式加载项目

如果 IntelliJ 没有自动导入，请手动按 Gradle 项目重新加载。正常情况下你会看到 demo-app 和 demo-app-proto 两个模块。

升级已有项目时，先更新 gradle/libs.versions.toml，再重新加载 Gradle，确保 SDK 版本一致生效。

理解项目结构

最小示例可以参考 simplest-demo：

Terminal

+---gradle
|   |   libs.versions.toml  (1)
+---demo-app  (2)
|   |   build.gradle
|   \---src
|       \---main
|           +---java
|           |   \---com
|           |       \---apihug
|           |           \---demo
|           |               |   DemoAppApplication.java
|           |               +---domain
|           |               \---service
|           \---resources
|               |   hope-stub.json  (3)
|
+---demo-app-proto (4)
|   |   build.gradle
|   \---src
|       \---main
|           +---proto
|           |   \---com
|           |       \---apihug
|           |           \---demo
|           |               \---proto
|           |                   +---api
|           |                   \---infra
|           \---resources
|                   hope-wire.json (5)

文件	作用
(1) `libs.versions.toml`	版本目录与插件别名配置
(2) `demo-app`	应用模块与手写业务逻辑
(3) `hope-stub.json`	应用模块的生成配置
(4) `demo-app-proto`	protobuf 契约模块与 wire 输出
(5) `hope-wire.json`	proto 模块元数据

# versions
apihug = "<current-version>"
springBoot = "4.0.0"
springDependency = "1.1.7"

# libraries
apihugBom = { group = "com.apihug", name = "it-bom", version.ref = "apihug" }

# plugins
springBoot = { id = "org.springframework.boot", version.ref = "springBoot" }
springDependency = { id = "io.spring.dependency-management", version.ref = "springDependency" }

跑通 Contract-First 工具链

1. 执行 Wire

wire 负责校验 proto 模块，并生成中立的契约构建输出。

打开 README.md > 0. Build All
复制命令到终端，例如 gradlew clean build -x test -x wireTest -x stubTest
执行命令
查看 demo-app-proto 下的生成结果

2. 启动应用

打开 README.md > 3. Run Application
执行 gradlew demo-app:bootRun
确认应用正常启动