Java技术交流

SpringBoot 教程

最后更新：2026-08-05
适合人群：刚开始学 Java 后端、准备做 Spring Boot 项目、正在从普通 Java 项目转 Spring Boot 的开发者
相关内容：JDK、Maven、Gradle、Spring Boot、REST API、JSON、MyBatis、MySQL、项目部署

Spring Boot 是现在 Java 后端开发里最常用的一套框架工具。它不是要替代 Spring，而是把 Spring 项目的初始化、依赖配置、内嵌服务器、自动配置这些事情做得更省心。

以前新建一个 Spring 项目，经常要手动配一堆 XML、Tomcat、依赖版本。Spring Boot 的思路更直接：选好依赖，写好业务代码，项目就能直接跑起来。Spring 官方对 Spring Boot 的介绍也是“创建可独立运行、生产级别的 Spring 应用，并尽量减少配置”。(Home)

这篇文章不讲玄乎的概念，按实际开发顺序来：先准备环境，再创建项目，然后写接口、接收参数、连接数据库，最后讲常见报错和后续学习路线。

一、学 Spring Boot 前要准备什么

不要一上来就直接学微服务、分布式、源码分析。Spring Boot 入门前，先把这几件事准备好：

1. 会一点 Java 基础语法
2. 能安装和切换 JDK
3. 会用 IDEA 打开项目
4. 知道 Maven 或 Gradle 是干什么的
5. 能看懂简单的 Controller、Service、Mapper 分层
6. 知道 HTTP、JSON、接口请求这些基本概念

如果环境还没配置好，可以先看这些文章：

现在新项目一般建议优先用 JDK17 或 JDK21。Spring Boot 当前官方系统要求里，Spring Boot 4.1.0 至少需要 Java 17，并兼容到 Java 26。不同 Spring Boot 版本对 JDK 的支持范围不一样，别只看“Spring Boot”这几个字就随便选 JDK。(Home)

可以先看这篇：
Spring Boot JDK 兼容表

二、Spring Boot 适合解决什么问题

Spring Boot 最适合做这类 Java 后端项目：

REST API 服务
后台管理系统
博客系统
权限系统
接口管理系统
企业内部系统
小程序 / App 后端接口
定时任务服务
轻量级微服务

常见组合是：

Spring Boot + Maven + MyBatis + MySQL
Spring Boot + Maven + MyBatis-Plus + MySQL
Spring Boot + Redis
Spring Boot + Spring Security
Spring Boot + Docker

新手不要一开始就追：

Spring Cloud
Nacos
Gateway
Seata
Sentinel
Dubbo
分布式事务
秒杀系统

这些不是不能学，而是要等单体项目、接口开发、数据库操作、部署流程都熟悉之后再学。否则很容易变成“项目能跑，但完全不知道为什么”。

三、怎么创建 Spring Boot 项目

最常见的方式是用 Spring Initializr。

Spring 官方入门指南也建议通过 Spring Initializr 填写项目信息、选择依赖，然后下载一个项目压缩包。(Home)

创建时建议这样选：

Project：Maven
Language：Java
Spring Boot：选择当前稳定版本
Packaging：Jar
Java：17 或 21

常用依赖可以先选：

Spring Web
Validation
MyBatis Framework
MySQL Driver
Lombok

如果只是写第一个接口，只选：

Spring Web
Lombok

就够了。

不要一开始把 Redis、Security、JPA、OAuth2、RabbitMQ、Kafka 全部勾上。依赖越多，启动问题越多，排查难度也越高。

四、一个最简单的 Spring Boot 项目结构

常见结构大概是这样：

src/main/java
└── com/example/demo
    ├── DemoApplication.java
    ├── controller
    │   └── UserController.java
    ├── service
    │   └── UserService.java
    ├── mapper
    │   └── UserMapper.java
    ├── entity
    │   └── User.java
    ├── dto
    │   └── UserCreateRequest.java
    └── vo
        └── UserVO.java

src/main/resources
├── application.yml
└── mapper
    └── UserMapper.xml

简单理解：

controller：接收请求
service：写业务逻辑
mapper：访问数据库
entity：数据库表对应对象
dto：接收前端参数
vo：返回给前端的数据
application.yml：配置文件

新手最容易犯的错是把所有代码都写在 Controller 里。这样一开始能跑，但项目一复杂就很难维护。

比较舒服的写法是：

Controller 只处理请求和响应
Service 处理业务
Mapper 只处理数据库
DTO 和 VO 分开

五、写第一个接口

先写一个简单接口：

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

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello Spring Boot";
    }
}

启动项目后访问：

http://localhost:8080/hello

能看到：

Hello Spring Boot

这里几个注解先记住：

@RestController：表示这是一个接口控制器
@GetMapping：处理 GET 请求
@PostMapping：处理 POST 请求
@RequestMapping：设置统一请求路径

比如：

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public String getUser(@PathVariable Long id) {
        return "用户ID：" + id;
    }
}

访问：

http://localhost:8080/users/1

六、Spring Boot 接收 JSON 参数

写后端接口时，最常见的是前端传 JSON，后端用 Java 对象接住。

请求 JSON：

{
  "username": "zhangsan",
  "age": 18
}

DTO：

import lombok.Data;

@Data
public class UserCreateRequest {

    private String username;

    private Integer age;
}

Controller：

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/users")
public class UserController {

    @PostMapping
    public String createUser(@RequestBody UserCreateRequest request) {
        return "接收到用户：" + request.getUsername();
    }
}

请求头要是：

Content-Type: application/json

如果请求头不对，或者 JSON 结构和 Java 对象对不上，就容易出现：

Required request body is missing
415 Unsupported Media Type
JSON parse error
Cannot deserialize value of type

这部分可以继续看：
Spring Boot 接收 JSON 参数

JSON转Java实体类完整教程

七、Spring Boot 配置文件怎么写

Spring Boot 常见配置文件有两种：

application.yml
application.properties

我个人更推荐 application.yml，层级更清楚。

例如配置端口：

server:
  port: 8081

配置应用名：

spring:
  application:
    name: demo-api

配置不同环境：

application.yml
application-dev.yml
application-prod.yml

在 application.yml 中激活开发环境：

spring:
  profiles:
    active: dev

如果你改了 application-dev.yml，但没有激活 dev，配置不会生效。这类问题很常见。

端口被占用可以看：
Spring Boot 端口被占用怎么处理

八、Spring Boot 连接 MySQL

连接 MySQL 一般需要三件事：

1. 引入数据库驱动
2. 配置 spring.datasource
3. 写 Mapper 或 Repository

Maven 依赖：

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

application.yml：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/demo?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver

如果你引入了数据库相关依赖，却没写数据库配置，就容易报：

Failed to configure a DataSource

这篇可以直接看：
Spring Boot DataSource 报错怎么处理

九、Spring Boot 整合 MyBatis

Spring Boot 项目里，MyBatis 是很常见的持久层方案。

Maven 依赖：

<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>3.0.4</version>
</dependency>

Mapper 接口：

public interface UserMapper {

    User selectUserById(Long id);
}

Mapper XML：

<mapper namespace="com.example.demo.mapper.UserMapper">

    <select id="selectUserById" resultType="com.example.demo.entity.User">
        select id, username, nickname
        from user
        where id = #{id}
    </select>

</mapper>

配置 XML 路径：

mybatis:
  mapper-locations: classpath*:mapper/**/*.xml

启动类加：

@MapperScan("com.example.demo.mapper")
@SpringBootApplication
public class DemoApplication {
}

如果接口和 XML 没绑定上，就可能报：

Invalid bound statement (not found)

继续看：
MyBatis Invalid bound statement 怎么处理

十、统一返回结果

真实项目里，不建议接口一会儿返回字符串，一会儿返回 Map，一会儿返回对象。

可以统一成这种格式：

{
  "code": 200,
  "message": "success",
  "data": {}
}

简单封装：

import lombok.AllArgsConstructor;
import lombok.Data;

@Data
@AllArgsConstructor
public class ApiResult<T> {

    private Integer code;

    private String message;

    private T data;

    public static <T> ApiResult<T> success(T data) {
        return new ApiResult<>(200, "success", data);
    }

    public static <T> ApiResult<T> fail(String message) {
        return new ApiResult<>(500, message, null);
    }
}

Controller：

@GetMapping("/{id}")
public ApiResult<UserVO> getUser(@PathVariable Long id) {
    UserVO user = new UserVO();
    user.setId(id);
    user.setUsername("zhangsan");
    return ApiResult.success(user);
}

这类写法不是必须，但会让前后端联调舒服很多。

十一、参数校验

接口参数不能只靠前端校验。后端也要校验。

依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

DTO：

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import lombok.Data;

@Data
public class UserCreateRequest {

    @NotBlank(message = "用户名不能为空")
    private String username;

    @NotNull(message = "年龄不能为空")
    private Integer age;
}

Controller：

@PostMapping
public ApiResult<Long> createUser(@Valid @RequestBody UserCreateRequest request) {
    return ApiResult.success(1L);
}

Spring MVC 官方文档说明，@RequestBody 可以配合 @Valid 或 @Validated 触发 Bean Validation，校验失败时默认会抛出相关异常并返回 400 响应。(Home)

后续可以单独写一篇：

Spring Boot 参数校验

十二、全局异常处理

项目里不要到处写：

try {
    ...
} catch (Exception e) {
    ...
}

更常见的做法是统一异常处理：

import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(RuntimeException.class)
    public ApiResult<Void> handleRuntimeException(RuntimeException e) {
        return ApiResult.fail(e.getMessage());
    }
}

这样业务里可以直接抛异常：

throw new RuntimeException("用户不存在");

接口返回统一格式：

{
  "code": 500,
  "message": "用户不存在",
  "data": null
}

真实项目里还可以继续细分：

参数校验异常
业务异常
权限异常
数据库异常
第三方接口异常

十三、日志怎么配置

Spring Boot 默认已经有日志能力。普通项目先不要急着自己引入一堆日志依赖。

常用配置：

logging:
  level:
    root: info
    com.example.demo: debug

日志里建议打印：

请求关键参数
业务关键节点
外部接口调用结果
异常堆栈
耗时信息

不要打印：

密码
token
身份证
手机号完整明文
银行卡
敏感业务数据

新手常犯的错是把日志当 System.out.println() 用。开发阶段可以临时打印，但正式项目建议用日志框架。

十四、Spring Boot 打包运行

Maven 项目打包：

mvn clean package

生成文件一般在：

target/demo-0.0.1-SNAPSHOT.jar

运行：

java -jar target/demo-0.0.1-SNAPSHOT.jar

指定端口：

java -jar target/demo-0.0.1-SNAPSHOT.jar --server.port=8081

指定环境：

java -jar target/demo-0.0.1-SNAPSHOT.jar --spring.profiles.active=prod

如果 Maven 下载依赖失败，可以看：
Maven 下载依赖失败怎么处理

如果依赖冲突，可以看：
Maven 依赖冲突怎么排查

十五、Spring Boot 常见报错

Spring Boot 入门阶段，常见报错基本集中在这几个方向：

JDK版本不对
Maven依赖下载失败
端口被占用
数据库配置缺失
JSON参数接收失败
Mapper XML找不到
配置文件没生效

本站已经整理了几篇常见问题：
Spring Boot DataSource 报错怎么处理

Spring Boot 端口被占用怎么处理

Spring Boot 接收 JSON 参数

MyBatis Invalid bound statement 怎么处理

Java major version 对照表

Maven 下载依赖失败怎么处理

遇到报错时，不要只复制最后一行。要看完整堆栈，尤其是：

Caused by
APPLICATION FAILED TO START
Description
Action

Spring Boot 很多启动失败日志会直接给出建议，别忽略它。

十六、Spring Boot 版本怎么选

不要只看网上教程用什么版本。要看你自己的 JDK、依赖和项目情况。

大致建议：

老项目：按现有版本维护，不要盲目升级
Spring Boot 2.7 项目：可以准备向 Spring Boot 3 迁移
当前新项目：优先 Spring Boot 3.x + JDK21
长期新项目：可以关注 Spring Boot 4.x + JDK25

版本兼容可以看：
Spring Boot JDK 兼容表

如果你要从 2 升到 3，可以看：
Spring Boot 2 升级 3 指南

升级 Spring Boot 不只是改版本号，还要检查：

JDK版本
Maven / Gradle版本
Spring Security
MyBatis / JPA
javax 到 jakarta
第三方 Starter
Docker 和 CI/CD 环境

十七、推荐学习顺序

如果你准备系统学 Spring Boot，可以按这个顺序：

1. JDK 和 IDEA 环境配置
2. Maven 基础
3. Spring Boot 创建项目
4. Controller 和接口
5. JSON 参数接收
6. 配置文件 application.yml
7. MySQL 数据库连接
8. MyBatis / MyBatis-Plus
9. 统一返回结果
10. 参数校验
11. 全局异常处理
12. 日志配置
13. 打包部署
14. 常见报错排查
15. 再学 Spring Security、Redis、Docker、微服务

不要一上来就学微服务。先把单体 Spring Boot 项目写顺，后面会轻松很多。

十八、一个小项目应该包含哪些功能

如果你想做一个 Spring Boot 练手项目，建议至少包含这些内容：

用户注册登录
用户列表分页
新增、编辑、删除
参数校验
统一返回结果
全局异常处理
MyBatis 查询
MySQL 数据库
接口文档
日志
打包部署

项目可以很小，但流程要完整。

比如：

图书管理系统
博客系统
任务管理系统
后台管理系统
接口管理系统

不要一开始就做“秒杀系统”“大型分布式商城”。那些项目不是入门项目。

十九、Spring Boot 适合和哪些技术一起学

入门阶段：

Maven
MySQL
MyBatis
JSON
HTTP
IDEA
Postman / Apifox

进阶阶段：

Redis
Spring Security
Docker
Linux
Nginx
JVM
日志和监控

再往后：

Spring Cloud
消息队列
分布式事务
网关
配置中心
注册中心
链路追踪

学习顺序不要反过来。基础没稳，直接学分布式，很容易只记住一堆名词。

二十、最后总结

Spring Boot 入门不难，难的是别一上来把东西学散。

先抓住这条主线：

创建项目
写接口
接收参数
连接数据库
返回结果
处理异常
打包部署
排查报错

对新手来说，最值得先掌握的是：

Controller
@RequestBody
application.yml
Maven
MyBatis
MySQL
统一返回
全局异常
日志
打包运行

不要急着追 Spring Cloud。先把一个 Spring Boot 单体项目做完整，比看十套微服务视频更有用。

二十一、本站推荐阅读

Java 环境配置：
Java开发环境配置专题

Spring Boot 版本：
Spring Boot JDK 兼容表

Spring Boot 2 升级 3 指南

Spring Boot 报错：
Spring Boot DataSource 报错怎么处理

Spring Boot 端口被占用怎么处理

接口开发：
Spring Boot 接收 JSON 参数

JSON转Java实体类完整教程

MyBatis：
MyBatis Invalid bound statement 怎么处理

Maven：
Maven 国内镜像配置教程

Maven 依赖冲突怎么排查

更新记录

2026-08-05：
- 创建 Spring Boot 教程入口文章
- 增加 Spring Boot 学习前置要求
- 增加项目结构、接口、JSON参数、数据库、MyBatis、统一返回、异常处理、打包部署说明
- 增加本站 Spring Boot 相关文章阅读顺序

如果觉得文章对你有用，请随意赞赏

SpringBoot Java

SpringBoot 教程

https://java.li/archives/spring-boot-tutorial

作者

HiF

发布于

2026-08-05

更新于

2026-08-05

许可协议

CC BY 4.0

Json美化工具站	文字推荐位2
yq.cx \| 一起查询	文字推荐位4
文字推荐位5	文字推荐位6
文字推荐位7	文字推荐位8
文字推荐位9	文字推荐位10

SpringBoot 教程

一、学 Spring Boot 前要准备什么

二、Spring Boot 适合解决什么问题

三、怎么创建 Spring Boot 项目

四、一个最简单的 Spring Boot 项目结构

五、写第一个接口

六、Spring Boot 接收 JSON 参数

七、Spring Boot 配置文件怎么写

八、Spring Boot 连接 MySQL

九、Spring Boot 整合 MyBatis

十、统一返回结果

十一、参数校验

十二、全局异常处理

十三、日志怎么配置

十四、Spring Boot 打包运行

十五、Spring Boot 常见报错

十六、Spring Boot 版本怎么选

十七、推荐学习顺序

十八、一个小项目应该包含哪些功能

十九、Spring Boot 适合和哪些技术一起学

二十、最后总结

二十一、本站推荐阅读

更新记录

作者

发布于

更新于

许可协议

评论