注解中的 value 参数作用

• value 参数用于指定前端传递的参数名：如果 value 参数与前端的参数名一致，后端方法的参数名就可以随意设置，而不必与前端一致。也可以使用简写形式 @RequestParam("id") 来指定参数名。
• 如果不设置 value 参数，Spring 默认会使用方法参数名与前端参数名进行映射。这时，方法参数名必须与前端传递的参数名一致。

1. 接收查询参数 (@RequestParam )

注解说明： @RequestParam 用于接收 HTTP 请求中的查询参数或表单数据。它可以绑定 URL 中的参数到方法的参数上。

可配置参数

• value：指定请求参数名称，绑定 URL 中对应的参数。
• required：指定参数是否必须，默认为 true，可选参数设置为 false。
• defaultValue：为可选参数提供默认值，当参数未传递时使用。

前端请求示例

// 使用 Axios 发送 GET 请求
axios.get('/api/getUser', {
  params: {
    id: 123, // 用户 ID，后端将通过 @RequestParam 接收该参数
    name: '张三' // 用户姓名，后端将通过 @RequestParam 接收该参数
  }
})
.then(response => {
  console.log('响应数据:', response.data);
})
.catch(error => {
  console.error('请求失败:', error);
});

后端参数接收示例

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

    @GetMapping("/getUser")
    public ResponseEntity<String> getUser(
            @RequestParam(value = "id", required = true) int id, // 必填参数：id
            @RequestParam(value = "name", required = false, defaultValue = "匿名") String name // 可选参数：name，默认值为 "匿名"
    ) {
        String response = "用户 ID: " + id + ", 用户姓名: " + name;
        return ResponseEntity.ok(response);
    }
}

注释说明

• @RequestParam 用于接收 URL 中的参数，value 是参数名，必须设置。
• required 默认为 true，表示参数必须存在。如果设置为 false，则参数为可选。
• defaultValue 用于在参数可选且未提供时指定默认值。

2. 接收路径参数 (@PathVariable)

注解说明： @PathVariable 用于接收 URL 路径中的变量值。通常在 RESTful 风格的路径中使用，如 /api/user/{id}。

可配置参数

• value：指定路径变量的名称，通常与路径中的占位符一致。
• required：默认值为 true，表示该路径变量是必须的。

前端请求示例

// 使用 Axios 发送带路径参数的 GET 请求
axios.get('/api/user/123')
.then(response => {
  console.log('响应数据:', response.data);
})
.catch(error => {
  console.error('请求失败:', error);
});

后端参数接收示例

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

    @GetMapping("/user/{id}")
    public ResponseEntity<String> getUserById(@PathVariable(value = "id") int id) {
        String response = "用户 ID: " + id;
        return ResponseEntity.ok(response);
    }
}

注释说明

• @PathVariable 用于接收 URL 路径中的参数，value 是路径变量的名称，必须设置。
• 路径中的占位符（如 /user/{id}）必须与 @PathVariable 中的 value 一致。

3. 接收 JSON 数据 (@RequestBody)

注解说明： @RequestBody 用于接收 HTTP 请求体中的 JSON 数据，并将其映射为对应的 Java 对象。常用于 POST、PUT 请求。

在后端使用对象接收前端数据时，通常不需要保证字段数量完全一致。Spring Boot 使用的 @RequestBody 或其他数据绑定机制能够自动将 JSON 数据映射到 Java 对象，即使字段数量不完全匹配。

可配置参数

• required：默认 true，表示请求体必须存在。设置为 false 时，允许请求体为空。

前端请求示例

// 使用 Axios 发送 POST 请求，并发送 JSON 格式的数据
axios.post('/api/saveUser', {
  id: 123,
  name: '张三',
  age: 25
})
.then(response => {
  console.log('响应数据:', response.data);
})
.catch(error => {
  console.error('请求失败:', error);
});

后端参数接收示例

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

    @PostMapping("/saveUser")
    public ResponseEntity<String> saveUser(@RequestBody User user) {
        String response = "保存的用户信息: " + user.toString();
        return ResponseEntity.ok(response);
    }
}

// 用户数据模型类
class User {
    private int id;
    private String name;
    private int age;

    // Getters 和 Setters

    @Override
    public String toString() {
        return "ID: " + id + ", 姓名: " + name + ", 年龄: " + age;
    }
}

注释说明

• @RequestBody 用于接收请求体中的 JSON 数据，并自动映射到 Java 对象。
• required 默认为 true，表示请求体必须存在。如果设置为 false，请求体可以为空，但需要在业务逻辑中处理空值情况。

映射规则

1. 字段名称匹配：前端传来的 JSON 数据中的字段名称需要和后端对象的字段名称一致。Spring 会根据名称进行匹配。如果前端传递了后端对象中没有的字段，Spring 会忽略这些字段。
2. 字段缺失：如果前端传递的数据中缺少后端对象中的某些字段，这些字段会被映射为默认值（如 null、0 等）。只要后端的字段是可选的（即没有标注为 @NotNull 或其他约束注解），这不会影响数据的正常绑定。

4. 接收请求头参数 (@RequestHeader)

注解说明： @RequestHeader 用于接收 HTTP 请求头中的参数，如 Authorization、User-Agent 等。

可配置参数

1. value：指定请求头的名称，通常与请求头的键名一致。必须设置。

2. required：指定请求头是否必须，默认值为 true。如果设置为 false，请求头可以为空。

3. defaultValue：当 required = false 时，如果请求头不存在，会使用此默认值。

前端请求示例

// 使用 Axios 发送带请求头的 POST 请求
axios.post('/api/secure/saveUser', {
  id: 123,
  name: '张三',
  age: 25
}, {
  headers: {
    Authorization: 'Bearer token_123456' // 请求头中的 token 信息
  }
})
.then(response => {
  console.log('响应数据:', response.data);
})
.catch(error => {
  console.error('请求失败:', error);
});

后端参数接收示例

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

    @PostMapping("/saveUser")
    public ResponseEntity<String> saveUserWithAuth(
            @RequestBody User user, 
            @RequestHeader(value = "Authorization", required = false, defaultValue = "") String token) {
        if (token.isEmpty()) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("未提供授权令牌");
        }
        String response = "保存的用户信息: " + user.toString() + ", 认证令牌: " + token;
        return ResponseEntity.ok(response);
    }
}

注释说明

• @RequestHeader 用于接收请求头中的参数，value 是请求头的名称，必须设置。
• required 默认为 true，表示请求头必须存在。如果设置为 false，请求头可以为空。
• defaultValue 用于在请求头不存在时指定默认值。

5. 接收传统表单数据 (@ModelAttribute)

提示

在当前前后端分离的开发模式中，表单数据的提交通常使用 JSON 格式。

注解说明： @ModelAttribute 用于接收表单数据，常用于传统的表单提交。适用于 POST 请求中的 application/x-www-form-urlencoded 和 multipart/form-data 数据。

可配置参数

1. value：可以指定绑定的数据名称，通常不常用。

2. binding：指定是否进行数据绑定，默认值为 true。

前端请求示例

在前端使用传统表单提交时，通常是通过 HTML 的 <form> 标签来提交数据，但在现代 Web 开发中，也可以使用 Axios 模拟传统表单的提交方式。

// 使用 Axios 发送 POST 表单请求
axios.post('/api/form/saveUser', new URLSearchParams({
  id: 123,
  name: '张三',
  age: 25
}))
.then(response => {
  console.log('响应数据:', response.data);
})
.catch(error => {
  console.error('请求失败:', error);
});

• 通过 new URLSearchParams() 可以将对象数据转换为 application/x-www-form-urlencoded 格式，这是传统表单提交数据的编码方式之一。
• 这种方式模拟了传统表单的提交方式，适用于需要处理表单数据的后端接口。

后端参数接收示例

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

    @PostMapping("/saveUser")
    public ResponseEntity<String> saveUserForm(@ModelAttribute User user) {
        String response = "保存的用户信息: " + user.toString();
        return ResponseEntity.ok(response);
    }
}

注释说明

• @ModelAttribute 用于接收表单数据，并自动将表单字段映射到 Java 对象中。
• value 参数用于指定绑定的前缀或对象名称，通常不常用。
• binding 参数控制是否参与数据绑定，默认为 true。

6. 单文件上传 (MultipartFile)

注解说明： MultipartFile 是 Spring MVC 提供的用于处理文件上传的类。通过 @RequestParam 绑定单个文件。

前端请求示例

// 使用 Axios 发送单文件上传请求
let formData = new FormData();
formData.append('file', this.selectedFile); // 将文件添加到 FormData 对象中

axios.post('/api/upload/single', formData, {
  headers: {
    'Content-Type': 'multipart/form-data' // 设置请求头为 multipart/form-data
  }
})
.then(response => {
  console.log('上传成功:', response.data);
})
.catch(error => {
  console.error('上传失败:', error);
});

后端参数接收示例

@RestController
@RequestMapping("/api/upload")
public class FileUploadController {

    @PostMapping("/single")
    public ResponseEntity<String> uploadSingleFile(@RequestParam("file") MultipartFile file) {
        if (file.isEmpty()) {
            return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("文件为空");
        }

        String fileName = file.getOriginalFilename();
        Path filePath = Paths.get("uploads/" + fileName);

        try {
            Files.copy(file.getInputStream(), filePath, StandardCopyOption.REPLACE_EXISTING);
            return ResponseEntity.ok("文件上传成功: " + fileName);
        } catch (IOException e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("文件上传失败");
        }
    }
}

注释说明

• 前端使用 FormData 对象构建文件上传请求，并设置 Content-Type 为 multipart/form-data。
• 后端使用 MultipartFile 接收文件，该类提供了获取文件名、文件大小和文件内容等方法。

7. 多文件上传 (List<MultipartFile>)

注解说明： MultipartFile[] 或 List<MultipartFile> 用于处理多文件上传。通过 @RequestParam 绑定多个文件。

前端请求示例

// 使用 Axios 发送多文件上传请求
let formData = new FormData();
this.selectedFiles.forEach(file => {
  formData.append('files', file); // 多个文件使用相同的键名
});

axios.post('/api/upload/multiple', formData, {
  headers: {
    'Content-Type': 'multipart/form-data' // 设置请求头为 multipart/form-data
  }
})
.then(response => {
  console.log('上传成功:', response.data);
})
.catch(error => {
  console.error('上传失败:', error);
});

后端参数接收示例

@RestController
@RequestMapping("/api/upload")
public class FileUploadController {

    @PostMapping("/multiple")
    public ResponseEntity<String> uploadMultipleFiles(@RequestParam("files") List<MultipartFile> files) {
        if (files.isEmpty()) {
            return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("没有上传任何文件");
        }

        List<String> fileNames = new ArrayList<>();
        for (MultipartFile file : files) {
            String fileName = file.getOriginalFilename();
            Path filePath = Paths.get("uploads/" + fileName);
            try {
                Files.copy(file.getInputStream(), filePath, StandardCopyOption.REPLACE_EXISTING);
                fileNames.add(fileName);
            } catch (IOException e) {
                return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("部分文件上传失败");
            }
        }

        return ResponseEntity.ok("文件上传成功: " + String.join(", ", fileNames));
    }
}

注释说明

• List<MultipartFile> 接收多个文件，比 MultipartFile[] 更灵活。
• 前端 FormData 使用相同的键名 files 添加多个文件。

8. 接收 Cookie (@CookieValue)

注解说明： @CookieValue 用于接收 HTTP 请求中的 Cookie。

可配置参数

• value：指定要绑定的 Cookie 名称，通常与前端发送的 Cookie 名称一致。必须设置。

• required：指定 Cookie 是否必须，默认值为 true。如果设置为 false，Cookie 可以为空。 `

• defaultValue：当 required = false 时，如果 Cookie 不存在，会使用此默认值。

前端请求示例

// 使用 Axios 发送请求，浏览器会自动携带已有的 Cookie
axios.get('/api/getUser')
.then(response => {
  console.log('响应数据:', response.data);
})
.catch(error => {
  console.error('请求失败:', error);
});

后端参数接收示例

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

    @GetMapping("/getUser")
    public ResponseEntity<String> getUserByCookie(@CookieValue(value = "sessionId", required = false, defaultValue = "unknown") String sessionId) {
        if ("unknown".equals(sessionId)) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("用户未登录");
        }
        return ResponseEntity.ok("用户的 Session ID: " + sessionId);
    }
}

注释说明

• @CookieValue 用于接收特定名称的 Cookie 值，value 是 Cookie 名称，必须设置。
• required 默认为 true，表示 Cookie 必须存在。如果设置为 false，Cookie 可以为空。
• defaultValue 用于在 Cookie 不存在时指定默认值。

9. 接收 Session 属性 (@SessionAttribute)

注解说明： @SessionAttribute 用于获取 HttpSession 中的某个属性值，简化了对 HttpSession 的操作。

前端请求示例

// 使用 Axios 发送请求，浏览器会自动携带已有的 Session 信息
axios.get('/api/session/getUserInfo')
.then(response => {
  console.log('响应数据:', response.data);
})
.catch(error => {
  console.error('请求失败:', error);
});

后端参数接收示例

@RestController
@RequestMapping("/api/session")
public class SessionController {

    @GetMapping("/getUserInfo")
    public ResponseEntity<String> getUserInfo(@SessionAttribute(value = "username", required = false) String username) {
        if (username == null) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("未找到用户信息，请先登录");
        }
        return ResponseEntity.ok("当前用户: " + username);
    }

    @PostMapping("/setUserInfo")
    public ResponseEntity<String> setUserInfo(HttpSession session) {
        session.setAttribute("username", "张三");
        return ResponseEntity.ok("用户信息已保存到 Session");
    }
}

注释说明

• @SessionAttribute 用于直接获取 HttpSession 中的属性，value 参数指定属性名称。
• required 参数默认为 true，表示属性必须存在。如果设置为 false，则属性不存在时会返回 null。
• 与直接使用 HttpSession 相比，@SessionAttribute 更加简洁，适合在处理单个会话属性时使用。

10. 接收日期格式的参数 (@DateTimeFormat)

注解说明： @DateTimeFormat 用于指定日期参数的格式，常用于接收前端传递的日期字符串。

可配置参数

1. pattern：指定日期格式的模式，如 yyyy-MM-dd、yyyy-MM-dd HH:mm:ss。必须设置。
   • 示例：@DateTimeFormat(pattern = "yyyy-MM-dd")

前端请求示例

// 使用 Axios 发送带日期参数的请求
axios.get('/api/getUserByDate', {
  params: {
    birthDate: '2023-08-17' // 日期格式为 yyyy-MM-dd
  }
})
.then(response => {
  console.log('响应数据:', response.data);
})
.catch(error => {
  console.error('请求失败:', error);
});

后端参数接收示例

@RestController
@RequestMapping("/api")
public class User

Controller {

    @GetMapping("/getUserByDate")
    public ResponseEntity<String> getUserByDate(@RequestParam("birthDate") @DateTimeFormat(pattern = "yyyy-MM-dd") Date birthDate) {
        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");
        return ResponseEntity.ok("用户出生日期: " + sdf.format(birthDate));
    }
}

注释说明

• @DateTimeFormat 用于指定日期参数的格式，pattern 是日期格式的模式，必须设置。
• 前端应确保发送的日期格式与后端的模式一致，否则会导致参数解析失败。

11. 处理对象属性中的日期格式 (@DateTimeFormat)

当接收对象中包含日期属性时，可以在对象的日期属性上使用 @DateTimeFormat 注解来指定日期格式。这样，当对象通过请求参数传递到后端时，Spring MVC 会自动按照指定格式解析日期字符串。

1. 前端请求示例

假设我们有一个包含日期属性的对象需要通过前端发送到后端：

// 使用 Axios 发送带日期属性的对象请求
axios.post('/api/saveUser', {
  userName: '张三',
  birthDate: '2023-08-17' // 日期格式为 yyyy-MM-dd
})
.then(response => {
  console.log('响应数据:', response.data);
})
.catch(error => {
  console.error('请求失败:', error);
});

2. 后端对象定义与接收示例

我们可以通过在对象的日期属性上使用 @DateTimeFormat 注解来指定日期格式：

// 用户类，包含一个日期属性
public class User {

    private String userName;

    @DateTimeFormat(pattern = "yyyy-MM-dd") // 指定日期格式
    private Date birthDate;

    // Getter 和 Setter 方法
    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }

    public Date getBirthDate() {
        return birthDate;
    }

    public void setBirthDate(Date birthDate) {
        this.birthDate = birthDate;
    }
}

在控制器中接收对象时，Spring MVC 会自动按照 @DateTimeFormat 中指定的格式解析日期：

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

    @PostMapping("/saveUser")
    public ResponseEntity<String> saveUser(@RequestBody User user) {
        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");
        return ResponseEntity.ok("用户姓名: " + user.getUserName() + ", 出生日期: " + sdf.format(user.getBirthDate()));
    }
}

注释说明

• @DateTimeFormat(pattern = "yyyy-MM-dd")：用于指定对象中日期属性的格式，pattern 参数必须设置，指定日期格式的模式如 yyyy-MM-dd。

• 请求解析：前端应确保发送的日期格式与后端对象中的 @DateTimeFormat 模式一致，否则会导致参数解析失败。

12. 接收数组或集合参数

Vue 中发送数组或集合参数

当你使用 Axios 发送包含数组或集合的请求时，可以直接将数组作为 JSON 数据的一部分发送到后端。通常有以下两种方式：

1. 作为查询参数发送（适用于 GET 请求）
2. 作为 JSON 数据发送（适用于 POST、PUT 请求）

1. 作为查询参数发送（GET 请求）

如果你想发送一个数组作为查询参数，可以这样做：

// 使用 Axios 发送 GET 请求，数组作为查询参数
axios.get('/api/getItems', {
  params: {
    ids: [1, 2, 3, 4] // 发送一个数组作为查询参数
  }
})
.then(response => {
  console.log('响应数据:', response.data);
})
.catch(error => {
  console.error('请求失败:', error);
});

在这种情况下，Axios 会将数组自动转换为 URL 编码格式，如：/api/getItems?ids=1&ids=2&ids=3&ids=4。

2. 作为 JSON 数据发送（POST 请求）

在 POST 请求中，可以直接发送包含数组的 JSON 对象：

// 使用 Axios 发送 POST 请求，JSON 数据中包含数组
axios.post('/api/saveItems', {
  ids: [1, 2, 3, 4], // 数组作为 JSON 数据的一部分
  name: '张三'
})
.then(response => {
  console.log('响应数据:', response.data);
})
.catch(error => {
  console.error('请求失败:', error);
});

后端接收数组或集合参数

后端可以通过 @RequestParam、@RequestBody 等注解来接收数组或集合参数。

1. 使用 @RequestParam 接收数组或列表（适用于 GET 请求）

@RestController
@RequestMapping("/api")
public class ItemController {

    @GetMapping("/getItems")
    public ResponseEntity<String> getItems(@RequestParam List<Integer> ids) {
        // 处理 ids 参数，ids 是一个列表
        String response = "接收到的 ID 集合: " + ids.toString();
        return ResponseEntity.ok(response);
    }
}

• 通过 @RequestParam 注解可以直接接收数组或列表参数，Spring MVC 会自动解析 URL 中的多个同名参数并将其转换为列表。

2. 使用 @RequestBody 接收 JSON 数据中的数组或集合（适用于 POST 请求）

@RestController
@RequestMapping("/api")
public class ItemController {

    @PostMapping("/saveItems")
    public ResponseEntity<String> saveItems(@RequestBody ItemData itemData) {
        // 处理接收到的数据
        String response = "接收到的 ID 集合: " + itemData.getIds().toString() + ", 名称: " + itemData.getName();
        return ResponseEntity.ok(response);
    }
}

// 数据模型类
class ItemData {
    private List<Integer> ids;
    private String name;

    // Getters 和 Setters
}

在这个示例中，前端发送的 JSON 对象中包含一个数组（ids），后端通过 @RequestBody 将 JSON 数据映射为 ItemData 对象，并可以直接访问其中的集合。

总结

1. 在使用 @RequestParam 接收数组时，前端需要使用同名参数（如 ids=1&ids=2&ids=3）来传递多个值，Spring 会自动将这些值解析为列表或数组。
2. 使用 @RequestBody 时，前端传递的数据需要是一个合法的 JSON 对象，Spring 会根据字段名称进行自动映射。