---

一、Spring Boot Web 基礎配置

1.1 Web 起步依賴（spring-boot-starter-web 導入與核心組件）

在 Spring Boot 項目中，若要快速搭建 Web 應用，spring-boot-starter-web起步依賴必不可少。以 Maven 項目為例，在pom.xml文件的<dependencies>標簽內添加如下依賴：

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId>
</dependency>

當我們添加此依賴后，Maven 會利用依賴傳遞特性，自動引入 Web 開發所需的眾多依賴。其中核心組件之一便是 Spring MVC，它是 Spring 框架中用于構建 Web 應用的模塊，基于 MVC（Model - View - Controller）設計模式。在 Spring MVC 中，Controller 負責處理用戶請求，Model 封裝業務數據，View 負責展示數據給用戶。例如，我們定義一個 Controller 來處理用戶對首頁的請求：

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;@Controller
public class HomeController {@GetMapping("/")public String home(Model model) {model.addAttribute("message", "歡迎來到我的Spring Boot應用");return "index";}
}

上述代碼中，@GetMapping(“/”)注解表示當用戶訪問根路徑時，會調用home方法，該方法將數據添加到Model中，并返回視圖名index，Spring MVC 會根據視圖解析器找到對應的視圖頁面展示給用戶。spring-boot-starter-web還引入了 Tomcat 作為默認的嵌入式 Web 服務器，使得我們無需額外配置和部署外部 Web 服務器，就能快速啟動并運行 Web 應用。

1.2 內置服務器配置（Tomcat 端口、線程池、連接超時設置）

Spring Boot 默認使用 Tomcat 作為內置服務器，默認端口為 8080。若要修改端口，在application.properties文件中添加如下配置即可：

server.port=8081

或者在application.yml文件中配置：

server:port: 8081

合理配置 Tomcat 線程池參數對于提升應用的并發處理能力至關重要。主要參數包括：

• server.tomcat.max-threads：最大線程數，默認值為 200，即 Tomcat 可同時處理的最大線程數量。例如，在高并發場景下，若發現線程數經常達到上限，導致請求處理緩慢，可以適當增大此值，如設置為 500。在application.yml中的配置如下：

server:tomcat:max-threads: 500

• server.tomcat.min-spare-threads：最小空閑線程數，默認值為 10 ，Tomcat 啟動時初始化的線程數，即使沒有請求時也會保留這些線程，以便快速響應新請求。
• server.tomcat.accept-count：等待隊列長度，默認值為 100 ，當所有線程都在忙碌時，新請求會進入等待隊列，該參數表示隊列的最大長度。若隊列滿了，新請求將被拒絕。

連接超時設置決定了客戶端與服務器建立連接以及數據傳輸的最長等待時間。通過設置server.connection-timeout參數可以配置連接超時時間，單位為毫秒，默認值為 - 1，表示不限制超時時間。例如，設置連接超時時間為 5 秒：

server:connection-timeout: 5000

合適的連接超時設置能避免因長時間等待無效連接而占用資源，提高系統的穩定性和資源利用率。

1.3 靜態資源訪問（靜態資源存放路徑、自定義資源映射）

Spring Boot 默認會從src/main/resources/static、src/main/resources/public、src/main/resources/resources以及src/main/resources/META-INF/resources目錄下查找并加載靜態資源。例如，將圖片、CSS、JavaScript 文件等放置在src/main/resources/static目錄下，當用戶訪問http://localhost:8080/images/logo.png時，Spring Boot 會自動從src/main/resources/static/images目錄下查找logo.png文件并返回給用戶。

若想自定義靜態資源映射路徑，可通過實現WebMvcConfigurer接口來完成。比如，我們希望將/static-resources/路徑映射到src/main/resources/custom-static/目錄下，代碼如下：

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;@Configuration
public class WebMvcConfig implements WebMvcConfigurer {@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/static-resources/**").addResourceLocations("classpath:/custom-static/");}
}

上述配置完成后，當用戶訪問http://localhost:8080/static-resources/js/app.js時，Spring Boot 會從src/main/resources/custom-static/js目錄下查找app.js文件，實現了靈活的靜態資源訪問路徑自定義。

1.4 全局異常處理（@ControllerAdvice、@ExceptionHandler 統一異常響應）

在 Web 開發中，統一處理異常能提升系統的穩定性和用戶體驗。@ControllerAdvice注解用于定義全局異常處理類，它會對所有標注了@RequestMapping注解的方法進行異常處理。@ExceptionHandler注解用于指定處理特定異常的方法。

例如，創建一個全局異常處理器：

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;@ControllerAdvice
public class GlobalExceptionHandler {@ExceptionHandler(Exception.class)public ResponseEntity<String> handleException(Exception e) {e.printStackTrace();return new ResponseEntity<>("服務器內部錯誤", HttpStatus.INTERNAL_SERVER_ERROR);}
}

上述代碼中，GlobalExceptionHandler類被@ControllerAdvice注解修飾，成為全局異常處理器。@ExceptionHandler(Exception.class)表示該方法處理所有未捕獲的Exception異常。當系統中任何Controller方法拋出Exception異常時，都會被該方法捕獲，并返回一個包含錯誤信息和500 Internal Server Error狀態碼的響應給客戶端，實現了異常響應的統一處理。

二、RESTful 接口開發

2.1 RESTful 設計規范（HTTP 方法、URL 命名、狀態碼使用）

在當今的 Web 開發領域，RESTful 架構風格的接口設計已成為主流，它通過合理使用 HTTP 方法、規范 URL 命名以及恰當運用狀態碼，使接口具備更好的可讀性、可維護性和可擴展性。

在 HTTP 方法的使用上，GET 方法用于獲取資源，就像從圖書館書架上取下一本書查看內容，比如請求GET /users/1，表示獲取 ID 為 1 的用戶信息；POST 方法用于創建新資源，如同在圖書館添加一本新書，如發送POST /users并攜帶用戶信息來創建新用戶；PUT 方法用于更新資源，類似于修改圖書館中某本書的信息，如PUT /users/1，攜帶更新后的用戶數據來全量更新 ID 為 1 的用戶信息；DELETE 方法用于刪除資源，好比從圖書館移除一本書，如DELETE /users/1刪除 ID 為 1 的用戶。每種方法都有其明確的語義和使用場景，避免了使用不恰當的方法導致接口語義混亂。

URL 命名遵循一定規則能讓接口更清晰易懂。URL 應使用名詞表示資源，并且通常采用復數形式，例如/users表示用戶資源集合，/orders表示訂單資源集合。避免在 URL 中出現動詞，因為對資源的操作應由 HTTP 方法體現，而不是將操作寫在 URL 里。比如獲取用戶列表不應寫成/getUsers，而應是GET /users。同時，URL 路徑應簡潔明了，避免深度嵌套和冗長的命名，可采用小寫字母和連字符分隔單詞，如/product-categories表示產品分類資源。

狀態碼在接口中起到重要的溝通作用，它能讓客戶端快速了解請求的處理結果。2xx 狀態碼表示成功，其中 200 OK 表示請求成功，獲取資源時常用，如GET /products/1成功返回產品信息時狀態碼為 200；201 Created 表示資源創建成功，POST /users成功創建用戶后返回 201，并在響應頭的 Location 字段中指明新創建資源的 URL；204 No Content 表示請求成功但無內容返回，常用于DELETE /users/1成功刪除用戶后，不需要返回數據時。4xx 狀態碼表示客戶端錯誤，400 Bad Request 表示客戶端請求參數錯誤，如請求GET /users?id=abc，id參數格式錯誤時返回 400；401 Unauthorized 表示未授權，需要身份驗證，常用于訪問需要登錄的資源時；404 Not Found 表示請求的資源不存在，如請求GET /users/999，而 ID 為 999 的用戶不存在則返回 404。5xx 狀態碼表示服務器錯誤，500 Internal Server Error 表示服務器內部出現錯誤，當服務器執行代碼出錯時返回該狀態碼，告知客戶端服務器端出現問題。

2.2 核心注解使用（@RestController、@RequestMapping、@GetMapping 等）

在 Spring Boot 的 RESTful 接口開發中，@RestController、@RequestMapping、@GetMapping等注解發揮著關鍵作用，它們簡化了接口開發流程，使代碼結構更加清晰。

@RestController是一個組合注解，它結合了@Controller和@ResponseBody的功能。@Controller用于標識一個類為 Spring MVC 的控制器，負責處理 HTTP 請求；@ResponseBody則表示該控制器方法的返回值將直接作為 HTTP 響應體返回，而不會被解析為視圖。例如：

import org.springframework.web.bind.annotation.RestController;@RestController
public class UserController {// 控制器方法
}

上述代碼中，UserController被@RestController注解修飾，表明該類中的方法返回值會直接以 JSON 等格式返回給客戶端，無需額外配置視圖解析器。

@RequestMapping是一個通用的請求映射注解，可用于類和方法上。標注在類上時，表示類中的所有響應請求的方法都是以該類路徑為父路徑；標注在方法上時，指定該方法處理的具體 URL 路徑和 HTTP 請求方法等。例如：

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/users")
public class UserController {@RequestMapping(value = "/{id}", method = RequestMethod.GET)public String getUserById(@PathVariable Long id) {// 根據id獲取用戶信息的邏輯return "獲取到用戶ID: " + id;}
}

在這個例子中，@RequestMapping(“/users”)表示UserController處理所有以/users為前綴的 URL 請求，而@RequestMapping(value = “/{id}”, method = RequestMethod.GET)則表示getUserById方法處理GET請求，具體路徑為/users/{id}，即根據用戶 ID 獲取用戶信息。

@GetMapping是@RequestMapping(method = RequestMethod.GET)的縮寫，用于處理 HTTP GET 請求，使代碼更加簡潔易讀。例如：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/users")
public class UserController {@GetMapping("/list")public String listUsers() {// 獲取用戶列表的邏輯return "用戶列表";}
}

這里@GetMapping(“/list”)清晰地表明listUsers方法處理GET請求，路徑為/users/list，專門用于獲取用戶列表。類似地，@PostMapping、@PutMapping、@DeleteMapping分別是對應POST、PUT、DELETE請求的縮寫注解，在開發中可根據不同的 HTTP 請求方法選擇合適的注解來映射請求。

2.3 請求參數處理（@RequestParam、@PathVariable、@RequestBody）

在處理 RESTful 接口請求時，準確獲取和處理請求參數至關重要，@RequestParam、@PathVariable、@RequestBody這三個注解為我們提供了便捷的方式來獲取不同類型的請求參數。

@RequestParam用于從請求參數中獲取值，請求參數是 URL 中?后面的鍵值對。它可以將這些參數的值綁定到方法的參數上，并且可以指定參數是否必須存在以及默認值。例如：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;@RestController
public class ProductController {@GetMapping("/products")public String getProductsByPrice(@RequestParam(value = "minPrice", defaultValue = "0") double minPrice,@RequestParam(value = "maxPrice", required = false) Double maxPrice) {// 根據價格范圍獲取產品的邏輯String result = "獲取價格大于等于 " + minPrice;if (maxPrice != null) {result += " 且小于等于 " + maxPrice + " 的產品";} else {result += " 的產品";}return result;}
}

上述代碼中，@RequestParam(“minPrice”)獲取請求參數minPrice的值，若請求中未提供該參數，則使用默認值0；@RequestParam(“maxPrice”)獲取請求參數maxPrice的值，required = false表示該參數不是必須的，若請求中沒有該參數，maxPrice的值為null。

@PathVariable用于從 URI 模板變量中獲取值，URI 模板變量是在 URI 中用大括號{}包圍的變量名。它通常與@GetMapping、@PostMapping等注解一起使用，將 URL 中的變量值綁定到方法參數上。例如：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;@RestController
public class OrderController {@GetMapping("/orders/{orderId}")public String getOrderById(@PathVariable Long orderId) {// 根據訂單ID獲取訂單信息的邏輯return "獲取到訂單ID: " + orderId;}
}

當請求GET /orders/123時，@PathVariable Long orderId會將 URL 中的123賦值給orderId參數，方便后續根據訂單 ID 進行業務處理。

@RequestBody用于將 HTTP 請求體中的 JSON 或 XML 數據綁定到方法的參數上，通常用于處理客戶端發送的復雜數據類型，如對象或數組，這些數據會被自動轉換為 Java 對象。它常與@PostMapping或@PutMapping等注解一起使用，因為這兩種 HTTP 方法通常用于提交數據。例如：

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;@RestController
public class UserController {@PostMapping("/users")public String createUser(@RequestBody User user) {// 保存用戶信息的邏輯return "創建用戶成功: " + user.getName();}
}class User {private String name;private int age;// 省略getter和setter方法
}

當客戶端發送POST /users請求，并在請求體中攜帶 JSON 格式的用戶數據，如{“name”: “張三”, “age”: 20}時，Spring 會自動將這些數據轉換為User對象，并傳遞給createUser方法中的user參數，實現對復雜數據的處理。

2.4 響應結果封裝（統一響應格式、JSON 數據返回）

在 RESTful 接口開發中，統一的響應格式能提高接口的易用性和可維護性，便于前端或其他客戶端進行處理。同時，將數據以 JSON 格式返回是目前 Web 開發中廣泛采用的方式，因為 JSON 具有輕量級、易解析的特點。

首先，定義一個統一的響應類，例如：

public class ResponseResult<T> {private int code;private String message;private T data;public ResponseResult(int code, String message, T data) {this.code = code;this.message = message;this.data = data;}// 省略getter和setter方法
}

這個ResponseResult類包含三個字段：code表示響應狀態碼，用于標識請求處理的結果，例如 200 表示成功，400 表示請求錯誤等；message是對響應結果的描述信息，如 “操作成功”“參數錯誤” 等，方便前端了解具體情況；data則是實際返回的數據，類型通過泛型T表示，可以是任何 Java 對象，如用戶信息、訂單列表等。

在控制器方法中，使用這個統一響應類來封裝響應結果。例如：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
public class BookController {@GetMapping("/books/1")public ResponseResult<Book> getBook() {Book book = new Book("Java核心技術", "Cay S. Horstmann");return new ResponseResult<>(200, "獲取書籍成功", book);}
}class Book {private String title;private String author;public Book(String title, String author) {this.title = title;this.author = author;}// 省略getter和setter方法
}

上述代碼中，getBook方法返回一個ResponseResult<Book>對象，將書籍信息封裝在其中，狀態碼設置為 200，消息為 “獲取書籍成功”。

在 Spring Boot 中，默認會使用Jackson庫將 Java 對象轉換為 JSON 格式返回給客戶端。當客戶端接收到這個響應時，會得到如下格式的 JSON 數據：

{"code": 200,"message": "獲取書籍成功","data": {"title": "Java核心技術","author": "Cay S. Horstmann"}
}

這種統一的響應格式和 JSON 數據返回方式，使得前端開發人員能夠方便地解析和處理接口響應，提高了前后端交互的效率和穩定性，同時也便于在項目中進行錯誤處理和日志記錄等操作。

三、接口參數校驗與文檔

3.1 參數校驗框架（Hibernate Validator，@NotNull、@NotBlank 等注解）

在接口開發中，確保輸入參數的合法性至關重要，Hibernate Validator 作為一款強大的參數校驗框架，為 Java 開發者提供了便捷的校驗方式。它實現了 Java Bean Validation 規范，使得我們能夠通過簡單的注解來定義校驗規則。

首先，在 Spring Boot 項目中引入spring-boot-starter-validation依賴，它包含了 Hibernate Validator 相關的依賴。若使用 Maven 構建項目，在pom.xml文件中添加如下依賴：

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId>
</dependency>

添加依賴后，便可以在實體類或請求參數對象中使用校驗注解。@NotNull注解用于確保字段不為null，它適用于各種對象類型，包括基本數據類型的包裝類。例如：

import javax.validation.constraints.NotNull;public class User {@NotNull(message = "用戶ID不能為空")private Long id;// 省略其他字段和方法
}

上述代碼中，@NotNull注解標注在id字段上，當對User對象進行校驗時，如果id為null，則會拋出校驗異常，并返回message中定義的錯誤信息 “用戶 ID 不能為空”。
@NotBlank注解專門用于字符串類型，它要求字符串不為null，并且去除首尾空格后長度大于 0。例如：

import javax.validation.constraints.NotBlank;public class User {@NotBlank(message = "用戶名不能為空")private String username;// 省略其他字段和方法
}

這里，若username為null、空字符串或者僅包含空格，校驗都會失敗，提示 “用戶名不能為空”，常用于校驗用戶名、密碼等重要字符串信息，確保其有實際內容。

在控制器方法中，使用@Valid或@Validated注解來觸發校驗。例如：

import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;@RestController
@Validated
public class UserController {@PostMapping("/users")public String createUser(@Validated @RequestBody User user) {// 保存用戶邏輯return "用戶創建成功";}
}

當客戶端發送POST /users請求，請求體中包含User對象數據時，Spring 會自動對user對象進行校驗。若參數不滿足校驗規則，會拋出MethodArgumentNotValidException異常，我們可以通過全局異常處理器來統一處理這類異常，返回友好的錯誤提示給客戶端，確保接口接收到的數據是符合預期的，提高系統的穩定性和健壯性。

3.2 自定義參數校驗注解（實現 Validator 接口）

盡管 Hibernate Validator 提供了豐富的內置校驗注解，但在實際開發中，有時內置注解無法滿足復雜的業務需求，這時就需要自定義參數校驗注解。通過實現Validator接口，我們可以創建符合特定業務規則的校驗邏輯。

首先，定義自定義校驗注解。例如，我們希望校驗一個字符串是否為手機號碼格式，創建一個@PhoneNumber注解：

import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Constraint(validatedBy = PhoneNumberValidator.class)
public @interface PhoneNumber {String message() default "手機號碼格式不正確";Class<?>[] groups() default {};Class<? extends Payload>[] payload() default {};
}

上述代碼中，@Retention(RetentionPolicy.RUNTIME)表示該注解在運行時有效；@Target指定了注解可以作用的目標，這里是字段和方法參數；@Constraint(validatedBy = PhoneNumberValidator.class)指定了校驗器類為PhoneNumberValidator。

接下來，實現PhoneNumberValidator校驗器類，它需要實現ConstraintValidator接口：

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
import java.util.regex.Pattern;public class PhoneNumberValidator implements ConstraintValidator<PhoneNumber, String> {private static final Pattern PHONE_PATTERN = Pattern.compile("^1[3-9]\\d{9}$");@Overridepublic void initialize(PhoneNumber constraintAnnotation) {// 初始化方法，可用于獲取注解參數等操作}@Overridepublic boolean isValid(String value, ConstraintValidatorContext context) {if (value == null) {return true;}return PHONE_PATTERN.matcher(value).matches();}
}

在isValid方法中，通過正則表達式匹配來判斷傳入的字符串是否符合手機號碼格式。如果匹配成功，返回true表示校驗通過；否則返回false，校驗失敗。

最后，在實體類或請求參數對象中使用自定義注解：

public class User {@PhoneNumberprivate String phone;// 省略其他字段和方法
}

這樣，當對User對象進行校驗時，若phone字段的值不符合手機號碼格式，就會觸發自定義的校驗邏輯，返回@PhoneNumber注解中定義的錯誤信息 “手機號碼格式不正確”，從而實現了滿足特定業務需求的參數校驗功能。

3.3 Swagger/OpenAPI 整合（接口文檔自動生成、在線測試）

在接口開發過程中，生成清晰、準確的接口文檔對于團隊協作和接口的維護至關重要。Swagger 和 OpenAPI 為我們提供了便捷的方式來自動生成接口文檔，并支持在線測試功能，大大提高了接口開發的效率和可維護性。

Swagger 2 整合

以 Spring Boot 項目為例，首先在pom.xml文件中添加 Swagger 2 相關依賴：

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>3.0.0</version>
</dependency>
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>3.0.0</version>
</dependency>

添加依賴后，創建一個 Swagger 配置類，用于配置 Swagger 的相關參數：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Spring Boot API 文檔").description("這是一個Spring Boot項目的接口文檔").version("1.0").build();}
}

在上述配置類中，@EnableSwagger2注解啟用 Swagger 2 功能；Docket定義了 Swagger 的基本配置，apiInfo方法設置了接口文檔的標題、描述和版本信息；RequestHandlerSelectors.basePackage指定了需要生成接口文檔的控制器所在的包路徑，PathSelectors.any()表示對所有路徑生成文檔。

啟動項目后，訪問http://localhost:8080/swagger-ui.html，即可看到自動生成的 Swagger 接口文檔頁面。在該頁面中，可以查看每個接口的詳細信息，包括請求方法、URL、請求參數、響應參數等，并且可以直接在頁面上進行接口測試，輸入請求參數，發送請求并查看響應結果，方便開發人員進行接口調試和驗證。

OpenAPI 整合（以 springdoc-openapi 為例）

若使用 OpenAPI 進行接口文檔生成，同樣先在pom.xml文件中添加依賴：

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.5.9</version>
</dependency>

springdoc-openapi 的配置相對簡單，通常只需在application.properties或application.yml文件中進行一些基本配置即可啟用：

springdoc.api-docs.enabled=true
springdoc.swagger-ui.enabled=true
springdoc.swagger-ui.path=/swagger-ui.html

上述配置中，springdoc.api-docs.enabled=true啟用 API 文檔功能，springdoc.swagger-ui.enabled=true啟用 Swagger UI 界面，springdoc.swagger-ui.path=/swagger-ui.html指定 Swagger UI 的訪問路徑。

啟動項目后，同樣通過http://localhost:8080/swagger-ui.html訪問接口文檔頁面，OpenAPI 會根據項目中的控制器和接口定義，自動生成符合 OpenAPI 3.0 規范的接口文檔，其功能與 Swagger 2 類似，但在文檔生成和規范支持上可能有所不同，開發人員可根據項目需求選擇合適的工具來生成接口文檔。

3.4 接口實戰案例（用戶管理 CRUD 接口開發與測試）

通過一個用戶管理 CRUD 接口開發的實戰案例，能更好地理解和運用前面講解的知識，展示完整的接口開發流程，并進行測試驗證。

項目搭建與依賴引入

首先創建一個 Spring Boot 項目，在pom.xml文件中引入必要的依賴，包括spring-boot-starter-web、spring-boot-starter-validation（用于參數校驗）以及數據庫相關依賴（這里以 MySQL 和 MyBatis-Plus 為例）：

<dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId></dependency><dependency><groupId>com.baomidou</groupId><artifactId>mybatis-plus-boot-starter</artifactId><version>3.5.1</version></dependency><dependency><groupId>mysql</groupId><artifactId>mysql-connector-java</artifactId><scope>runtime</scope></dependency>
</dependencies>

數據庫表設計

創建一個user表，用于存儲用戶信息：

CREATE TABLE user (id BIGINT AUTO_INCREMENT PRIMARY KEY,username VARCHAR(50) NOT NULL,password VARCHAR(100) NOT NULL,age INT,email VARCHAR(100)
);

實體類與 Mapper 層

創建User實體類，對應數據庫中的user表：

import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;@Data
@TableName("user")
public class User {private Long id;@NotBlank(message = "用戶名不能為空")private String username;@NotBlank(message = "密碼不能為空")private String password;private Integer age;@Email(message = "郵箱格式不正確")private String email;
}

使用 MyBatis-Plus 創建UserMapper接口，繼承BaseMapper<User>，即可獲得基本的 CRUD 操作方法：

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import org.apache.ibatis.annotations.Mapper;@Mapper
public interface UserMapper extends BaseMapper<User> {
}

服務層與控制器層

在服務層創建UserService接口及其實現類UserServiceImpl，用于處理業務邏輯：

import com.baomidou.mybatisplus.extension.service.IService;
import com.example.demo.entity.User;public interface UserService extends IService<User> {
}

import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
import com.example.demo.entity.User;
import com.example.demo.mapper.UserMapper;
import org.springframework.stereotype.Service;@Service
public class UserServiceImpl extends ServiceImpl<UserMapper, User> implements UserService {
}

在控制器層創建UserController，實現用戶管理的 CRUD 接口：

import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.example.demo.entity.User;
import com.example.demo.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;import java.util.List;@RestController
@RequestMapping("/users")
@Api(tags = "用戶管理接口")
public class UserController {@Autowiredprivate UserService userService;@PostMapping@ApiOperation("創建用戶")public String createUser(@Validated @RequestBody User user) {if (userService.save(user)) {return "用戶創建成功";}return "用戶創建失敗";}@GetMapping("/{id}")@ApiOperation("根據ID查詢用戶")public User getUserById(@PathVariable Long id) {return userService.getById(id);}@GetMapping@ApiOperation("查詢用戶列表")public Page<User> getUserList(@RequestParam(defaultValue = "1") long current,@RequestParam(defaultValue = "10") long size) {Page<User> page = new Page<>(current, size);return userService.page(page, null);}@PutMapping@ApiOperation("更新用戶")public String updateUser(@Validated @RequestBody User user) {if (userService.updateById(user)) {return "用戶更新成功";}return "用戶更新失敗";}@DeleteMapping("/{id}")@ApiOperation("刪除用戶")public String deleteUser(@PathVariable Long id) {if (userService.removeById(id)) {return "用戶刪除成功";}return "用戶刪除失敗";}
}

在上述控制器代碼中，使用了前面講解的各種注解，如@Validated用于參數校驗，@Api和@ApiOperation用于 Swagger 接口文檔描述，@RequestParam、@PathVariable、@RequestBody用于請求參數處理。

接口測試

啟動項目后，通過 Swagger 界面進行接口測試。在 Swagger 頁面中，可以清晰地看到每個接口的信息，包括請求方法、參數、響應等。例如，測試創建用戶接口時，在 Swagger 頁面輸入合法的用戶信息，點擊 “Try it out” 按鈕發送請求，若參數校驗通過且業務邏輯執行成功，會返回 “用戶創建成功” 的提示；若參數不符合校驗規則，會返回相應的錯誤信息。同樣，可以對查詢、更新和刪除接口進行測試，驗證接口的正確性和穩定性，確保用戶管理 CRUD 接口能夠正常工作。