@GetMapping & @PostMapping

引言

在 Spring Boot 后端开发中，@GetMapping 和 @PostMapping 是 Spring Web 模块提供的语义化组合注解，专门用于 RESTful API 的请求映射。二者均是 @RequestMapping 注解的简化版，分别绑定 HTTP 协议的 GET 和 POST 请求方法，是前后端数据交互最核心的注解。

遵循 HTTP 标准语义：@GetMapping 用于查询 / 读取服务器资源，@PostMapping 用于新增 / 提交资源，严格区分读写操作是企业级开发的最佳实践。

本质

两者都是组合注解（Spring 4.3+ 引入），底层等价于 @RequestMapping + 指定请求方法，作用是简化代码、提升接口语义：

// @GetMapping 等价写法
@RequestMapping(value = "/xxx", method = RequestMethod.GET)

// @PostMapping 等价写法
@RequestMapping(value = "/xxx", method = RequestMethod.POST)

区别

特性	@GetMapping	@PostMapping
HTTP 方法	GET	POST
核心用途	查询 / 读取资源（无副作用）	新增 / 提交资源（有副作用）
数据位置	URL 拼接（路径变量 / 查询参数）	请求体（Body）为主，URL 为辅
安全性	安全（不修改服务器数据）	不安全（修改服务器状态）
幂等性	幂等（多次请求结果完全一致）	非幂等（多次请求会创建多份资源）
数据长度	受 URL 长度限制（≈2KB）	无理论限制（支持大数据 / 文件）
缓存支持	浏览器 / 网关自动缓存	默认不缓存
浏览器历史	记录到地址栏历史	不记录
编码支持	仅支持 ASCII 编码	支持 JSON/ 表单 / 二进制等任意编码
请求体规范	HTTP 规范禁止携带请求体	推荐 / 必须携带请求体

@GetMapping

适用场景

仅用于查询数据，不修改服务器任何状态：

获取列表、详情（用户列表、商品详情）
筛选 / 分页查询（?page=1&size=10）
加载配置、统计数据

数据传递方式

@PathVariable：路径变量（RESTful 标准风格）
@RequestParam：URL 查询参数（?key=value）
@ModelAttribute：GET 表单参数（极少用）

代码示例

@RestController
@RequestMapping("/api/users") // 统一接口前缀
public class UserController {

    @Autowired
    private UserService userService;

    // 1. 查询所有用户 GET /api/users
    @GetMapping
    public List<User> list() {
        return userService.listAll();
    }

    // 2. 根据ID查询用户 GET /api/users/1
    @GetMapping("/{id}")
    public User getById(@PathVariable Long id) {
        return userService.getById(id);
    }

    // 3. 分页+条件查询 GET /api/users/page?name=张三&page=1&size=10
    // required：是否必传；defaultValue：默认值
    @GetMapping("/page")
    public PageInfo<User> page(
            @RequestParam(required = false) String name,
            @RequestParam(defaultValue = "1") Integer page,
            @RequestParam(defaultValue = "10") Integer size) {
        return userService.page(name, page, size);
    }
}

核心特性

幂等性：重复请求不会产生脏数据
缓存友好：浏览器会自动缓存响应结果（可通过请求头禁用）
轻量：请求体积小，响应速度快

@PostMapping

适用场景

用于提交数据，修改服务器状态：

新增资源（注册用户、创建订单）
提交表单、上传文件
批量操作数据

数据传递方式

@RequestBody：接收 JSON 格式请求体（最常用）
@ModelAttribute：接收表单数据（x-www-form-urlencoded）
MultipartFile：接收文件上传（form-data）

代码示例

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

    @Autowired
    private UserService userService;

    // 1. 新增用户 POST /api/users（接收JSON）
    @PostMapping
    public ResponseEntity<User> add(@Valid @RequestBody User user) {
        User saveUser = userService.save(user);
        // 遵循REST规范：新增资源返回201状态码
        return ResponseEntity.status(HttpStatus.CREATED).body(saveUser);
    }

    // 2. 表单提交 POST /api/users/form
    @PostMapping("/form")
    public String formSubmit(@ModelAttribute User user) {
        userService.save(user);
        return "提交成功";
    }

    // 3. 单文件上传 POST /api/users/upload
    @PostMapping("/upload")
    public String upload(@RequestParam("file") MultipartFile file) {
        // 文件上传逻辑
        return "上传成功：" + file.getOriginalFilename();
    }
}

核心特性

非幂等性：重复提交会创建多条数据（需做防重处理）
大数据支持：可传输 JSON、文件、二进制数据
无缓存：浏览器不会缓存响应结果

其他补充

幂等性

幂等：任意多次请求的结果与一次请求完全一致（GET 天生幂等）
非幂等：多次请求会改变数据状态（POST 天生非幂等）
实战：POST 接口必须做防重复提交（令牌机制、唯一索引）

参数接收注解

注解	适用请求	数据位置	常用场景
@PathVariable	GET	URL 路径	RESTful 资源查询
@RequestParam	GET/POST	URL 查询参数	简单参数、分页筛选
@RequestBody	POST	请求体（JSON）	复杂对象、批量数据
@ModelAttribute	GET/POST	表单数据	传统表单提交
MultipartFile	POST	表单数据	文件上传

缓存机制差异

GET：浏览器 /CDN 自动缓存，适合静态数据、频繁查询的接口
POST：默认禁用缓存，适合写操作接口
手动控制：通过 @Cacheable（Spring 缓存）或 Cache-Control 请求头

HTTP 规范红线

禁止：@GetMapping 携带请求体（违反 HTTP 标准，部分服务器会丢弃）
推荐：@PostMapping 必须用请求体传输数据，避免参数暴露在 URL

总结

语义优先：查询用 @GetMapping，新增提交用 @PostMapping，严格遵循 HTTP 语义
参数分离：GET 用 URL 传参，POST 用请求体传参
幂等控制：GET 天然安全，POST 必须防重
规范开发：遵循 RESTful 标准、状态码规范、参数校验规范，提升接口可读性与稳定性

源本科技 | 码上会

引言

本质

区别

@GetMapping

适用场景

数据传递方式

代码示例

核心特性

@PostMapping

适用场景

数据传递方式

代码示例

核心特性

其他补充

幂等性

参数接收注解

缓存机制差异

HTTP 规范红线

总结