2026-08-30 · IDEA 创建纯净 Spring Boot 4 项目，跑通第一个接口。

Spring Boot 4 项目创建

1. 解决什么问题

得到一个干净的、能跑的最小项目：IDEA 向导创建 → 配国内镜像 → 写第一个接口 → 浏览器看到返回。不引入任何额外依赖，后面每一步用到什么再往这个项目里加。

2. 环境

组件	版本
JDK	25（Temurin）
IDEA	2024.x+（社区版即可）
Maven	3.9.x（`scoop install maven`）

3. 国内镜像（先配，否则依赖下载卡死）

编辑 C:\Users\zgqin\.m2\settings.xml：

xml

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <mirrors>
    <mirror>
      <id>aliyun</id>
      <mirrorOf>*</mirrorOf>
      <name>阿里云公共仓库</name>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
  </mirrors>
</settings>

4. IDEA 创建

File → New → Project，左侧选 Spring Initializr（不是 Maven/Archetype 向导）
选项按下面填：

项	值
Type	Maven
Language	Java
Spring Boot	4.1.x
JDK	25
Group	`com.zgqin`
Artifact	项目名（如 `demo`）
Packaging	jar
Configuration	yaml

依赖只勾一个：Spring Web。其他都不勾，后面用到再加
勾 Create Git repository → 点 Create

5. 项目结构

src/main/
├── java/com/zgqin/demo/
│   └── DemoApplication.java      ← 启动类（程序的入口）
└── resources/
    └── application.yaml          ← 配置（暂时是空的）

启动类内容是固定的：

java

package com.zgqin.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

启动类必须放在最外层包（com.zgqin.demo，不在任何子包下），否则接口全部 404。

6. 第一个接口

在启动类旁边新建 controller/HelloController.java：

java

package com.zgqin.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/api/hello")
    public String hello() {
        return "hello spring boot 4";
    }
}

两个注解的作用：

注解	作用
`@RestController`	这个类是接口类，返回值直接作为 JSON 响应体
`@GetMapping("/api/hello")`	浏览器 GET 访问这个路径时，执行这个方法

7. 跑起来

点 DemoApplication 行号旁的绿色三角运行。控制台出现 Tomcat started on port 8080 后，浏览器打开：

http://localhost:8080/api/hello

页面显示 hello spring boot 4，项目跑通。

7.1 在哪个终端测接口

所有 curl 命令都在 Git Bash 终端里执行。两个位置任选：

IDEA 底部 Terminal：点开 Terminal 标签 → 左上角下拉箭头 → 选 Git Bash
系统 Git Bash：按 Win 键 → 搜 Git Bash → 回车打开

用 Git Bash，不要用 PowerShell（它的 curl 是假别名，不认 -X/-H/-d）。 curl 打的是 http://localhost:8080/... 网络地址，跟当前在哪个目录无关，不用 cd 到项目下。

8. 常见坑

现象	解法
依赖下载卡死	配阿里云镜像（第 3 步）
接口 404	启动类移到最外层包
端口 8080 被占用	杀掉占端口的进程，或改 `application.yaml` 的 `server.port`
git-bash 里 `mvn` 报 classworlds 找不到	用 `mvn.cmd`

Spring Boot 4 项目创建 ​

1. 解决什么问题 ​

2. 环境 ​

3. 国内镜像（先配，否则依赖下载卡死） ​

4. IDEA 创建 ​

5. 项目结构 ​

6. 第一个接口 ​

7. 跑起来 ​

7.1 在哪个终端测接口 ​

8. 常见坑 ​