@PutMapping用于全量更新资源，需以路径ID为准、校验失败返回400、资源不存在返回404、成功返回200或204；不应用于增量修改，应选@PatchMapping。
@PutMapping 是 Spring MVC 中用于映射 HTTP PUT 请求的注解，常用于实现资源的**全量更新**（即客户端提供完整资源数据，服务端用其完全替换现有资源）。它不负责业务逻辑本身，而是把请求准确路由到对应方法，并配合其他注解完成参数解析、校验和响应处理。
明确 PUT 的语义：全量更新，不是增量修改
PUT 请求默认代表“用请求体中的数据，完整替换指定 URI 对应的资源”。例如：
- PUT /api/users/123 表示“把 ID 为 123 的用户，替换成请求体里给的数据”；
- 即使只传了 name 字段，其他字段（如 email、status）也会被设为 null 或默认值（取决于反序列化配置），除非你显式忽略未传字段；
- 若需只改部分字段，更适合用 @PatchMapping（HTTP PATCH），或在业务层做差异化合并。
基本用法：绑定路径、接收 JSON、返回结果
典型写法如下：
Java注释规范Skills
下载
当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。
@PutMapping("/api/users/{id}")
public ResponseEntity<User> updateUser(
@PathVariable Long id,
@RequestBody @Valid User userUpdate) {
User updated = userService.updateById(id, userUpdate);
return ResponseEntity.ok(updated);
}
- @PathVariable 提取 URL 中的 ID，确保操作目标明确；
- @RequestBody 将 JSON 自动转为 Java 对象（依赖 Jackson）；
- @Valid 触发 Bean Validation（如 @NotNull、@Email），校验失败时 Spring 自动返回 400；
- 返回 ResponseEntity 可灵活控制状态码（如 200 OK、404 Not Found）和响应体。
处理常见场景：ID 不一致、资源不存在、空字段覆盖
真实开发中需主动应对这些情况：
-
ID 来源不一致：URL 中的
{id}和请求体 JSON 中的"id": 999可能不同。建议以路径 ID 为准，忽略请求体中的 ID 字段（可用@JsonIgnore或 DTO 分离输入/输出模型）； -
资源不存在：查询不到原记录时，应返回
ResponseEntity.notFound().build()（404），而不是创建新资源（那是 POST 的职责）； -
避免空字段覆盖：若前端只传了 name，Jackson 默认会把 email 设为 null。可改用
@JsonInclude(JsonInclude.Include.NON_NULL)或使用 Map/JsonNode 手动合并，或切换为 Patch 语义。
配合 REST 规范：正确设置状态码与响应头
符合规范的响应提升 API 可靠性：
- 成功更新 → 返回
200 OK（含更新后资源）或204 No Content（无响应体）； - 创建新资源（极少数 PUT 幂等创建场景）→ 返回
201 Created+Location头； - 校验失败 →
400 Bad Request（Spring Boot 默认返回）； - 资源不存在 →
404 Not Found； - 并发冲突（如带 ETag）→
412 Precondition Failed。
