Spring Boot 基础开发：实现 RESTful API 开发

Lsland..2025-02-01 14:17
前言

在现代 Web 开发中，RESTful API 已经成为前后端分离架构的核心。Spring Boot 提供了强大的支持，使得 RESTful API 的开发变得高效且简洁。本文将从以下几个方面详细讲解如何在 Spring Boot 中实现 RESTful API 开发：

  1. @RestController 设计 API：简化 Controller 的编写
  2. HTTP 状态码与响应封装：了解常见状态码及其使用场景
  3. Swagger3 集成：生成接口文档便于开发和测试

通过本文的学习，你将能够快速上手 Spring Boot 的 RESTful API 开发，并掌握一些实用技巧。

一、@RestController 设计 API：简化 Controller 的编写

1. 什么是 RESTful API？

REST（Representational State Transfer）是一种基于 HTTP 协议的设计风格，旨在通过标准的 HTTP 方法（如 GET、POST、PUT、DELETE）对资源进行操作。RESTful API 是基于 REST 风格设计的接口。

2. Spring Boot 中的 @RestController

@RestController 是 Spring Boot 提供的一个组合注解，结合了 @Controller 和 @ResponseBody 的功能。它简化了 Controller 的编写，使得返回的数据直接作为 HTTP 响应体返回。

示例代码：

java 复制代码 
import org.springframework.web.bind.annotation.GetMapping; 
import org.springframework.web.bind.annotation.RequestMapping; 
import org.springframework.web.bind.annotation.RestController; 
 
@RestController 
@RequestMapping("/api/users")
public class UserController {
 
    @GetMapping 
    public String getUsers() {
        return "Hello, RESTful API!";
    }
}
  • @RestController：标识这是一个 REST 控制器。
  • @RequestMapping：定义请求映射路径。
  • @GetMapping：处理 GET 请求。
3. 常见 HTTP 方法映射

Spring 提供了多种注解来处理不同的 HTTP 方法：

HTTP 方法 对应注解 描述
GET @GetMapping 获取资源
POST @PostMapping 创建资源
PUT @PutMapping 更新资源
DELETE @DeleteMapping 删除资源
PATCH @PatchMapping 部分更新资源

示例代码：

java 复制代码 
@RestController 
@RequestMapping("/api/books")
public class BookController {
 
    @GetMapping 
    public String getAllBooks() {
        return "Get all books";
    }
 
    @PostMapping 
    public String createBook() {
        return "Create a new book";
    }
 
    @PutMapping("/{id}")
    public String updateBook(@PathVariable Long id) {
        return "Update book with ID: " + id;
    }
 
    @DeleteMapping("/{id}")
    public String deleteBook(@PathVariable Long id) {
        return "Delete book with ID: " + id;
    }
}
4. @PathVariable 和 @RequestParam

在 RESTful API 中，我们经常需要从 URL 路径或查询参数中获取参数。

  • @PathVariable：用于获取路径变量。
  • @RequestParam：用于获取查询参数。

示例代码：

java 复制代码 
@RestController 
@RequestMapping("/api/users")
public class UserController {
 
    @GetMapping("/{id}")
    public String getUserById(@PathVariable Long id) {
        return "Get user with ID: " + id;
    }
 
    @GetMapping 
    public String getUsersByName(@RequestParam String name) {
        return "Get users named: " + name;
    }
}

二、HTTP 状态码与响应封装

1. HTTP 状态码

HTTP 状态码是服务器对客户端请求的响应状态的描述。常见的状态码包括：

状态码 描述
200 OK 请求成功
201 Created 资源创建成功
400 Bad Request 请求错误
404 Not Found 资源未找到
500 Internal Server Error 服务器内部错误

示例代码：

java 复制代码 
import org.springframework.http.HttpStatus; 
import org.springframework.http.ResponseEntity; 
import org.springframework.web.bind.annotation.GetMapping; 
import org.springframework.web.bind.annotation.RequestMapping; 
import org.springframework.web.bind.annotation.RestController; 
 
@RestController 
@RequestMapping("/api/status")
public class StatusController {
 
    @GetMapping("/ok")
    public ResponseEntity<String> ok() {
        return ResponseEntity.ok("Request  successful");
    }
 
    @GetMapping("/not-found")
    public ResponseEntity<String> notFound() {
        return ResponseEntity.notFound().build(); 
    }
 
    @GetMapping("/error")
    public ResponseEntity<String> error() {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR) 
                             .body("Internal server error");
    }
}
2. 响应封装

为了统一 API 的响应格式，通常会自定义一个响应类（如 ApiResponse），并在 Controller 中使用 ResponseEntity 进行封装。

自定义响应类：

java 复制代码 
public class ApiResponse<T> {
    
    private int code;
    private String message;
    private T data;
 
    // Constructor, getters, and setters 
}

Controller 示例：

java 复制代码 
@RestController 
@RequestMapping("/api/books")
public class BookController {
 
    @GetMapping("/{id}")
    public ResponseEntity<ApiResponse<Book>> getBookById(@PathVariable Long id) {
        Book book = ...; // 查询书籍 
        ApiResponse<Book> response = new ApiResponse<>(200, "Success", book);
        return ResponseEntity.ok(response); 
    }
 
    @PostMapping 
    public ResponseEntity<ApiResponse<Book>> createBook(@RequestBody Book book) {
        Book savedBook = ...; // 保存书籍 
        ApiResponse<Book> response = new ApiResponse<>(201, "Created", savedBook);
        return ResponseEntity.status(HttpStatus.CREATED).body(response); 
    }
}
3. 响应封装的好处
  • 统一格式：前后端通信格式统一，便于开发和维护。
  • 错误处理：统一处理异常和错误信息。
  • 扩展性：方便后续增加新的字段（如分页信息）。

三、Swagger3 集成：生成接口文档

Swagger 是一个流行的 API 文档生成工具，可以帮助开发者快速生成接口文档，并提供在线测试功能。

1. 引入 Swagger3 依赖

在 pom.xml 中添加 Swagger3 依赖：

XML 复制代码 
<dependency>
    <groupId>io.springfox</groupId> 
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
2. 配置 Swagger

创建一个配置类：

java 复制代码 
import org.springframework.context.annotation.Bean; 
import org.springframework.context.annotation.Configuration; 
import springfox.documentation.builders.ApiInfoBuilder; 
import springfox.documentation.spi.DocumentationType; 
import springfox.documentation.spring.web.plugins.Docket; 
import springfox.documentation.swagger2.annotations.EnableSwagger2; 
 
@Configuration 
@EnableSwagger2 
public class SwaggerConfig {
 
    @Bean 
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("My RESTful API")
                        .description("A sample API for learning Swagger3 integration.")
                        .version("1.0.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.any()) 
                .paths(PathSelectors.any()) 
                .build();
    }
}
3. 启动 Swagger UI

配置完成后，启动应用并访问以下路径即可查看 Swagger UI：

http://localhost:8080/swagger-ui.html
4. 使用 Swagger 注解增强文档

通过 Swagger 提供的注解（如 @Api、@ApiOperation、@ApiParam），可以进一步丰富接口文档。

示例代码：

java 复制代码 
import io.swagger.annotations.Api; 
import io.swagger.annotations.ApiOperation; 
import io.swagger.annotations.ApiParam; 
import org.springframework.web.bind.annotation.GetMapping; 
import org.springframework.web.bind.annotation.PathVariable; 
import org.springframework.web.bind.annotation.RequestMapping; 
import org.springframework.web.bind.annotation.RestController; 
 
@RestController 
@RequestMapping("/api/users")
@Api(tags = "User API", description = "Operations related to users")
public class UserController {
 
    @GetMapping("/{id}")
    @ApiOperation(value = "Get user by ID", notes = "Returns a single user by their ID")
    public ResponseEntity<User> getUserById(
            @ApiParam(value = "User ID", required = true) @PathVariable Long id) {
        User user = ...; // 查询用户 
        return ResponseEntity.ok(user); 
    }
}
5. Swagger 的好处
  • 自动化文档：无需手动编写文档，提高开发效率。
  • 在线测试：通过 Swagger UI 可以直接测试接口。
  • 团队协作：方便前后端团队沟通和协作。

四、实战案例：完整 RESTful API 示例

1. 创建一个简单的 Book 管理系统

实体类（Book.java ）：

java 复制代码 
public class Book {
    
    private Long id;
    private String title;
    private String author;
 
    // Constructor, getters, and setters 
}

Controller（BookController.java ）：

java 复制代码 
import org.springframework.http.HttpStatus; 
import org.springframework.http.ResponseEntity; 
import org.springframework.web.bind.annotation.*; 
 
@RestController 
@RequestMapping("/api/books")
public class BookController {
 
    // 模拟数据存储 
    private static List<Book> books = new ArrayList<>();
 
    static {
        books.add(new  Book(1L, "Java Programming", "John Doe"));
        books.add(new  Book(2L, "Python Basics", "Jane Smith"));
    }
 
    @GetMapping 
    @ApiOperation(value = "Get all books", notes = "Returns a list of all books")
    public ResponseEntity<List<Book>> getAllBooks() {
        return ResponseEntity.ok(books); 
    }
 
    @GetMapping("/{id}")
    @ApiOperation(value = "Get book by ID", notes = "Returns a single book by its ID")
    public ResponseEntity<Book> getBookById(@ApiParam(value = "Book ID", required = true) @PathVariable Long id) {
        Book book = books.stream() 
                          .filter(b -> b.getId().equals(id)) 
                          .findFirst()
                          .orElse(null);
        if (book != null) {
            return ResponseEntity.ok(book); 
        } else {
            return ResponseEntity.notFound().build(); 
        }
    }
 
    @PostMapping 
    @ApiOperation(value = "Create a new book", notes = "Creates a new book and returns it")
    public ResponseEntity<Book> createBook(@ApiParam(value = "Book object") @RequestBody Book book) {
        book.setId(books.size()  + 1L);
        books.add(book); 
        return ResponseEntity.status(HttpStatus.CREATED).body(book); 
    }
 
    @PutMapping("/{id}")
    @ApiOperation(value = "Update an existing book", notes = "Updates an existing book and returns it")
    public ResponseEntity<Book> updateBook(
            @ApiParam(value = "Book ID", required = true) @PathVariable Long id,
            @ApiParam(value = "Updated book object") @RequestBody Book updatedBook) {
 
        int index = books.indexOf(books.stream() 
                                      .filter(b -> b.getId().equals(id)) 
                                      .findFirst()
                                      .orElse(null));
        if (index != -1) {
            updatedBook.setId(id); 
            books.set(index,  updatedBook);
            return ResponseEntity.ok(updatedBook); 
        } else {
            return ResponseEntity.notFound().build(); 
        }
    }
 
    @DeleteMapping("/{id}")
    @ApiOperation(value = "Delete a book", notes = "Deletes a book by its ID")
    public ResponseEntity<Void> deleteBook(@ApiParam(value = "Book ID", required = true) @PathVariable Long id) {
        books.removeIf(b  -> b.getId().equals(id)); 
        return ResponseEntity.noContent().build(); 
    }
}
2. 测试接口

启动应用后，访问 http://localhost:8080/swagger-ui.html ，可以看到所有定义的接口，并可以直接进行在线测试。

相关推荐
bing_15835 分钟前
Spring的设计理念之IOC
java·后端·spring
码界筑梦坊1 小时前
基于Flask的全国奶茶饮品加盟及门店数据分析系统的设计与实现
后端·python·flask·毕业设计
SomeB1oody2 小时前
【Rust】18.2. 可辩驳性：模式是否会无法匹配
开发语言·后端·rust
python算法(魔法师版)2 小时前
Spring Boot深度开发实践：从高效开发到生产级部署
开发语言·vue.js·spring boot·前端框架·ecmascript
扎量丙不要犟2 小时前
rust跨平台调用动态库
开发语言·后端·rust
是小崔啊3 小时前
Spring Boot - 数据库集成06 - 集成ElasticSearch
数据库·spring boot·elasticsearch
程序员勋勋13 小时前
【GoLang】利用validator包实现服务端参数校验时自定义错误信息
后端·golang·web
刘大浪3 小时前
如何获取Springboot项目运行路径 （idea 启动以及打包为jar均可） 针对无服务器容器新建上传文件路径（适用于win 与 linunix）
spring boot·intellij-idea·jar
jimiStephen3 小时前
Go-并行编程新手指南
开发语言·后端·golang
热门推荐
01【deepseek】deepseek-r1本地部署-第一步：下载LM Studio02新鲜速递：DeepSeek-R1开源大模型本地部署实战—Ollama + MaxKB 搭建RAG检索增强生成应用03Dell服务器升级ubuntu 22.04失败解决04将DeepSeek接入Word，打造AI办公助手05SQL从入门到实战-206半导体应用系统一些小知识收集(strip&wafer mapping,EAP&scada)07DeepSeek r1本地安装全指南08xgboost: Why not implement distributed XGBoost on top of spark09密码学原理技术-第六章-introduction to pulibc-key cryptography10使用Ollama 在Ubuntu运行deepseek大模型：以DeepSeek-coder为例