手把手教你从零搭建SpringBoot项目：超详细图文教程

Ne0inhk

16 Mar 2026 — 14 min read

前言

SpringBoot作为当前Java领域最流行的微服务框架之一，以其"约定大于配置"的理念和快速开发的特点，深受开发者喜爱。无论你是Java初学者，还是有一定经验的开发者，掌握SpringBoot都是必备技能。本文将带你从零开始，一步步搭建一个完整的SpringBoot项目，并深入讲解其中的原理和最佳实践。

一、SpringBoot简介与优势

1.1 什么是SpringBoot？

SpringBoot是基于Spring框架的"脚手架"工具，它简化了基于Spring的应用开发。通过自动配置和起步依赖，开发者可以快速创建独立运行、生产级别的Spring应用程序。

1.2 SpringBoot的核心优势

· 快速启动：内置Tomcat、Jetty等Web容器，无需部署WAR包
· 自动配置：根据classpath中的jar包自动配置Bean
· 起步依赖：通过starter简化Maven/Gradle配置
· 无代码生成：无需XML配置，开箱即用
· 生产就绪：提供监控、健康检查等生产级特性

二、环境准备与工具安装

2.1 JDK安装与配置

SpringBoot 2.x需要JDK 1.8或更高版本，SpringBoot 3.x需要JDK 17或更高版本。

安装步骤：

访问Oracle官网或OpenJDK官网下载JDK
安装JDK并配置环境变量
验证安装：在命令行执行 java -version

# 验证JDK安装java-version javac -version

2.2 开发工具选择与配置

推荐IDE：

· IntelliJ IDEA（推荐使用Ultimate版）
· Eclipse with Spring Tools
· VS Code with Java扩展

2.3 Maven安装与配置

# 下载Maven并解压# 配置环境变量 MAVEN_HOME 和 PATH# 验证安装 mvn -version

2.4 数据库准备（可选）

· MySQL 5.7+/8.0
· PostgreSQL
· 其他支持的数据库

三、使用Spring Initializr快速创建项目

3.1 在线创建项目

访问 start.spring.io
选择项目配置：
· Project: Maven Project
· Language: Java
· Spring Boot: 选择稳定版本（如3.1.0）
· Project Metadata: 填写Group、Artifact等信息
· Dependencies: 添加需要的起步依赖

3.2 使用IDE创建

IntelliJ IDEA创建步骤：

File → New → Project
选择Spring Initializr
配置项目信息
选择依赖（Web、JPA、MySQL等）
完成创建

3.3 使用命令行创建

curl https://start.spring.io/starter.zip \-ddependencies=web,data-jpa,mysql \-dgroupId=com.example \-dartifactId=demo \-o demo.zip unzip demo.zip

四、手动创建SpringBoot项目

虽然推荐使用Spring Initializr，但了解手动创建过程有助于理解项目结构。

4.1 创建Maven项目结构

my-springboot-project/ ├── src/ │ ├── main/ │ │ ├── java/ │ │ │ └── com/example/demo/ │ │ └── resources/ │ │ ├── application.properties │ │ ├── static/ │ │ └── templates/ │ └── test/ │ └── java/ │ └── com/example/demo/ └── pom.xml

4.2 配置pom.xml

<?xml version="1.0" encoding="UTF-8"?><projectxmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><!-- Spring Boot父项目，提供依赖管理 --><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.1.0</version><relativePath/></parent><groupId>com.example</groupId><artifactId>demo</artifactId><version>1.0.0</version><packaging>jar</packaging><name>demo</name><description>Demo project for Spring Boot</description><properties><java.version>17</java.version></properties><dependencies><!-- Web开发起步依赖 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- 测试起步依赖 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency><!-- 热部署依赖（开发时使用） --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-devtools</artifactId><scope>runtime</scope><optional>true</optional></dependency></dependencies><build><plugins><!-- Spring Boot Maven插件 --><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build></project>

4.3 创建主应用类

packagecom.example.demo;importorg.springframework.boot.SpringApplication;importorg.springframework.boot.autoconfigure.SpringBootApplication;/** * SpringBoot应用主类 * @SpringBootApplication 注解标识这是一个SpringBoot应用 */@SpringBootApplicationpublicclassDemoApplication{publicstaticvoidmain(String[] args){// 启动SpringBoot应用SpringApplication.run(DemoApplication.class, args);}}

五、项目结构深度解析

5.1 标准项目目录结构

src/ ├── main/ │ ├── java/ # Java源代码 │ │ └── com/example/demo/ │ │ ├── controller/ # 控制器层 │ │ ├── service/ # 业务逻辑层 │ │ ├── repository/ # 数据访问层 │ │ ├── entity/ # 实体类 │ │ ├── config/ # 配置类 │ │ └── DemoApplication.java # 主应用类 │ └── resources/ # 资源文件 │ ├── static/ # 静态资源(css,js,图片) │ ├── templates/ # 模板文件(thymeleaf,freemarker) │ ├── application.properties # 主配置文件 │ └── application-dev.properties # 开发环境配置 └── test/ # 测试代码 └── java/ └── com/example/demo/

5.2 配置文件详解

application.properties:

# 应用配置 spring.application.name=demo # 服务器配置 server.port=8080 server.servlet.context-path=/demo # 日志配置 logging.level.com.example.demo=DEBUG logging.file.name=logs/demo.log # 开发环境配置 spring.profiles.active=dev

application-dev.properties:

# 开发环境数据库配置 spring.datasource.url=jdbc:mysql://localhost:3306/demo_dev spring.datasource.username=dev_user spring.datasource.password=dev_password # H2内存数据库（开发测试用） # spring.datasource.url=jdbc:h2:mem:testdb # spring.datasource.driverClassName=org.h2.Driver # spring.datasource.username=sa # spring.datasource.password=password # JPA配置 spring.jpa.hibernate.ddl-auto=update spring.jpa.show-sql=true spring.jpa.properties.hibernate.format_sql=true

六、编写第一个RESTful API

6.1 创建实体类

packagecom.example.demo.entity;importjava.time.LocalDateTime;publicclassUser{privateLong id;privateString username;privateString email;privateLocalDateTime createTime;// 构造方法publicUser(){}publicUser(Long id,String username,String email){this.id = id;this.username = username;this.email = email;this.createTime =LocalDateTime.now();}// Getter和Setter方法publicLonggetId(){return id;}publicvoidsetId(Long id){this.id = id;}publicStringgetUsername(){return username;}publicvoidsetUsername(String username){this.username = username;}publicStringgetEmail(){return email;}publicvoidsetEmail(String email){this.email = email;}publicLocalDateTimegetCreateTime(){return createTime;}publicvoidsetCreateTime(LocalDateTime createTime){this.createTime = createTime;}}

6.2 创建控制器

packagecom.example.demo.controller;importcom.example.demo.entity.User;importorg.springframework.web.bind.annotation.*;importjava.util.ArrayList;importjava.util.List;importjava.util.concurrent.atomic.AtomicLong;/** * 用户管理控制器 * @RestController 组合了@Controller和@ResponseBody */@RestController@RequestMapping("/api/users")publicclassUserController{privatefinalList<User> users =newArrayList<>();privatefinalAtomicLong counter =newAtomicLong();// 初始化一些测试数据publicUserController(){ users.add(newUser(counter.incrementAndGet(),"张三","[email protected]")); users.add(newUser(counter.incrementAndGet(),"李四","[email protected]"));}/** * 获取所有用户 * GET /api/users */@GetMappingpublicList<User>getAllUsers(){return users;}/** * 根据ID获取用户 * GET /api/users/{id} */@GetMapping("/{id}")publicUsergetUserById(@PathVariableLong id){return users.stream().filter(user -> user.getId().equals(id)).findFirst().orElse(null);}/** * 创建新用户 * POST /api/users */@PostMappingpublicUsercreateUser(@RequestBodyUser user){ user.setId(counter.incrementAndGet()); users.add(user);return user;}/** * 更新用户信息 * PUT /api/users/{id} */@PutMapping("/{id}")publicUserupdateUser(@PathVariableLong id,@RequestBodyUser userDetails){User user =getUserById(id);if(user !=null){ user.setUsername(userDetails.getUsername()); user.setEmail(userDetails.getEmail());}return user;}/** * 删除用户 * DELETE /api/users/{id} */@DeleteMapping("/{id}")publicStringdeleteUser(@PathVariableLong id){ users.removeIf(user -> user.getId().equals(id));return"用户删除成功";}}

6.3 创建服务层

packagecom.example.demo.service;importcom.example.demo.entity.User;importorg.springframework.stereotype.Service;importjava.util.List;importjava.util.Optional;/** * 用户服务层 * @Service 标识这是一个Spring服务组件 */@ServicepublicclassUserService{/** * 模拟数据库操作 - 获取所有用户 */publicList<User>findAllUsers(){// 实际项目中这里会调用RepositoryreturnList.of(newUser(1L,"张三","[email protected]"),newUser(2L,"李四","[email protected]"));}/** * 根据ID查找用户 */publicOptional<User>findUserById(Long id){// 模拟数据库查询returnfindAllUsers().stream().filter(user -> user.getId().equals(id)).findFirst();}/** * 创建用户 */publicUsercreateUser(User user){// 模拟保存到数据库return user;}}

6.4 更新控制器使用服务层

packagecom.example.demo.controller;importcom.example.demo.entity.User;importcom.example.demo.service.UserService;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.http.ResponseEntity;importorg.springframework.web.bind.annotation.*;importjava.util.List;importjava.util.Optional;@RestController@RequestMapping("/api/v2/users")publicclassUserControllerV2{privatefinalUserService userService;/** * 构造器注入 - 推荐方式 */@AutowiredpublicUserControllerV2(UserService userService){this.userService = userService;}@GetMappingpublicList<User>getAllUsers(){return userService.findAllUsers();}@GetMapping("/{id}")publicResponseEntity<User>getUserById(@PathVariableLong id){Optional<User> user = userService.findUserById(id);return user.map(ResponseEntity::ok).orElse(ResponseEntity.notFound().build());}@PostMappingpublicUsercreateUser(@RequestBodyUser user){return userService.createUser(user);}}

七、数据库集成与JPA使用

7.1 添加数据库依赖

<!-- 在pom.xml中添加 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-jpa</artifactId></dependency><!-- MySQL驱动 --><dependency><groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId><scope>runtime</scope></dependency><!-- H2数据库（测试用） --><dependency><groupId>com.h2database</groupId><artifactId>h2</artifactId><scope>runtime</scope></dependency>

7.2 配置数据源

# application.properties spring.datasource.url=jdbc:mysql://localhost:3306/demo?useSSL=false&serverTimezone=UTC spring.datasource.username=root spring.datasource.password=123456 # JPA配置 spring.jpa.hibernate.ddl-auto=update spring.jpa.show-sql=true spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL8Dialect # H2控制台（开发时使用） spring.h2.console.enabled=true spring.h2.console.path=/h2-console

7.3 创建JPA实体

packagecom.example.demo.entity;importjakarta.persistence.*;importjava.time.LocalDateTime;@Entity@Table(name ="users")publicclassUser{@Id@GeneratedValue(strategy =GenerationType.IDENTITY)privateLong id;@Column(nullable =false, unique =true, length =50)privateString username;@Column(nullable =false, unique =true, length =100)privateString email;@Column(name ="create_time")privateLocalDateTime createTime;// 构造方法publicUser(){this.createTime =LocalDateTime.now();}publicUser(String username,String email){this();this.username = username;this.email = email;}// Getter和Setter// ... 省略getter/setter}

7.4 创建Repository接口

packagecom.example.demo.repository;importcom.example.demo.entity.User;importorg.springframework.data.jpa.repository.JpaRepository;importorg.springframework.data.jpa.repository.Query;importorg.springframework.data.repository.query.Param;importorg.springframework.stereotype.Repository;importjava.util.List;importjava.util.Optional;@RepositorypublicinterfaceUserRepositoryextendsJpaRepository<User,Long>{// 根据用户名查找用户Optional<User>findByUsername(String username);// 根据邮箱查找用户Optional<User>findByEmail(String email);// 自定义查询：查找创建时间在指定时间之后的用户@Query("SELECT u FROM User u WHERE u.createTime > :createTime")List<User>findUsersAfterCreateTime(@Param("createTime")LocalDateTime createTime);// 检查用户名是否存在booleanexistsByUsername(String username);// 检查邮箱是否存在booleanexistsByEmail(String email);}

7.5 更新服务层使用Repository

packagecom.example.demo.service;importcom.example.demo.entity.User;importcom.example.demo.repository.UserRepository;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.stereotype.Service;importjava.util.List;importjava.util.Optional;@ServicepublicclassUserService{privatefinalUserRepository userRepository;@AutowiredpublicUserService(UserRepository userRepository){this.userRepository = userRepository;}publicList<User>findAllUsers(){return userRepository.findAll();}publicOptional<User>findUserById(Long id){return userRepository.findById(id);}publicUsersaveUser(User user){return userRepository.save(user);}publicvoiddeleteUser(Long id){ userRepository.deleteById(id);}publicbooleanexistsByUsername(String username){return userRepository.existsByUsername(username);}publicbooleanexistsByEmail(String email){return userRepository.existsByEmail(email);}}

八、异常处理与统一响应

8.1 创建自定义异常

packagecom.example.demo.exception;publicclassResourceNotFoundExceptionextendsRuntimeException{publicResourceNotFoundException(String message){super(message);}}publicclassBusinessExceptionextendsRuntimeException{publicBusinessException(String message){super(message);}}

8.2 创建统一响应对象

packagecom.example.demo.dto;publicclassApiResponse<T>{privateboolean success;privateString message;privateT data;privateString errorCode;// 成功响应publicstatic<T>ApiResponse<T>success(T data){returnnewApiResponse<>(true,"操作成功", data,null);}publicstatic<T>ApiResponse<T>success(String message,T data){returnnewApiResponse<>(true, message, data,null);}// 失败响应publicstatic<T>ApiResponse<T>error(String message){returnnewApiResponse<>(false, message,null,null);}publicstatic<T>ApiResponse<T>error(String message,String errorCode){returnnewApiResponse<>(false, message,null, errorCode);}// 构造方法、getter、setterpublicApiResponse(boolean success,String message,T data,String errorCode){this.success = success;this.message = message;this.data = data;this.errorCode = errorCode;}// ... 省略getter/setter}

8.3 创建全局异常处理器

packagecom.example.demo.handler;importcom.example.demo.dto.ApiResponse;importcom.example.demo.exception.ResourceNotFoundException;importorg.springframework.http.HttpStatus;importorg.springframework.http.ResponseEntity;importorg.springframework.validation.FieldError;importorg.springframework.web.bind.MethodArgumentNotValidException;importorg.springframework.web.bind.annotation.ExceptionHandler;importorg.springframework.web.bind.annotation.RestControllerAdvice;importjava.util.HashMap;importjava.util.Map;/** * 全局异常处理 */@RestControllerAdvicepublicclassGlobalExceptionHandler{/** * 处理资源不存在异常 */@ExceptionHandler(ResourceNotFoundException.class)publicResponseEntity<ApiResponse<Object>>handleResourceNotFound(ResourceNotFoundException ex){ApiResponse<Object> response =ApiResponse.error(ex.getMessage());returnnewResponseEntity<>(response,HttpStatus.NOT_FOUND);}/** * 处理参数验证异常 */@ExceptionHandler(MethodArgumentNotValidException.class)publicResponseEntity<ApiResponse<Map<String,String>>>handleValidationExceptions(MethodArgumentNotValidException ex){Map<String,String> errors =newHashMap<>(); ex.getBindingResult().getAllErrors().forEach((error)->{String fieldName =((FieldError) error).getField();String errorMessage = error.getDefaultMessage(); errors.put(fieldName, errorMessage);});ApiResponse<Map<String,String>> response =ApiResponse.error("参数验证失败","VALIDATION_ERROR"); response.setData(errors);returnnewResponseEntity<>(response,HttpStatus.BAD_REQUEST);}/** * 处理其他所有异常 */@ExceptionHandler(Exception.class)publicResponseEntity<ApiResponse<Object>>handleGlobalException(Exception ex){ApiResponse<Object> response =ApiResponse.error("服务器内部错误");returnnewResponseEntity<>(response,HttpStatus.INTERNAL_SERVER_ERROR);}}

九、运行与测试

9.1 启动应用程序

方式一：使用IDE运行

· 直接运行主类的main方法

方式二：使用Maven命令

mvn spring-boot:run

方式三：打包后运行

mvn clean package java-jar target/demo-1.0.0.jar

9.2 测试API接口

使用Postman或curl测试创建的API：

# 获取所有用户curl-X GET http://localhost:8080/api/users # 根据ID获取用户curl-X GET http://localhost:8080/api/users/1 # 创建新用户curl-X POST http://localhost:8080/api/users \-H"Content-Type: application/json"\-d'{"username":"王五","email":"[email protected]"}'# 更新用户curl-X PUT http://localhost:8080/api/users/1 \-H"Content-Type: application/json"\-d'{"username":"张三丰","email":"[email protected]"}'# 删除用户curl-X DELETE http://localhost:8080/api/users/1

9.3 编写单元测试

packagecom.example.demo.controller;importcom.example.demo.entity.User;importcom.example.demo.service.UserService;importcom.fasterxml.jackson.databind.ObjectMapper;importorg.junit.jupiter.api.Test;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;importorg.springframework.boot.test.mock.mockito.MockBean;importorg.springframework.http.MediaType;importorg.springframework.test.web.servlet.MockMvc;importjava.util.Arrays;importjava.util.Optional;importstaticorg.mockito.ArgumentMatchers.any;importstaticorg.mockito.Mockito.when;importstaticorg.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;importstaticorg.springframework.test.web.servlet.result.MockMvcResultMatchers.*;@WebMvcTest(UserControllerV2.class)publicclassUserControllerTest{@AutowiredprivateMockMvc mockMvc;@MockBeanprivateUserService userService;@AutowiredprivateObjectMapper objectMapper;@TestpublicvoidtestGetAllUsers()throwsException{User user1 =newUser(1L,"user1","[email protected]");User user2 =newUser(2L,"user2","[email protected]");when(userService.findAllUsers()).thenReturn(Arrays.asList(user1, user2)); mockMvc.perform(get("/api/v2/users")).andExpect(status().isOk()).andExpect(jsonPath("$[0].username").value("user1")).andExpect(jsonPath("$[1].username").value("user2"));}@TestpublicvoidtestGetUserById()throwsException{User user =newUser(1L,"testuser","[email protected]");when(userService.findUserById(1L)).thenReturn(Optional.of(user)); mockMvc.perform(get("/api/v2/users/1")).andExpect(status().isOk()).andExpect(jsonPath("$.username").value("testuser"));}@TestpublicvoidtestCreateUser()throwsException{User user =newUser("newuser","[email protected]");User savedUser =newUser(1L,"newuser","[email protected]");when(userService.saveUser(any(User.class))).thenReturn(savedUser); mockMvc.perform(post("/api/v2/users").contentType(MediaType.APPLICATION_JSON).content(objectMapper.writeValueAsString(user))).andExpect(status().isOk()).andExpect(jsonPath("$.id").value(1L));}}

十、项目优化与最佳实践

10.1 配置文件优化

使用YAML格式配置：

# application.ymlspring:application:name: demo datasource:url: jdbc:mysql://localhost:3306/demo username: root password:123456jpa:hibernate:ddl-auto: update show-sql:trueproperties:hibernate:dialect: org.hibernate.dialect.MySQL8Dialect format_sql:trueserver:port:8080servlet:context-path: /demo logging:level:com.example.demo: DEBUG file:name: logs/demo.log

10.2 多环境配置

# application-dev.ymlspring:datasource:url: jdbc:mysql://localhost:3306/demo_dev username: dev_user password: dev_password jpa:show-sql:true---# application-prod.ymlspring:datasource:url: jdbc:mysql://prod-db:3306/demo_prod username: prod_user password: ${DB_PASSWORD}jpa:show-sql:falselogging:level:com.example.demo: INFO

10.3 添加Swagger API文档

<!-- 添加依赖 --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.1.0</version></dependency>

// 配置类@ConfigurationpublicclassOpenApiConfig{@BeanpublicOpenAPIcustomOpenAPI(){returnnewOpenAPI().info(newInfo().title("Demo API").version("1.0").description("SpringBoot Demo项目API文档").contact(newContact().name("开发者").email("[email protected]")));}}

访问：http://localhost:8080/swagger-ui.html

十一、常见问题与解决方案

11.1 端口被占用

# 修改端口 server.port=8081

11.2 数据库连接失败

· 检查数据库服务是否启动
· 验证连接URL、用户名、密码
· 检查网络连接

11.3 依赖冲突

使用Maven依赖树分析：

mvn dependency:tree

11.4 热部署配置

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-devtools</artifactId><scope>runtime</scope><optional>true</optional></dependency>

在IDE中开启自动编译。

十二、总结

通过本文的详细讲解，你应该已经掌握了：

SpringBoot项目创建：多种创建方式及其适用场景
项目结构理解：标准的Maven目录结构和SpringBoot约定
核心组件开发：Controller、Service、Repository的分层架构
数据库集成：使用Spring Data JPA进行数据持久化
RESTful API设计：遵循REST原则设计清晰的API接口
异常处理：统一的异常处理和响应格式
测试策略：单元测试和集成测试的编写
项目优化：配置文件管理、多环境配置等最佳实践

SpringBoot的强大之处在于它的"约定大于配置"理念和丰富的starter生态。掌握这些基础后，你可以继续深入学习SpringBoot的高级特性，如安全认证、消息队列、缓存、监控等，构建更加复杂和强大的应用程序。

希望本教程对你有所帮助，祝你SpringBoot学习之路顺利！

手把手教你从零搭建SpringBoot项目：超详细图文教程

Ne0inhk

Read more

免疫治疗门诊动线优化：Go离散事件仿真（DES）从“常规排队”到“ResusBay挤兑”的技术全解（上）

π0源码(openpi)剖析——从π0模型架构的实现：如何基于PaLI-Gemma和扩散策略去噪生成动作，到基于C/S架构下的模型训练与部署

Palantir 产品架构调研

X86、ARM与C86架构全面对比分析：性能、功耗、成本与生态系统