Spring Boot 全方位指南从项目初始化到分层架构搭建本教程旨在引导 Java 开发者特别是 Spring Boot 的初学者从零开始创建一个结构清晰、功能完备的后端项目。我们将从项目初始化开始详细讲解每一项依赖的作用然后配置数据库并最终搭建起经典的 MVCModel-View-Controller分层架构。目录1. 依赖讲解通用依赖数据库相关依赖2. 初始化项目步骤详细附录在 Visual Studio Code 中打开和运行项目3. 项目转化为基于 Java 8 的修改方法(按需)重要jakartavsjavax命名空间变更4. 需要手动添加的依赖场景一Spring Boot 3.x (推荐)场景二Spring Boot 2.x (兼容旧版 Java 8)5. 数据库支持情况一集成 MongoDB情况二集成 MySQL6. 修改服务端口号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 WebLombokSpring Boot DevToolsSpringdoc 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 项目。安装必备扩展:在开始之前请确保你已经在 VS Code 中安装了 Java 开发的必备扩展。在扩展市场中搜索并安装以下扩展包它提供了对 Java 开发的全面支持Extension Pack for Java(来自 Microsoft)打开项目:将从 Spring Initializr 下载的压缩包解压。然后在 VS Code 中通过菜单栏的文件 (File)打开文件夹... (Open Folder...)选择刚刚解压的项目根目录。项目加载:VS Code 会自动识别这是一个基于 Maven 的 Java 项目。右下角会弹出提示询问你是否信任此工作区请选择“是”。之后Java 扩展会自动开始下载项目所需的依赖项 (Dependencies)。你可以在左侧边栏的JAVA PROJECTS视图中看到项目的结构和依赖加载进度。运行项目:项目依赖加载完毕后请在文件资源管理器中找到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。propertiesjava.version1.8/java.version/properties同时你需要确保你的 Spring Boot 版本与 Java 8 兼容。Spring Boot 3.x 及以上版本要求 Java 17 或更高因此你需要选择一个2.x.x的版本例如2.7.18。这通常在parent标签中修改!-- pom.xml --parentgroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-parent/artifactIdversion2.7.18/versionrelativePath//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 --dependencygroupIdorg.springdoc/groupIdartifactIdspringdoc-openapi-starter-webmvc-ui/artifactIdversion2.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 --dependencygroupIdorg.springdoc/groupIdartifactIdspringdoc-openapi-ui/artifactIdversion1.8.0/version/dependency/dependencies注意: 请检查并使用最新的1.x稳定版本号。5. 数据库支持接下来我们将在src/main/resources/目录下的配置文件中添加数据库连接信息。你可以选择application.properties或application.yml格式。yml格式层级更清晰是目前更主流的选择。情况一集成 MongoDBMongoDB 的 Windows 下安装方法可见 这篇文章确保你的pom.xml文件中包含spring-boot-starter-data-mongodb依赖。application.properties格式配置:# MongoDB Configuration # 使用 URI 方式连接包含了地址、端口、数据库名等信息 spring.data.mongodb.urimongodb://localhost:27017/mydatabase # 如果你的 MongoDB 设置了用户名和密码可以使用以下格式 # spring.data.mongodb.urimongodb://user:passwordlocalhost:27017/mydatabase # 或者分别指定主机、端口和数据库名 # spring.data.mongodb.hostlocalhost # spring.data.mongodb.port27017 # spring.data.mongodb.databasemydatabase # spring.data.mongodb.usernameyour_username # spring.data.mongodb.passwordyour_password # spring.data.mongodb.authentication-databaseadmin # 指定认证数据库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-databaseadmin。如果使用 URI可以在连接字符串中添加authSource参数例如mongodb://user:passwordlocalhost:27017/mydatabase?authSourceadmin。情况二集成 MySQL确保你的pom.xml文件中包含spring-boot-starter-data-jpa和mysql-connector-j依赖。application.properties格式配置:# MySQL Datasource Configuration spring.datasource.urljdbc:mysql://localhost:3306/mydatabase?useSSLfalseserverTimezoneUTCallowPublicKeyRetrievaltrue spring.datasource.usernameroot spring.datasource.passwordyour_password # JPA (Hibernate) Configuration # ddl-auto: # none: 不做任何操作 # validate: 校验 schema如果实体与表结构不匹配则报错 # update: 启动时更新 schema使其与实体匹配 # create: 每次启动时都删除并重新创建 schema # create-drop: 启动时创建关闭时删除 spring.jpa.hibernate.ddl-autoupdate spring.jpa.show-sqltrue # 在控制台打印执行的 SQL 语句方便调试application.yml格式配置:spring:datasource:url:jdbc:mysql://localhost:3306/mydatabase?useSSLfalseserverTimezoneUTCallowPublicKeyRetrievaltrueusername:rootpassword:your_passwordjpa:hibernate:ddl-auto:updateshow-sql:true6. 修改服务端口号Spring Boot 内嵌的 Web 服务器如 Tomcat默认使用8080端口。如果该端口被占用或你希望使用其他端口可以通过修改配置文件轻松实现。此项配置与数据库配置一样都位于src/main/resources/目录下。application.properties格式配置:# Server Configuration server.port8090application.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 中创建包 (文件夹):在左侧的文件夹 (FOLDERS)视图中找到并展开src/main/java/com/example/myspringproject目录。右键点击myspringproject文件夹。在弹出的菜单中选择新建文件夹 (New Folder)。输入第一个包名例如entity然后按 Enter。重复以上步骤创建repository、service和controller这三个包。创建实体层 (Entity/Model)实体是与数据库表或文档结构对应的 Java 对象。MongoDB 场景:创建一个User类使用Document注解表示它对应 MongoDB 中的一个集合。src/main/java/com/example/myspringproject/entity/User.javapackagecom.example.myspringproject.entity;importlombok.Data;importorg.springframework.data.annotation.Id;importorg.springframework.data.mongodb.core.mapping.Document;Data// Lombok 注解自动生成 Getter, Setter, toString() 等方法Document(collectionusers)// 映射到 MongoDB 中的 users 集合publicclassUser{IdprivateStringid;// MongoDB 的主键通常是字符串类型privateStringusername;privateStringemail;}MySQL 场景:创建一个User类使用Entity注解表示它是一个 JPA 实体。src/main/java/com/example/myspringproject/entity/User.javapackagecom.example.myspringproject.entity;// 重要提示:// 如果你使用的是 Spring Boot 2.x (对应 Java 8),// 需要将下面的 jakarta.persistence 全部替换为 javax.persistenceimportjakarta.persistence.*;importlombok.Data;Data// Lombok 注解Entity// 声明这是一个 JPA 实体Table(nameusers)// 映射到数据库中的 users 表publicclassUser{IdGeneratedValue(strategyGenerationType.IDENTITY)// 主键自增策略privateLongid;// MySQL 的主键通常是 Long 类型privateStringusername;privateStringemail;}创建数据访问层 (Repository)Repository 层负责与数据库进行直接交互提供基础的增删改查功能。MongoDB 场景:创建一个UserRepository接口继承MongoRepository。src/main/java/com/example/myspringproject/repository/UserRepository.javapackagecom.example.myspringproject.repository;importcom.example.myspringproject.entity.User;importorg.springframework.data.mongodb.repository.MongoRepository;importorg.springframework.stereotype.Repository;RepositorypublicinterfaceUserRepositoryextendsMongoRepositoryUser,String{// Spring Data MongoDB 会自动实现基础的 CRUD 方法// 你也可以在这里定义符合规范的自定义查询方法例如// OptionalUser findByUsername(String username);}MySQL 场景:创建一个UserRepository接口继承JpaRepository。src/main/java/com/example/myspringproject/repository/UserRepository.javapackagecom.example.myspringproject.repository;importcom.example.myspringproject.entity.User;importorg.springframework.data.jpa.repository.JpaRepository;importorg.springframework.stereotype.Repository;Repository// 声明这是一个 Spring 管理的 BeanpublicinterfaceUserRepositoryextendsJpaRepositoryUser,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.javapackagecom.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.userRepositoryuserRepository;}/** * 创建一个新用户 * 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.javapackagecom.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.userServiceuserService;}/** * 创建用户的 API 端点 * param user 从请求体中接收的 User 对象 * return 创建的用户信息 */PostMappingpublicUsercreateUser(RequestBodyUseruser){returnuserService.createUser(user);}/** * 根据 ID 查询用户的 API 端点 * param id 从路径中获取的用户 ID (String) * return 包含用户信息的 ResponseEntity */GetMapping(/{id})publicResponseEntityUsergetUserById(PathVariableStringid){UseruseruserService.findUserById(id);if(user!null){returnResponseEntity.ok(user);// 返回 200 OK 和用户信息}else{returnResponseEntity.notFound().build();// 返回 404 Not Found}}}8. 生成并访问 API 文档现在你的项目已经准备就绪。运行项目:在 IDE 中找到主应用程序类MySpringProjectApplication.java右键点击并选择 “Run”。或者在项目根目录下打开终端执行命令mvn spring-boot:run。访问 API 文档:项目成功启动后打开浏览器并访问http://localhost:8080/swagger-ui.html你将看到一个由 Springdoc 生成的交互式 API 页面。测试 API:在 Swagger UI 页面你可以看到POST /api/users和GET /api/users/{id}两个端点。展开POST端点点击 “Try it out”在请求体中输入 JSON 数据如{username: Alice, email: aliceexample.com}然后点击 “Execute”。复制响应中返回的 ID然后使用GET端点进行查询。至此你已经成功地创建了一个结构完整、包含数据库集成和 API 文档的 Spring Boot 后端项目。以此为基础你可以继续扩展更复杂的业务功能。