Spring Boot 全方位指南：从项目初始化到分层架构搭建

Spring Boot 全方位指南：从项目初始化到分层架构搭建

本教程旨在引导 Java 开发者，特别是 Spring Boot 的初学者，从零开始创建一个结构清晰、功能完备的后端项目。

我们将从项目初始化开始，详细讲解每一项依赖的作用，然后配置数据库，并最终搭建起经典的 MVC（Model-View-Controller）分层架构。

目录

• 1. 依赖讲解
  • 通用依赖
  • 数据库相关依赖
• 2. 初始化项目步骤详细
  • 附录：在 Visual Studio Code 中打开和运行项目
• 3. 项目转化为基于 Java 8 的修改方法(按需)
  • 重要：jakartavsjavax命名空间变更
• 4. 需要手动添加的依赖
  • 场景一：Spring Boot 3.x (推荐)
  • 场景二：Spring Boot 2.x (兼容旧版 Java 8)
• 5. 数据库支持
  • 情况一：集成 MongoDB
  • 情况二：集成 MySQL
• 6. 修改服务端口号
• 7. 搭建基础分层结构
  • 创建实体层 (Entity/Model)
  • 创建数据访问层 (Repository)
  • 创建业务逻辑层 (Service)
  • 创建表现层 (Controller)
• 8. 生成并访问 API 文档

1. 依赖讲解

在创建项目之前，理解核心依赖的作用至关重要。它们是构建项目的基础。

通用依赖

• Spring Web: 这是构建 Web 应用的核心模块，包括传统的 Spring MVC 和 RESTful API。它内置了 Tomcat 服务器，使我们无需额外配置 Web 服务器就能运行项目。
• Lombok: 一个非常实用的 Java 库，可以通过注解自动生成构造函数、Getter/Setter、toString()等模板代码，极大地简化了实体类和数据传输对象的编写。
• Spring Boot DevTools: 开发阶段的辅助工具。它提供了热部署功能，当你修改代码后，应用会自动重新启动，无需手动操作，从而显著提升开发效率。
• Springdoc OpenAPI: 用于根据代码自动生成 OpenAPI 3.0 格式的 API 文档。它与 Swagger UI 集成，提供了一个美观且可交互的 API 测试界面。

数据库相关依赖

根据你选择的数据库，需要引入不同的依赖：

• MongoDB:
  • Spring Data MongoDB: 提供了在 Spring 应用中与 MongoDB 数据库交互的便捷支持，包括对象-文档映射 (ODM) 和 Repository 抽象。
• MySQL:
  • Spring Data JPA: Java Persistence API (JPA) 是 Java EE 的标准规范，用于对象关系映射 (ORM)。Spring Data JPA 在其基础上提供了更高层次的抽象，简化了数据访问层的开发。
  • MySQL Driver: 这是 MySQL 数据库的 JDBC 驱动，是 Java 应用连接 MySQL 数据库的桥梁。

2. 初始化项目步骤详细

我们将使用 Spring Initializr 这个官方工具来生成项目骨架。

请按照以下步骤进行配置：

• Project: 选择Maven。Maven 是一个强大的项目管理和构建工具。

• Language: 选择Java。

• Spring Boot: 选择一个稳定且被广泛推荐的版本，例如3.5.3或其他3.x.x系列的非快照版本。

• Project Metadata:

  • Group:com.example(通常是你的公司或组织域名倒写)
  • Artifact:my-spring-project(项目名称)
  • Name:my-spring-project(同上)
  • Description:Demo project for Spring Boot(项目描述)
  • Package name:com.example.myspringproject(项目的基础包名)

• Packaging: 选择Jar。这是现代微服务架构中最常见的打包方式，项目会作为一个独立的可执行文件运行。

• Java: 选择一个长期支持 (LTS) 版本，如17或21。

• Dependencies: 在页面右侧，点击 “ADD DEPENDENCIES…” 按钮，然后搜索并添加以下依赖：

  • Spring Web
  • Lombok
  • Spring Boot DevTools
  • Springdoc OpenAPI（如果可选项中可用，建议直接勾选）
  • 根据你的数据库选择:
    • MongoDB 用户: 添加Spring Data MongoDB。
    • MySQL 用户: 添加Spring Data JPA和MySQL Driver。

如果 Spring Initializr 中没有直接提供Springdoc OpenAPI依赖，可先完成项目生成，再参考下面的“需要手动添加的依赖”章节，将springdoc-openapi依赖手动加入pom.xml。

完成以上配置后，点击 “GENERATE” 按钮下载项目压缩包，然后在你的 IDE (如 IntelliJ IDEA 或 Eclipse 或 VS Code) 中导入该 Maven 项目。

附录：在 Visual Studio Code 中打开和运行项目

对于 VS Code 用户，请遵循以下步骤来设置和运行你的 Spring Boot 项目。

1. 安装必备扩展:
   在开始之前，请确保你已经在 VS Code 中安装了 Java 开发的必备扩展。在扩展市场中搜索并安装以下扩展包，它提供了对 Java 开发的全面支持：

   • Extension Pack for Java(来自 Microsoft)

2. 打开项目:
   将从 Spring Initializr 下载的压缩包解压。然后，在 VS Code 中，通过菜单栏的文件 (File)>打开文件夹... (Open Folder...)，选择刚刚解压的项目根目录。

3. 项目加载:
   VS Code 会自动识别这是一个基于 Maven 的 Java 项目。右下角会弹出提示，询问你是否信任此工作区，请选择“是”。之后，Java 扩展会自动开始下载项目所需的依赖项 (Dependencies)。你可以在左侧边栏的JAVA PROJECTS视图中看到项目的结构和依赖加载进度。

4. 运行项目:
   项目依赖加载完毕后，请在文件资源管理器中找到src/main/java/com/example/myspringproject/MySpringProjectApplication.java文件。你有多种方式启动它：

   • 在编辑器中运行: 打开该文件。你会发现在main方法的上方，VS Code 会显示Run | Debug的可点击选项。同时，编辑器的右上角也会出现一个播放 (▶️) 按钮。点击其中任意一个都可以启动应用。
   • 在文件浏览器中运行: 在左侧的文件资源管理器中，直接右键点击MySpringProjectApplication.java文件，在弹出的上下文菜单中选择运行 Java (Run Java)。

3. 项目转化为基于 Java 8 的修改方法(按需)

虽然推荐使用 Java 17 或 21，但如果你因旧有环境限制必须使用 Java 8，可以手动修改pom.xml文件。

打开项目根目录下的pom.xml文件，找到<properties>标签，将其中的<java.version>修改为1.8。

<properties><java.version>1.8</java.version></properties>

同时，你需要确保你的 Spring Boot 版本与 Java 8 兼容。Spring Boot 3.x 及以上版本要求 Java 17 或更高，因此你需要选择一个2.x.x的版本，例如2.7.18。这通常在<parent>标签中修改：

<!-- pom.xml --><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.7.18</version><relativePath/></parent>

重要：jakartavsjavax命名空间变更

这是一个非常关键的技术点。从 Spring Boot 3.0 开始，Spring 框架迁移到了 Jakarta EE 9 规范，最直观的变化就是 Java EE API 的包名从javax.*变成了jakarta.*。

• Spring Boot 3.x (Java 17+): 使用jakarta.persistence.*
• Spring Boot 2.x (Java 8/11): 使用javax.persistence.*

因此，如果你按照本节步骤降级到了 Spring Boot 2.x，在后续编写 JPA 实体类（如User实体）时，必须手动将所有import jakarta.persistence.*修改为import javax.persistence.*，否则项目将无法编译。

4. 需要手动添加的依赖

Springdoc OpenAPI并非总是在所有 Spring Initializr 版本中都作为默认选项提供。如果初始化时未能添加，你需要手动将其添加到pom.xml的<dependencies>区域。

重要提示：springdoc-openapi的版本与 Spring Boot 的版本是紧密相关的。请根据你的 Spring Boot 版本选择正确的依赖。

场景一：Spring Boot 3.x (推荐)

如果你使用的是 Spring Boot 3.x (例如3.5.3)，你需要添加v2.x.x版本的springdoc-openapi。

<!-- pom.xml --><dependencies><!-- ... 其他依赖 ... --><!-- Springdoc OpenAPI for Spring Boot 3 --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.5.0</version></dependency></dependencies>

注意: 请检查并使用最新的2.x稳定版本号。

场景二：Spring Boot 2.x (兼容旧版 Java 8)

如果你根据前面的步骤降级到了 Spring Boot 2.x (例如2.7.18)，则必须使用v1.x.x版本的springdoc-openapi，并且artifactId也不同。

<!-- pom.xml --><dependencies><!-- ... 其他依赖 ... --><!-- Springdoc OpenAPI for Spring Boot 2 --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.8.0</version></dependency></dependencies>

注意: 请检查并使用最新的1.x稳定版本号。

5. 数据库支持

接下来，我们将在src/main/resources/目录下的配置文件中添加数据库连接信息。你可以选择application.properties或application.yml格式。yml格式层级更清晰，是目前更主流的选择。

情况一：集成 MongoDB

MongoDB 的 Windows 下安装方法可见 这篇文章

确保你的pom.xml文件中包含spring-boot-starter-data-mongodb依赖。

application.properties格式配置:

# MongoDB Configuration # 使用 URI 方式连接，包含了地址、端口、数据库名等信息 spring.data.mongodb.uri=mongodb://localhost:27017/mydatabase # 如果你的 MongoDB 设置了用户名和密码，可以使用以下格式 # spring.data.mongodb.uri=mongodb://user:password@localhost:27017/mydatabase # 或者分别指定主机、端口和数据库名 # spring.data.mongodb.host=localhost # spring.data.mongodb.port=27017 # spring.data.mongodb.database=mydatabase # spring.data.mongodb.username=your_username # spring.data.mongodb.password=your_password # spring.data.mongodb.authentication-database=admin # 指定认证数据库

application.yml格式配置:

spring:data:mongodb:uri:mongodb://localhost:27017/mydatabase# 或者分别指定主机、端口和数据库名# host: localhost# port: 27017# database: mydatabase# username: your_username# password: your_password# authentication-database: admin # 指定认证数据库

authentication-database配置详解

authentication-database是一个非常重要的配置项，尤其是在需要认证的生产环境中。

• 作用: 它用于指定对哪个数据库进行用户身份验证。当你提供的username和password不是在当前连接的数据库 (mydatabase) 中创建的，而是在另一个特定的数据库（通常是admin库）中创建时，就必须设置此项。
• 常见场景: 在 MongoDB 中，管理员通常会在admin数据库中创建用户，并授予该用户访问其他一个或多个数据库的权限。在这种情况下，即使你的应用程序操作的是mydatabase，认证过程也必须在admin数据库中进行。
• 如何配置: 如果你使用独立的配置项（而非 URI），请添加spring.data.mongodb.authentication-database=admin。如果使用 URI，可以在连接字符串中添加authSource参数，例如：mongodb://user:password@localhost:27017/mydatabase?authSource=admin。

情况二：集成 MySQL

确保你的pom.xml文件中包含spring-boot-starter-data-jpa和mysql-connector-j依赖。

application.properties格式配置:

# MySQL Datasource Configuration spring.datasource.url=jdbc:mysql://localhost:3306/mydatabase?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true spring.datasource.username=root spring.datasource.password=your_password # JPA (Hibernate) Configuration # ddl-auto: # none: 不做任何操作 # validate: 校验 schema，如果实体与表结构不匹配则报错 # update: 启动时更新 schema，使其与实体匹配 # create: 每次启动时都删除并重新创建 schema # create-drop: 启动时创建，关闭时删除 spring.jpa.hibernate.ddl-auto=update spring.jpa.show-sql=true # 在控制台打印执行的 SQL 语句，方便调试

application.yml格式配置:

spring:datasource:url:jdbc:mysql://localhost:3306/mydatabase?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=trueusername:rootpassword:your_passwordjpa:hibernate:ddl-auto:updateshow-sql:true

6. 修改服务端口号

Spring Boot 内嵌的 Web 服务器（如 Tomcat）默认使用8080端口。如果该端口被占用或你希望使用其他端口，可以通过修改配置文件轻松实现。此项配置与数据库配置一样，都位于src/main/resources/目录下。

application.properties格式配置:

# Server Configuration server.port=8090

application.yml格式配置:

server:port:8090

提示: 修改端口后，所有访问地址（包括 API 文档地址）都需要使用新的端口号，例如http://localhost:8090/swagger-ui.html。

7. 搭建基础分层结构

现在，我们开始搭建项目的核心代码结构。一个良好的分层结构可以使代码更清晰、更易于维护。我们遵循Entity -> Repository -> Service -> Controller的经典模式。

首先，在src/main/java/com/example/myspringproject/目录下创建以下四个包：

• entity(或model): 存放数据实体类。
• repository: 存放数据访问接口。
• service: 存放业务逻辑代码。
• controller: 存放 API 接口。

在 VS Code 中创建包 (文件夹):

1. 在左侧的文件夹 (FOLDERS)视图中，找到并展开src/main/java/com/example/myspringproject目录。
2. 右键点击myspringproject文件夹。
3. 在弹出的菜单中选择新建文件夹 (New Folder)。
4. 输入第一个包名，例如entity，然后按 Enter。
5. 重复以上步骤，创建repository、service和controller这三个包。

创建实体层 (Entity/Model)

实体是与数据库表或文档结构对应的 Java 对象。

MongoDB 场景:

创建一个User类，使用@Document注解表示它对应 MongoDB 中的一个集合。

src/main/java/com/example/myspringproject/entity/User.java

packagecom.example.myspringproject.entity;importlombok.Data;importorg.springframework.data.annotation.Id;importorg.springframework.data.mongodb.core.mapping.Document;@Data// Lombok 注解，自动生成 Getter, Setter, toString() 等方法@Document(collection="users")// 映射到 MongoDB 中的 "users" 集合publicclassUser{@IdprivateStringid;// MongoDB 的主键通常是字符串类型privateStringusername;privateStringemail;}

MySQL 场景:

创建一个User类，使用@Entity注解表示它是一个 JPA 实体。

src/main/java/com/example/myspringproject/entity/User.java

packagecom.example.myspringproject.entity;// 重要提示:// 如果你使用的是 Spring Boot 2.x (对应 Java 8),// 需要将下面的 'jakarta.persistence' 全部替换为 'javax.persistence'importjakarta.persistence.*;importlombok.Data;@Data// Lombok 注解@Entity// 声明这是一个 JPA 实体@Table(name="users")// 映射到数据库中的 "users" 表publicclassUser{@Id@GeneratedValue(strategy=GenerationType.IDENTITY)// 主键自增策略privateLongid;// MySQL 的主键通常是 Long 类型privateStringusername;privateStringemail;}

创建数据访问层 (Repository)

Repository 层负责与数据库进行直接交互，提供基础的增删改查功能。

MongoDB 场景:

创建一个UserRepository接口，继承MongoRepository。

src/main/java/com/example/myspringproject/repository/UserRepository.java

packagecom.example.myspringproject.repository;importcom.example.myspringproject.entity.User;importorg.springframework.data.mongodb.repository.MongoRepository;importorg.springframework.stereotype.Repository;@RepositorypublicinterfaceUserRepositoryextendsMongoRepository<User,String>{// Spring Data MongoDB 会自动实现基础的 CRUD 方法// 你也可以在这里定义符合规范的自定义查询方法，例如：// Optional<User> findByUsername(String username);}

MySQL 场景:

创建一个UserRepository接口，继承JpaRepository。

src/main/java/com/example/myspringproject/repository/UserRepository.java

packagecom.example.myspringproject.repository;importcom.example.myspringproject.entity.User;importorg.springframework.data.jpa.repository.JpaRepository;importorg.springframework.stereotype.Repository;@Repository// 声明这是一个 Spring 管理的 BeanpublicinterfaceUserRepositoryextendsJpaRepository<User,Long>{// JpaRepository 已经提供了丰富的 CRUD 操作// 和分页、排序等功能。}

创建业务逻辑层 (Service)

Service 层封装了核心的业务逻辑，它调用 Repository 层来持久化数据。

Service 的代码对于 MongoDB 和 MySQL 几乎一样，唯一区别在于findUserById方法的参数类型，这取决于User实体的主键类型 (Stringfor MongoDB,Longfor MySQL)。

下面以 MongoDB 为例展示UserService的代码。对于 MySQL，只需将findUserById方法的参数id类型从String改为Long即可。

src/main/java/com/example/myspringproject/service/UserService.java

packagecom.example.myspringproject.service;importcom.example.myspringproject.entity.User;importcom.example.myspringproject.repository.UserRepository;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.stereotype.Service;@Service// 声明这是一个业务逻辑组件publicclassUserService{privatefinalUserRepositoryuserRepository;// 推荐使用构造函数注入，确保依赖的不可变性@AutowiredpublicUserService(UserRepositoryuserRepository){this.userRepository=userRepository;}/** * 创建一个新用户 * @param user 用户实体 * @return 保存后的用户实体 */publicUsercreateUser(Useruser){returnuserRepository.save(user);}/** * 根据 ID 查找用户 * @param id 用户 ID (MongoDB 使用 String, MySQL 使用 Long) * @return 用户实体，如果不存在则返回 null */publicUserfindUserById(Stringid){// MySQL 用户请将 String id 改为 Long idreturnuserRepository.findById(id).orElse(null);}}

创建表现层 (Controller)

Controller 层负责接收 HTTP 请求，调用 Service 层处理业务，并返回 HTTP 响应。

Controller 的代码在 MongoDB 和 MySQL 两种场景下几乎完全相同。唯一的区别在于getUserById方法中 ID 的类型。

下面以 MongoDB 场景为例，其中用户 ID 为String类型。如果你使用 MySQL，只需将getUserById方法的参数@PathVariable String id修改为@PathVariable Long id即可，其他部分完全相同

src/main/java/com/example/myspringproject/controller/UserController.java

packagecom.example.myspringproject.controller;importcom.example.myspringproject.entity.User;importcom.example.myspringproject.service.UserService;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.http.ResponseEntity;importorg.springframework.web.bind.annotation.*;@RestController// 结合了 @Controller 和 @ResponseBody，返回 JSON 数据@RequestMapping("/api/users")// 定义此控制器下所有 API 的基础路径publicclassUserController{privatefinalUserServiceuserService;@AutowiredpublicUserController(UserServiceuserService){this.userService=userService;}/** * 创建用户的 API 端点 * @param user 从请求体中接收的 User 对象 * @return 创建的用户信息 */@PostMappingpublicUsercreateUser(@RequestBodyUseruser){returnuserService.createUser(user);}/** * 根据 ID 查询用户的 API 端点 * @param id 从路径中获取的用户 ID (String) * @return 包含用户信息的 ResponseEntity */@GetMapping("/{id}")publicResponseEntity<User>getUserById(@PathVariableStringid){Useruser=userService.findUserById(id);if(user!=null){returnResponseEntity.ok(user);// 返回 200 OK 和用户信息}else{returnResponseEntity.notFound().build();// 返回 404 Not Found}}}

8. 生成并访问 API 文档

现在，你的项目已经准备就绪。

1. 运行项目:

   • 在 IDE 中，找到主应用程序类（MySpringProjectApplication.java），右键点击并选择 “Run”。
   • 或者在项目根目录下打开终端，执行命令mvn spring-boot:run。

2. 访问 API 文档:

   • 项目成功启动后，打开浏览器并访问：http://localhost:8080/swagger-ui.html
   • 你将看到一个由 Springdoc 生成的交互式 API 页面。

3. 测试 API:

   • 在 Swagger UI 页面，你可以看到POST /api/users和GET /api/users/{id}两个端点。
   • 展开POST端点，点击 “Try it out”，在请求体中输入 JSON 数据（如{"username": "Alice", "email": "alice@example.com"}），然后点击 “Execute”。
   • 复制响应中返回的 ID，然后使用GET端点进行查询。

至此，你已经成功地创建了一个结构完整、包含数据库集成和 API 文档的 Spring Boot 后端项目。以此为基础，你可以继续扩展更复杂的业务功能。