第一个 Spring Boot 应用示例：从零构建 RESTful 接口服务

最新推荐文章于 2026-02-11 17:11:41 发布

原创最新推荐文章于 2026-02-11 17:11:41 发布 · 844 阅读

17 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

Spring Boot开发秘籍

在 Java 开发领域，Spring Boot 凭借其 "约定优于配置" 的理念和强大的自动配置能力，已成为构建微服务和企业级应用的首选框架。对于刚接触 Spring 生态的开发者而言，亲手搭建并运行第一个 Spring Boot 应用是理解其核心原理的最佳途径。本文将以一个完整的 RESTful 接口服务为例，从项目创建到接口测试，带你逐步实现一个能处理 HTTP 请求、返回 JSON 数据的 Spring Boot 应用，帮助你掌握 Spring Boot 开发的基本流程和核心技巧。

一、项目初始化：基于 Spring Initializr 的基础配置

构建 Spring Boot 应用的第一步是创建规范的项目结构，我们继续使用 Spring Initializr 工具（https://start.spring .io/）来完成初始化工作。相比手动搭建项目，这种方式能确保依赖版本兼容性和目录结构规范性，为后续开发奠定良好基础。

核心依赖选择

对于基础 RESTful 接口服务，需要重点添加以下核心依赖：

Spring Web：这是构建 Web 应用的核心依赖，包含了 Spring MVC 框架和嵌入式 Tomcat 服务器，能实现 HTTP 请求处理、路由映射等核心功能。

Lombok：通过注解简化 Java 类的代码编写，减少 getter、setter 等模板代码，提高开发效率。

Spring Boot DevTools：提供热部署功能，修改代码后无需重启应用即可生效，显著提升开发体验。

在 Spring Initializr 的依赖搜索框中输入上述依赖名称并勾选，工具会自动处理依赖间的版本关系。建议 Spring Boot 版本选择 3.2.x 的 RELEASE 版本，确保稳定性和安全性。

项目元数据配置

在基础配置区域，按以下规范设置项目元数据：

Group：填写组织域名反转（如 com.example）

Artifact：设置为 "first-springboot-app" 作为项目标识

Name：保持与 Artifact 一致便于识别

Package Name：默认使用 "com.example.firstspringbootapp"

Java Version：选择 17（Spring Boot 3.x 的最低要求）

Packaging：选择 Jar（Spring Boot 推荐的打包方式）

完成配置后点击 "Generate" 按钮下载项目压缩包，解压后即可得到标准的 Spring Boot 项目结构。

二、项目结构解析：理解核心目录与文件

成功生成的项目包含清晰的目录层次，理解各目录的作用是规范开发的基础。展开项目文件夹后，核心结构如下：

first-springboot-app/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           └── firstspringbootapp/
│   │   │               ├── controller/      // 控制器目录
│   │   │               ├── model/           // 实体类目录
│   │   │               └── FirstSpringbootAppApplication.java  // 启动类
│   │   └── resources/
│   │       ├── application.properties      // 配置文件
│   │       ├── static/                     // 静态资源目录
│   │       └── templates/                  // 模板文件目录
│   └── test/                               // 测试代码目录
└── pom.xml                                 // Maven配置文件

其中几个关键文件需要特别关注：

FirstSpringbootAppApplication.java：应用程序入口类，包含@SpringBootApplication注解，这是 Spring Boot 的核心注解，整合了自动配置、组件扫描等功能。

application.properties：全局配置文件，可设置服务器端口、日志级别等配置项。

pom.xml：Maven 依赖管理文件，Spring Boot 通过<parent>标签引入 spring-boot-starter-parent，实现依赖版本的统一管理。

三、核心代码实现：构建 RESTful 接口

我们将实现一个简单的用户管理接口，包含用户信息的查询、创建功能，以此展示 Spring Boot 处理 HTTP 请求的基本方式。

创建实体类

在com.example.firstspringbootapp.model包下创建User实体类，使用 Lombok 的@Data注解简化代码：

package com.example.firstspringbootapp.model;

import lombok.Data;

@Data

public class User {

private Long id;

private String username;

private String email;

private Integer age;

}

@Data注解会自动生成 getter、setter、toString 等方法，大幅减少模板代码。

实现控制器

在com.example.firstspringbootapp.controller包下创建UserController控制器类，处理 HTTP 请求：

package com.example.firstspringbootapp.controller;

import com.example.firstspringbootapp.model.User;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;
import java.util.concurrent.atomic.AtomicLong;

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

    // 内存存储用户数据
    private final ConcurrentMap<Long, User> userMap = new ConcurrentHashMap<>();
    private final AtomicLong idGenerator = new AtomicLong(1);

    // 获取所有用户
    @GetMapping
    public List<User> getAllUsers() {
        return new ArrayList<>(userMap.values());
    }

    // 根据ID获取用户
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return userMap.get(id);
    }

    // 创建新用户
    @PostMapping
    public User createUser(@RequestBody User user) {
        Long id = idGenerator.getAndIncrement();
        user.setId(id);
        userMap.put(id, user);
        return user;
    }
}

上述代码中包含几个核心知识点：

@RestController：组合了@Controller和@ResponseBody注解，表明该类是控制器且所有方法返回 JSON 数据。

@RequestMapping("/api/users")：指定该控制器的基础路径。

@GetMapping、@PostMapping：分别处理 GET 和 POST 请求，是@RequestMapping的简化形式。

@PathVariable：获取 URL 路径中的参数值。

@RequestBody：接收 HTTP 请求体中的 JSON 数据并转换为 Java 对象。

四、应用配置与运行

为了更好地控制应用行为，我们需要对应用进行基础配置并学习如何运行 Spring Boot 应用。

基础配置调整

打开src/main/resources/application.properties文件，添加以下配置：

# 设置服务器端口
server.port=8081

# 设置日志级别
logging.level.org.springframework.web=INFO
logging.level.com.example.firstspringbootapp=DEBUG

这些配置将服务器端口从默认的 8080 改为 8081，并调整了日志输出级别，便于开发调试。

应用启动方式

Spring Boot 应用有多种启动方式，适合不同的场景：

IDE 启动：在 FirstSpringbootAppApplication 类上右键选择 "Run" 或 "Debug"，这是开发阶段最常用的方式，支持断点调试和热部署。

Maven 命令启动：在项目根目录执行以下命令：

mvn spring-boot:run

这种方式需要配置好 Maven 环境变量，适合没有 IDE 的场景。

打包运行：先打包生成 Jar 文件，再执行 Jar 文件：

mvn package

java -jar target/first-springboot-app-0.0.1-SNAPSHOT.jar

这是生产环境常用的部署方式。

启动成功后，控制台会输出类似以下的日志信息：

2024-05-20 15:30:00.123 INFO 12345 --- [ restartedMain] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port 8081 (http) with context path ''

2024-05-20 15:30:00.135 INFO 12345 --- [ restartedMain] c.e.f.FirstSpringbootAppApplication : Started FirstSpringbootAppApplication in 2.345 seconds (process running for 3.456)

五、接口测试：验证应用功能

应用启动后，我们需要验证接口是否正常工作。推荐使用 Postman 或 curl 工具进行测试。

测试创建用户接口

发送 POST 请求到http://localhost:8081/api/users，请求体为 JSON 格式的用户数据：

{

"username": "张三",

"email": "zhangsan@example.com",

"age": 25

}

成功响应会返回包含 ID 的用户信息：

{

"id": 1,

"username": "张三",

"email": "zhangsan@example.com",

"age": 25

}

测试查询用户接口

发送 GET 请求到http://localhost:8081/api/users，会返回所有用户列表：

[

{

"id": 1,

"username": "张三",

"email": "zhangsan@example.com",

"age": 25

}

]

发送 GET 请求到http://localhost:8081/api/users/1，会返回 ID 为 1 的用户信息。

六、单元测试编写：确保代码质量

Spring Boot 提供了强大的测试支持，我们为 UserController 编写单元测试，确保接口功能稳定。

在src/test/java/com/example/firstspringbootapp/controller目录下创建UserControllerTest类：

package com.example.firstspringbootapp.controller;

import com.example.firstspringbootapp.model.User;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@SpringBootTest
@AutoConfigureMockMvc
public class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private ObjectMapper objectMapper;

    @Test
    public void testCreateAndGetUser() throws Exception {
        // 创建测试用户
        User user = new User();
        user.setUsername("测试用户");
        user.setEmail("test@example.com");
        user.setAge(30);

        // 测试创建用户接口
        mockMvc.perform(post("/api/users")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content(objectMapper.writeValueAsString(user)))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.username").value("测试用户"))
                .andExpect(jsonPath("$.id").value(1));

        // 测试查询用户接口
        mockMvc.perform(get("/api/users/1"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.email").value("test@example.com"));
    }
}

运行测试类，Spring Boot 会启动测试容器并执行测试方法。@SpringBootTest注解用于启动 Spring 上下文，@AutoConfigureMockMvc自动配置 MockMvc 用于模拟 HTTP 请求。

七、项目优化与扩展建议

完成基础功能后，我们可以对项目进行优化，使其更符合生产环境要求：

配置文件优化

将单一配置文件拆分为多环境配置：

application-dev.properties：开发环境配置

application-prod.properties：生产环境配置

通过spring.profiles.active=dev指定激活的环境

异常处理

添加全局异常处理器，统一处理接口异常：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<String> handleResourceNotFound(ResourceNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

添加接口文档

集成 SpringDoc OpenAPI 生成接口文档，在 pom.xml 中添加依赖：

<dependency>

<groupId>org.springdoc</groupId>

<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>

<version>2.2.0</version>

</dependency>

启动应用后访问http://localhost:8081/swagger-ui.html即可查看接口文档。

八、总结与进阶方向

通过本文的学习，你已成功构建并运行了第一个 Spring Boot 应用，掌握了从项目初始化、代码编写到接口测试的完整流程。这个简单的示例涵盖了 Spring Boot 的核心特性：自动配置、依赖管理、RESTful 接口开发等。

作为进阶学习方向，建议深入研究以下内容：

Spring Boot 自动配置原理，理解@Conditional注解家族的作用

数据持久化，集成 Spring Data JPA 或 MyBatis 操作数据库

安全认证，使用 Spring Security 保护接口访问

服务监控，集成 Spring Boot Actuator 实现应用监控

Spring Boot 的学习是一个循序渐进的过程，从简单应用开始，逐步引入更多组件和特性，你将能构建出更强大、更稳定的企业级应用。记住，实践是掌握 Spring Boot 最好的方式，不断编写代码、解决问题，才能真正理解其设计思想和最佳实践。

标签

#spring boot #restful #后端