首页 > 软件编程 > java > SpringBoot接口获取参数注解

SpringBoot接口获取参数的常用注解详解

2026-01-31 11:20:51 作者：一线大码

SpringBoot 接口获取参数的注解非常丰富,这篇文章主要为大家详细介绍了一些常用参数注解的使用,文中的示例代码讲解详细,感兴趣的小伙伴可以了解下

SpringBoot 接口获取参数的注解非常丰富，下面详细介绍一下常用的参数注解：

1、URL 路径参数

@PathVariable

获取 URL 路径中的参数

// 获取单个参数
@GetMapping("/user/{id}")
public User getUserById(@PathVariable Long id) {
    return userService.findById(id);
}

// 获取多个参数
@GetMapping("/user/{id}/post/{postId}")
public String getInfo(
    @PathVariable Long id,
    @PathVariable Long postId
) {
    // ...
}

// 参数名不一致时指定
@GetMapping("/user/{userId}")
public User getUser(@PathVariable("userId") Long id) {
    return userService.findById(id);
}

// 获取所有路径变量（Map形式）
@GetMapping("/user/{id}/post/{postId}")
public String getInfo(@PathVariable Map<String, String> pathVariables) {
    return pathVariables.get("id");
}

// URL路径中的时间参数
@GetMapping("/events/date/{date}")
public List<Event> getEventsByPathDate(
    @PathVariable @DateTimeFormat(pattern = "yyyy-MM-dd") Date date) {
    return eventService.findByDate(date);
}

@GetMapping("/events/datetime/{datetime}")
public String getByDateTime(
    @PathVariable @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") LocalDateTime datetime) {
    return "时间: " + datetime;
}

2. 查询参数（URL 参数）

@RequestParam

获取 URL 查询字符串参数

// 必填参数
@GetMapping("/users")
public List<User> getUsers(@RequestParam String name) {
    return userService.findByName(name);
}

// 可选参数
@GetMapping("/users")
public List<User> getUsers(
    @RequestParam(required = false) String name,
    @RequestParam(defaultValue = "1") int page,
    @RequestParam(defaultValue = "10") int size
) {
    return userService.findByName(name, page, size);
}

// 接收多个值
@GetMapping("/users")
public List<User> getUsers(@RequestParam List<Long> ids) {
    return userService.findByIds(ids);
}

// 获取所有查询参数（Map形式）
@GetMapping("/search")
public String search(@RequestParam Map<String, String> params) {
    return params.get("keyword");
}

// 查询参数中的时间
@GetMapping("/events")
public List<Event> getEventsByDate(
    @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") Date date) {
    return eventService.findByDate(date);
}

// 多个时间参数
@GetMapping("/events/range")
public List<Event> getEventsByRange(
    @RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd") Date startDate,
    @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) LocalDateTime endTime) {
    return eventService.findByDateRange(startDate, endTime);
}

3. 请求体参数

@RequestBody

获取 JSON/XML 格式的请求体

@PostMapping("/user")
public User createUser(@RequestBody User user) {
    return userService.save(user);
}

// 接收 Map 类型的请求体
@PostMapping("/data")
public String processData(@RequestBody Map<String, Object> data) {
    return data.toString();
}

// 使用 DTO 接收参数
@PostMapping("/register")
public ResponseEntity<?> register(@RequestBody RegisterDTO registerDTO) {
    // 处理注册逻辑
    return ResponseEntity.ok("注册成功");
}

@ModelAttribute

获取表单数据（支持 GET/POST）

// 绑定到对象
@PostMapping("/user")
public String createUser(@ModelAttribute User user) {
    userService.save(user);
    return "success";
}

// 绑定到 Map
@PostMapping("/user")
public String createUser(@ModelAttribute Map<String, Object> model) {
    return model.get("name").toString();
}

4. 请求头参数

@RequestHeader

获取 HTTP 请求头信息

@GetMapping("/info")
public String getInfo(
    @RequestHeader("User-Agent") String userAgent,
    @RequestHeader(value = "Authorization", required = false) String auth,
    @RequestHeader Map<String, String> headers
) {
    return "User-Agent: " + userAgent;
}

5. Cookie 参数

@CookieValue

获取 Cookie 中的值

@GetMapping("/profile")
public String getProfile(@CookieValue("sessionId") String sessionId) {
    return "Session ID: " + sessionId;
}

// 可选参数
@GetMapping("/profile")
public String getProfile(
    @CookieValue(value = "sessionId", defaultValue = "default") String sessionId
) {
    return "Session ID: " + sessionId;
}

6. 文件上传参数

@RequestPart

获取文件上传内容

@RequestPart处理 multipart/form-data 请求中的复杂数据类型，支持文件上传和混合表单数据（如 JSON + 文件）。

特性	@RequestPart	@RequestParam
数据格式	支持任何内容类型（如 JSON、XML）	仅支持 application/x-www-form-urlencoded
内容类型	每个部分有独立的 Content-Type	整个请求统一的 Content-Type
数据处理	使用 HttpMessageConverter	使用 Servlet API 的参数解析
文件处理	天然支持文件上传，支持其他类型	仅支持文件（作为 MultipartFile）
JSON 绑定	直接绑定到对象	不支持
主要应用场景	上传文件同时发送 JSON 数据‌：如用户上传头像并附带用户信息（JSON）。单个请求中混合不同类型的数据‌：如同时上传多个文件和表单数据。 REST API 中的文件上传‌：如上传图片并附带元数据（JSON）。

@RestController
@RequestMapping("/api/upload")
public class UploadController {
    // 基础文件上传
    @PostMapping("/single")
    public String uploadSingle(@RequestPart("file") MultipartFile file) {
        return "Uploaded: " + file.getOriginalFilename();
    }

    // 多文件上传
    @PostMapping("/multiple")
    public String uploadMultiple(@RequestPart("files") MultipartFile[] files) {
        return "Uploaded " + files.length + " files";
    }

    // 文件 + JSON对象
    @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public String uploadData(@RequestPart("file") MultipartFile file, 
                             @RequestPart("metadata") MyMetadata metadata) {
        // metadata 是自定义的 JSON 对象
        return "Uploaded file with metadata";
    }
    
    // 文件 + 表单字段
    @PostMapping(value = "/upload-with-data", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<?> uploadWithData(
                                            @RequestPart("file") MultipartFile file,
                                            @RequestParam("name") String name,
                                            @RequestParam("description") String description) {
        // 处理文件和文本数据
        return ResponseEntity.ok("上传成功");
    }
}

常见错误及解决方法:

忘记设置 consumes = "multipart/form-data"‌：导致无法解析请求。
文件大小超过默认限制‌：需配置 spring.servlet.multipart.max-file-size 和 spring.servlet.multipart.max-request-size。

与 @RequestBody 的区别:

@RequestBody 用于处理 application/json 或 application/xml 格式的请求体数据。
@RequestPart 用于处理 multipart/form-data 中的复杂数据类型（如 JSON + 文件）。

@RequestParam

@PostMapping("/upload-simple")
public String uploadSimple(@RequestParam("file") MultipartFile file) {
    return "文件名称: " + file.getOriginalFilename();
}

7. 会话和属性参数

@SessionAttribute

获取会话属性

@GetMapping("/dashboard")
public String dashboard(@SessionAttribute("user") User user) {
    return "欢迎 " + user.getUsername();
}

@RequestAttribute

获取请求域属性

@GetMapping("/process")
public String process(@RequestAttribute("processedData") String data) {
    return "处理后的数据: " + data;
}

8. 其他特殊注解

@MatrixVariable

获取矩阵变量（不常用）

// URL: /cars;color=red;year=2023
@GetMapping("/cars")
public String getCar(@MatrixVariable String color) {
    return color;
}

@Value（从配置获取）

@GetMapping("/config")
public String getConfig(@Value("${app.name}") String appName) {
    return "应用名称: " + appName;
}

到此这篇关于SpringBoot接口获取参数的常用注解详解的文章就介绍到这了,更多相关SpringBoot接口获取参数注解内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！