下面从“是什么、做什么、怎么用、易踩的坑”四个维度，对 `@GetMapping` 做一次“拆解式”说明，并配套一张“超细对照表”，方便快速查阅与实战落地。 >[info]一、它到底是什么 1. 语法糖：`@GetMapping` 是 Spring 4.3 引入的“快捷注解”，等价于 `@RequestMapping(method = RequestMethod.GET)` 2. 目的：把 **HTTP GET 请求** 精确地映射到某个控制器方法，完成路由 + 数据绑定 + 响应生成。 >[info]二、它能做什么 - URL 路由（常量、占位符、通配符、正则） - 参数绑定（路径变量、查询串、Header、Cookie、矩阵变量） - 内容协商（决定返回 JSON、XML、HTML 等） - 与 Spring 全家桶协作（安全、验证、跨域、异步、响应式） >[info]三、常用场景与示例 下面用一张“场景-代码-注意点”三列表，把 90% 的日常用法一次性列全。 | # | 场景 | 经典代码 | 注意点/最佳实践 | |---|------|----------|-----------------| | 1 | 最简 GET 接口 | `@GetMapping("/hello") public String hi(){ return "hi";}` | 返回字符串 = 视图名；想返回 JSON 请加 `@ResponseBody` 或直接用 `@RestController` | | 2 | 指定多路径 | `@GetMapping({"/v1/books","/books"})` | 适合新旧版本并存 | | 3 | 路径变量 | `@GetMapping("/book/{id}") public Book get(@PathVariable Long id)` | 变量名相同可省略 `@PathVariable("id")` | | 4 | 多路径变量 | `@GetMapping("/shop/{shopId}/book/{bookId}")` | 顺序无关，但名字必须对应 | | 5 | 正则限定 | `@GetMapping("/book/{id:\\d{3}}")` | 仅匹配 3 位数字，防止脏数据 | | 6 | 查询参数 | `@GetMapping("/search") public List<Book> list(@RequestParam String q, @RequestParam(defaultValue="0") int page)` | 非必填时记得 `required=false` 或给 `defaultValue` | | 7 | Map 一股脑接收 | `public List<Book> list(@RequestParam Map<String,String> all)` | 适合动态查询 | | 8 | 接收 Header | `@GetMapping("/token") public String token(@RequestHeader("X-Token") String t)` | Header 名忽略大小写 | | 9 | 接收 Cookie | `public String cookie(@CookieValue("JSESSIONID") String sid)` | Cookie 不存在会抛异常，可加 `required=false` | |10 | 矩阵变量 | `/book/123;author=King` + `@GetMapping("/book/{id}") public Book get(@PathVariable Long id, @MatrixVariable String author)` | 需先开启 `UrlPathHelper.removeSemicolonContent=false` | |11 | 返回 JSON | `@RestController` 类下直接返回对象 | 依赖 `spring-boot-starter-web` 里默认的 Jackson | |12 | 内容协商 | `@GetMapping(value="/book/{id}", produces={"application/json","application/xml"})` | 结合请求头 `Accept:` | |13 | 下载文件 | `@GetMapping("/report") public ResponseEntity<byte[]> download(){...}` | 设置 `Content-Disposition: attachment` | |14 | 自定义状态码 | `@GetMapping("/404") @ResponseStatus(HttpStatus.NOT_FOUND)` | 也可返回 `ResponseEntity.notFound().build()` | |15 | 跨域支持 | `@CrossOrigin(origins="*") @GetMapping("/api")` | 细粒度可配置到方法级别 | |16 | 组合安全注解 | `@PreAuthorize("hasRole('ADMIN')") @GetMapping("/admin")` | Spring Security | |17 | 异步/响应式 | `@GetMapping("/flux") public Flux<Event> stream()` | 需引入 `spring-boot-starter-webflux` | |18 | 与 Swagger 文档 | `@Operation(summary="按ID查书") @GetMapping("/{id}")` | springdoc-openapi | |19 | 默认通配符 | `@GetMapping("/static/**")` | 常用于映射 `/static/**` 到本地目录 | |20 | 视图渲染 | `@Controller` 类里返回 `"thymeleaf/hello"` | 配合模板引擎 | >[info]四、易踩的坑 - GET 请求体：HTTP 规范虽允许，但 Spring MVC 默认忽略 body；不要把 JSON 放在 body 里用 GET。 - `@PathVariable` 与 `@RequestParam` 同名时不会冲突，但路径优先。 - 返回字符串时，若想返回纯文本而非视图名，需加 `@ResponseBody` 或 `@RestController`。 - `/users/{id}` 和 `/users/list` 的顺序：精确路径应写在通配/参数路径之前，否则会被覆盖。 - 在 Spring Boot 3.x 之后，WebFlux 与 MVC 注解基本一致，但底层实现不同，注意依赖选择。 五、速查口诀 “GET 路由加 GetMapping，路径变量 PathVariable，查询参数 RequestParam，返回 JSON 用 RestController，文件下载 ResponseEntity，跨域安全再叠加。”