目录
- 参数注解使用场景完整指南
- 1. @RequestBody 使用场景
- 2. @PathVariable 使用场景
- 3. 无注解使用场景
- 详细对比表格
- 实际项目中的应用示例
- 员工管理模块完整示例
- 决策流程图
- 记忆口诀
- 特殊场景说明
- 混合使用场景
- 总结
参数注解使用场景完整指南
1. @RequestBody 使用场景
核心特征:
- HTTP方法:主要用于 POST、PUT、PATCH
- 数据来源:HTTP请求体 (Request Body)
- Content-Type:通常是
application/json
适用场景:
// 场景1:用户登录 - 敏感数据 @PostMapping("/login") public Result<EmployeeLoginVO> login(@RequestBody EmployeeLoginDTO employeeLoginDTO) { // 原因:用户名密码敏感,需要在请求体中加密传输 } // 场景python2:新增员工 - 复杂对象 @PostMapping public Result save(@RequestBody EmployeeDTO employeeDTO) { // 原因:多个字段的复杂对象,JSON格式更清晰 } // 场景3:修改员工信息 - 更新操作 @PutMapping public Result update(@RequestBody EmployeeDTO employeeDTO) { // 原因:修改操作通常用PUT,需要传递完整对象 } // 场景4:批量操作 @PostMapping("/BATch") public Result batchSave(@RequestBody List<EmployeeDTO> employees) { // 原因:批量数据,数组/列表格式 }
2. @PathVariable 使用场景
核心特征:
- 数据来源:URL路径中的变量部分
- 用途:资源标识符,符合RESTful设计
- HTTP方法:GET、PUT、DELETE等
适用场景:
// 场景1:根据ID查询 - 资源标识 @GetMapping("/{id}") public Result<Employee> getById(@PathVariable Long id) { // URL: /admin/employee/123 // 原因:ID是资源的唯一标识符 } // 场景2:根据ID删除 - 资源操作 @DeleteMapping("/{id}") public Result delete(@PathVariable Long id) { // URL: /admin/employee/123 // 原因:明确指定要删除的资源 } // 场景3:状态切换 - 动作+资源 @PostMapping("/status/{status}") public Result startOrStop(@PathVariable Integer status, Long id) { // URL: /admin/employee/status/1?id=123 // 原因:status是操作类型,属于URL路径的一部分 } // 场景4:多级资源路径 @GetMapping("/department/{deptId}/employees/{empId}") public Result getEmployeeInDept(@PathVariable Long deptId, @PathVariable Long empId) { // URL: /admin/department/10/employees/123 // 原因:表示部门下的特定员工资源 }
3. 无注解使用场景
核心特征:
- 数据来源:URL查询参数 (Query Parameters)
- 用途:查询条件、过滤参数、分页参数
- HTTP方法:主要是GET
适用场景:
// 场景1:分页查询 - 查询条件 @GetMapping("/page") public Result<PageResult> page(EmployeePageQueryDTO employeePageQueryDTO) { // URL: /admin/employee/page?name=张&page=1&pageSize=10 // 原因:简单查询条件,支持缓存和书签 } // 场景2:简单参数查询 @GetMapping("/search") public Result<List<Employee>> search(String keyword, Integer stjavascriptatus) { // URL: /admin/employee/search?keyword=张三&status=1 // 原因:简单的过滤条件 } // 场景3:可选参数查询 @GetMapping("/list") public Result<List<Employee>> list(String department, Integer level) { // URL: /admin/employee/list?department=IT&level=2 // 原因:可选的查询条件,可以为空 }
详细对比表格
注解类型 | HTTP方法 | 数据位置 | 使用场景 | URL示例 | 优缺点 |
---|---|---|---|---|---|
@RequestBody | POST/PUT/PATCH | 请求体 | 复杂对象、敏感数据、批量操作 | POST /employee + JSON | ✅复杂数据 ❌不支持缓存 |
@PathVariable | GET/PUT/DELETE | URL路径 | 资源标识符、层级资源 | GET /employee/123 | ✅RESTful ✅语义清晰 |
无注解 | GET | URL参数 | 查询条件、分页、过滤 | GET /employee?name=张&page=1 | ✅支持缓存 ✅书签友好 |
实际项目中的应用示例
员工管理模块完整示例
@RestController @RequestMapping("/admin/employee") public class EmployeeController { // 1. 登录 - @RequestBody (敏感数据) @PostMapping("/login") public Result<EmployeeLoginVO> login(@RequestBody EmployeeLoginDTO dto) { // POST /admin/employee/login + JSON } // 2. 新增 - @RequestBody (复杂对象) @PostMapping public Result save(@RequestBody EmployeeDTO dto) { // POST /admin/employee + JSON } // 3. 分页查询 - 无注解 (查询条件) @GetMapping("/page") public Result<PageResult> page(EmployeePageQueryDTO dto) { // GET /admin/employee/page?name=张&page=1&pageSize=10 } // 4. 根据ID查询 - @PathVariable (资源标识) @GetMapping("/{id}") public Result<Employee> getById(@PathVariable Long id) { // GET /admin/employee/123 } // 5. 修改 - @RequestBody (更新对象) @PutMapping public Result update(@RequestBody EmployeeDTO dto) { // PUT /admin/employee + JSON } // 6. 启用禁用 - @PathVariable + 无注解 (状态+ID) @PostMapping("/status/{status}") public Result startOrStop(@PathVariable Integer status, Long id) { // POST /admin/employee/status/1?id=123 } // 7. 删除 - @PathVariable (资源标识) @DeleteMapping("/{id}") public Result delete(@PathVariable Long id) { // DELETE /admin/employee/js123 } }
决策流程图
是否传输复杂对象或敏感数据? ├─ 是 → 使用 @RequestBody (POST/PUT + JSON) └─ 否 → 是否资源标识符? ├─ 是 → 使用 @PathVariable (/{id}) └─ 否 → 无注解 (URL参数,GET请求)
记忆口诀
- @RequestBody = “复杂敏感批量” (复杂对象、敏感数据、批量操作)
- @PathVariable = “资源标识符” (ID、路径参数、RESTful)
- 无注解 = “查询过滤分页” (查询条件、过滤器、分页参数)
特殊场景说明
混合使用场景
// 组合1:路径参数 + 查询参数 @GetMapping("/department/{deptId}/employees") public Result getEmployeesByDept(@PathVariable Long deptId, String keyword, Integer page) { // GET /admin/department/10/employees?keyword=张&page=1 } // 组合2:路径参数 + 请求体 @PutMapping("/{id}") public Result update(@PathVariable Long id, @RequestBody EmployeeDTO dto) { // PUT /admin/employee/123 + JSON // ID确定资源,DTO包含更新数据 }
总结
这三种注解的选择遵循以下原则:
- @RequestBody - 数据复杂度高、安全性要求高、修改操作
- @PathVariable - 资源定位、RESTful风格、层级关系
- 无注解python - 查询场景、性js能优化、用户体验
选择正确的注解不仅能让代码更规范,还能提升API的性能和用户体验!
以上为个人经验,希望能给大家一个参考,也希望大家多多支持编程客栈(www.devze.com)。
精彩评论