Spring Boot 编写 API 的 10条最佳实践-蒲公英云

Spring Boot 编写 API 的 10条最佳实践

10 个最佳实践，让您像专业人士一样编写 Spring Boot API，并结合编码示例和解释：

1. RESTful API 设计原则：

清晰一致的资源命名：使用准确反映 API 管理的资源的名词（例如，/products、/users）。

@GetMapping(“/products/{id}”)
public ResponseEntity getProductById(@PathVariable Long id) {
```
// ...
```
}
标准化 HTTP 方法：遵循 CRUD 操作的 RESTful 约定（CREATE： POST、READ： GET、UPDATE： PUT、DELETE：DELETE）。

@PostMapping(“/users”)
public ResponseEntity createUser(@RequestBody User user) {
```
// ...
```
}
有意义的状态代码：返回相应的 HTTP 状态代码以指示成功（2xx）、错误（4xx）或服务器问题（5xx）。

@DeleteMapping(“/products/{id}”)
public ResponseEntity<?> deleteProduct(@PathVariable Long id) {
```
if (productService.deleteProduct(id)) {
    return ResponseEntity.noContent().build(); // 204 No Content
} else {
    return ResponseEntity.notFound().build(); // 404 Not Found
}
```
}

2. 利用 Spring Boot 注解：

@RestController: 定义返回JSON的API
@RequestMapping: 定义Controller的基础路径
@GetMapping, @PostMapping, @PutMapping, @DeleteMapping: 定义HTTP端点
@PathVariable: 定义捕获URL路径中的参数 (比如： /products/{id}).
@RequestBody: 将HTTP请求体中的数据反序列化为Java对象.
@ResponseBody: 显式实现将Response处理成JSON格式

3. 拥抱依赖注入（DI）：

使用 @Autowired 将依赖项（服务、存储库）注入控制器。

促进松耦合和可测试性。

@RestController
public class ProductController {

@Autowired
private ProductService productService;
// ... other controller methods

}

4. 实现异常处理：

为特定 API 错误创建自定义异常类。

使用 @ControllerAdvice 和 @ExceptionHandler 可以正常处理异常并返回适当的错误响应。

@ControllerAdvice
public class ApiExceptionHandler {

@ExceptionHandler(ProductNotFoundException.class)
public ResponseEntity<ErrorResponse> handleProductNotFound(ProductNotFoundException ex) {
    // ... create error response with details
    return ResponseEntity.status(HttpStatus.NOT_FOUND).body(errorResponse);
}

}

5. 使用清晰简洁的 DTO（数据传输对象）对数据进行建模：

创建专用类（DTO）来表示 API 端点和服务之间交换的数据。
提高代码的可读性、可维护性和数据封装性。

public class ProductDto {
```
private Long id;
private String name;
private double price;
// Getters and setters
```
}