Java 后端 / 系统课时

接收路径、查询与请求体参数

接收路径、查询与请求体参数

一个 Web 请求可能同时携带资源标识、筛选条件、请求元数据和结构化业务数据。本课将用一个更新用户接口,把路径变量、查询参数、请求头与 JSON 请求体准确绑定到 Spring MVC 方法参数,并验证常见失败边界。

学习目标

  • 根据数据语义选择路径、查询、请求头或请求体
  • 使用 Spring MVC 注解完成类型安全的参数绑定
  • 通过实际请求验证成功结果与典型 400 错误

四种输入位置如何选择

路径变量用于定位唯一资源,例如 /users/42 中的 42;查询参数用于控制筛选、排序或可选行为;请求头承载追踪号、认证信息等元数据;请求体适合提交结构化业务对象。选择依据是数据职责,而不是字段多少。

数据位置 常用注解 适合承载 示例
路径 @PathVariable 必填资源标识 /users/42
查询串 @RequestParam 可选条件或开关 ?notify=true
请求头 @RequestHeader 请求元数据 X-Request-Id
JSON 请求体 @RequestBody 新增或修改的数据 用户名称与邮箱

Spring MVC 请求参数绑定流程

定义请求模型与控制器

片段示例:以下控制器放入已经引入 spring-boot-starter-web 的 Spring Boot 3 项目中。记录类型让请求体字段和返回字段保持明确,避免用无类型的 Map 接收业务数据。

java
package com.example.demo.web;

import org.springframework.web.bind.annotation.*;

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

    @PutMapping("/{userId}")
    public UpdateResult updateUser(
            @PathVariable long userId,
            @RequestParam(defaultValue = "false") boolean notify,
            @RequestHeader(value = "X-Request-Id", defaultValue = "unknown")
            String requestId,
            @RequestBody UpdateUserRequest request) {

        // 四类输入在进入业务层前已完成名称匹配和基础类型转换
        return new UpdateResult(
                userId,
                notify,
                requestId,
                request.displayName(),
                request.email()
        );
    }

    public record UpdateUserRequest(String displayName, String email) {}

    public record UpdateResult(
            long userId,
            boolean notify,
            String requestId,
            String displayName,
            String email) {}
}

生效行为:Spring MVC 会先从 URL、查询串和请求头提取简单值,再由 Jackson 把 JSON 请求体反序列化为 UpdateUserRequest。字段名默认按 Java 属性名匹配。

发起请求并验证绑定

应用启动后执行下面的请求。<PORT> 替换为实际端口,默认通常为 8080。

bash
curl -i -X PUT "http://localhost:<PORT>/api/users/42?notify=true" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: req-1001" \
  -d '{"displayName":"Lin","email":"lin@example.com"}'

预期输出:

text
HTTP/1.1 200
Content-Type: application/json

{"userId":42,"notify":true,"requestId":"req-1001","displayName":"Lin","email":"lin@example.com"}

状态行中的协议版本和响应头顺序可能不同,但状态码与 JSON 字段值应一致。

处理缺失值与类型错误

@RequestParam(defaultValue = "false") 表示未传 notify 时使用默认值;请求头也通过默认值变为可选。路径变量 userId 声明为 long,因此传入 /users/abc 会在进入方法前发生类型转换失败,Spring MVC 默认返回 400。

请求体缺失、JSON 语法错误或字段类型不兼容,同样会在反序列化阶段失败。业务必填、长度和格式规则不应靠手写 if 分散处理,后续应结合 Bean Validation 和统一异常响应。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

接收路径、查询与请求体参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通