当前位置： 首页 > article >正文

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

article 2025/2/1 15:45:07
前言

在现代 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 响应体返回。

示例代码：

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部分更新资源

 示例代码：

@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：用于获取查询参数。

 示例代码：

@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服务器内部错误

示例代码：

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 进行封装。

自定义响应类：

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

Controller 示例：

@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 依赖：

<dependency>
    <groupId>io.springfox</groupId> 
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

 

2. 配置 Swagger

创建一个配置类：

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），可以进一步丰富接口文档。

示例代码：

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 ）：

public class Book {
    
    private Long id;
    private String title;
    private String author;
 
    // Constructor, getters, and setters 
}

 Controller（BookController.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 ，可以看到所有定义的接口，并可以直接进行在线测试。

 

 


http://www.kler.cn/a/527320.html

相关文章：

  • 第11章：根据 ShuffleNet V2 迁移学习医学图像分类任务：甲状腺结节检测
  • UE5 特效
  • 使用 cmake
  • AI常见的算法和例子
  • Linux《基础指令》
  • Rust：Rhai脚本编程示例
  • 【算法设计与分析】实验4：动态规划—0/1背包问题
  • Baklib赋能企业实现高效数字化内容管理提升竞争力
  • 【基于SprintBoot+Mybatis+Mysql】电脑商城项目之用户注册
  • 第05章 16 Implicit Function应用举例
  • 【蓝桥杯】43697.机器人塔
  • origin如何在已经画好的图上修改数据且不改变原图像的画风和格式
  • 知识库管理如何推动企业数字化转型与创新发展的深层次探索
  • 智联出行公司布局中国市场，引领绿色出行新潮流
  • riscv xv6学习笔记
  • 使用vhd虚拟磁盘安装两个win10系统
  • cmd命令行无法进入D：盘怎么办
  • 论文阅读笔记 —— 英文论文常见缩写及含义
  • 优盘恢复原始容量工具
  • 为AI聊天工具添加一个知识系统 之73 详细设计之14 正则表达式 之1
  • deepseek本地部署使用教程
  • three.js+WebGL踩坑经验合集(6.1):负缩放，负定矩阵和行列式的关系（2D版本）
  • 可被electron等调用的Qt截图-录屏工具【源码开放】
  • 根据每月流量和市场份额排名前20 的AI工具列表
  • langgraph实现 handsoff between agents 模式 (1)
  • 自定义数据集 使用paddlepaddle框架实现逻辑回归并保存模型，然后保存模型后再加载模型进行预测