@PutMapping & @DeleteMapping

引言

在 Spring Boot 构建 RESTful API 时，@GetMapping（查）、@PostMapping（增）、@PutMapping（改）、@DeleteMapping（删）是完成CRUD 核心操作的四大组合注解。

@PutMapping 和 @DeleteMapping 是 Spring 4.3+ 引入的语义化派生注解，底层均为 @RequestMapping 的快捷方式，分别对应 HTTP PUT（全量更新）和 DELETE（删除）请求方法。严格遵循这两个注解的语义开发，是实现标准化 RESTful 接口的关键。

@PutMapping

核心定义

处理 HTTP PUT 请求，用于全量更新服务器上的已有完整资源，对应数据库的 UPDATE 操作。核心特性：全量覆盖更新、天生幂等

适用场景

更新用户的全部信息（姓名、年龄、电话等完整字段）
覆盖修改配置文件、订单信息等完整资源

数据传递规范

@PathVariable：从 URL 路径获取资源唯一标识（ID），定位要更新的资源
@RequestBody：接收客户端传递的完整实体数据（JSON 格式），全量覆盖原有资源
违反规范：不建议用 PUT 做局部更新（局部更新推荐用 @PatchMapping）

代码示例

@RestController
@RequestMapping("/api/users") // 统一接口前缀
public class UserController {

    @Autowired
    private UserService userService;

    /**
     * 全量更新用户信息
     * 请求地址：PUT /api/users/1
     * 请求体：完整的 User JSON 对象
     */
    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(
            @PathVariable Long id,  // 定位资源
            @Valid @RequestBody User user  // 接收完整更新数据 + 参数校验
    ) {
        // 校验资源是否存在
        User existUser = userService.getById(id);
        if (existUser == null) {
            return ResponseEntity.notFound().build(); // 404 资源不存在
        }
        // 全量更新
        User updatedUser = userService.updateById(id, user);
        // 200 成功返回更新后资源
        return ResponseEntity.ok(updatedUser);
    }
}

等价写法

@RequestMapping(value = "/api/users/{id}", method = RequestMethod.PUT)

@DeleteMapping

核心定义

处理 HTTP DELETE 请求，用于删除服务器上的指定资源，对应数据库的 DELETE 操作。核心特性：天生幂等、无请求体（HTTP 规范）

适用场景

根据 ID 删除单个用户 / 订单 / 文件
批量删除资源（扩展场景）

数据传递规范

单个删除：@PathVariable 从 URL 路径获取资源 ID（推荐）
批量删除：@RequestParam 接收多个 ID 参数（不建议用请求体）
HTTP 规范：DELETE 请求不推荐携带请求体

代码示例

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

    @Autowired
    private UserService userService;

    /**
     * 根据ID删除单个用户
     * 请求地址：DELETE /api/users/1
     */
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        User existUser = userService.getById(id);
        if (existUser == null) {
            return ResponseEntity.notFound().build(); // 404
        }
        userService.deleteById(id);
        // 204 无返回内容（RESTful 删除接口标准响应）
        return ResponseEntity.noContent().build();
    }

    /**
     * 批量删除用户
     * 请求地址：DELETE /api/users/batch?ids=1,2,3
     */
    @DeleteMapping("/batch")
    public ResponseEntity<Void> batchDelete(@RequestParam List<Long> ids) {
        userService.batchDelete(ids);
        return ResponseEntity.noContent().build();
    }
}

等价写法

@RequestMapping(value = "/api/users/{id}", method = RequestMethod.DELETE)

核心对比

特性	@PutMapping	@DeleteMapping
HTTP 方法	PUT	DELETE
核心操作	全量更新现有资源	删除现有资源
数据库类比	UPDATE（全量覆盖）	DELETE
幂等性	✅ 幂等（多次更新结果完全一致）	✅ 幂等（多次删除结果完全一致）
数据位置	路径参数 (@PathVariable)+ 请求体 (@RequestBody)	路径参数 / 查询参数（无请求体）
请求体	必须携带（完整资源数据）	禁止 / 不推荐携带
标准响应码	200 OK（返回更新后资源）	204 No Content（无响应体）
资源不存在	404 Not Found	404 Not Found
核心限制	仅用于全量更新，不做局部修改	仅用于删除，不做业务逻辑修改

其他补充

幂等性（最重要）

PUT 幂等：多次调用同一更新接口，资源最终状态完全一致（不会产生脏数据）
DELETE 幂等：多次删除同一资源，结果都是「资源已删除」（不会报错 / 重复删除）
对比：@PostMapping 非幂等，PUT/DELETE/GET 天生幂等

PUT 与 PATCH

注解	作用	数据要求	适用场景
@PutMapping	全量更新	必须传完整对象	覆盖整个资源
@PatchMapping	局部更新	传需要修改的字段	只修改个别属性（如改密码）

误区：很多开发者用 @PutMapping 做局部更新，违反 HTTP 语义，局部更新请用 @PatchMapping

RESTful 标准响应状态码

场景	状态码	注解使用
更新 / 删除成功	200	通用
删除成功无返回数据	204	DELETE
资源不存在	404	PUT/DELETE
参数校验失败	400	PUT

批量操作规范

批量更新：PUT /api/users/batch + 请求体（对象列表）
批量删除：DELETE /api/users/batch?ids=1,2,3（禁止用请求体）

总结

语义定位 @PutMapping = 全量更新资源，@DeleteMapping = 删除资源，配合 GET/POST 完成完整 CRUD；
幂等保障 二者均为幂等接口，重复请求不会产生脏数据，是 RESTful 规范的核心特性；
使用规范 PUT 必须用 @RequestBody 传完整数据，DELETE 用路径参数传 ID、禁止请求体；
标准开发 严格遵循 HTTP 语义和状态码规范，让接口更易读、易维护、符合企业开发标准。

源本科技 | 码上会

引言

@PutMapping

核心定义

适用场景

数据传递规范

代码示例

等价写法

@DeleteMapping

核心定义

适用场景

数据传递规范

代码示例

等价写法

核心对比

其他补充

幂等性（最重要）

PUT 与 PATCH

RESTful 标准响应状态码

批量操作规范

总结