本文介绍 Java 后端 HTTP GET 与 POST 请求传输规范。涵盖 RESTful 原则、参数传递（路径/查询/Body）、敏感数据保护、幂等性、响应体封装及异常处理。强调 URI 命名、版本控制、日志安全及前后端协作，提供代码示例与对照表，提升接口安全性与规范性。
@GetMapping，禁止用@RequestMapping(method = RequestMethod.GET)（冗余）。@PathVariable接收，参数名与 URI 中的占位符一致；// URI：GET /api/v1/users/1001
@RestController
@RequestMapping("/api/v1/users")
public class UserController {
@GetMapping("/{userId}")
public ResultDTO<UserInfoRespDTO> getUserById(@PathVariable("userId") Long userId) {
UserInfoRespDTO user = userService.getUserById(userId);
return ResultDTO.success(user);
}
}
@RequestParam接收唯一标识（如@RequestParam("userId") Long userId）。@RequestParam接收，可设置默认值、是否必传；// URI：GET /api/v1/orders?status=PAID&pageNum=1&pageSize=10
@GetMapping("/orders")
public ResultDTO<PageInfo<OrderListRespDTO>> getOrderList(
@RequestParam(value = "status", required = false) String status,
@RequestParam(value = "pageNum", defaultValue = "1") Integer pageNum,
@RequestParam(value = "pageSize", defaultValue = "10") Integer pageSize
) {
PageInfo<OrderListRespDTO> page = orderService.getOrderList(status, pageNum, pageSize);
return ResultDTO.success(page);
}
XXXQueryReqDTO，用@ModelAttribute接收（避免参数过多）；// 封装查询 DTO
@Data
public class OrderQueryReqDTO {
private String status;
private String orderNo;
private LocalDateTime startTime;
private LocalDateTime endTime;
private Integer pageNum = 1;
private Integer pageSize = 10;
}
// 接口接收
@GetMapping("/orders/query")
public ResultDTO<PageInfo<OrderListRespDTO>> queryOrder(@ModelAttribute OrderQueryReqDTO queryDTO) {
PageInfo<OrderListRespDTO> page = orderService.queryOrder(queryDTO);
return ResultDTO.success(page);
}
application.yml中配置：server:
tomcat:
uri-encoding: UTF-8
spring:
http:
encoding:
charset: UTF-8
enabled: true
force: true
password/token/phone等敏感字段，直接返回 400；public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
String method = request.getMethod();
if ("GET".equals(method)) {
Map<String, String[]> paramMap = request.getParameterMap();
if (paramMap.containsKey("password") || paramMap.containsKey("token")) {
response.setStatus(400);
response.getWriter().write(JSON.toJSONString(ResultDTO.fail("GET 请求禁止传递敏感数据")));
return false;
}
}
return true;
}
@PostMapping，禁止用@RequestMapping(method = RequestMethod.POST)。@RequestBody接收，参数封装为XXXReqDTO，并添加 JSR380 参数校验注解；// 新增用户 DTO（含参数校验）
@Data
@Schema(description = "用户新增请求参数")
public class UserAddReqDTO {
@NotBlank(message = "用户名不能为空")
@Size(min = 2, max = 20, message = "用户名长度需在 2-20 位")
private String username;
@NotBlank(message = "密码不能为空")
@Pattern(regexp = "^[a-zA-Z0-9@#$%^&*]{6,32}$", message = "密码仅支持字母、数字、特殊符号，长度 6-32 位")
private String password;
@Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式错误")
private String phoneNumber;
}
// 接口接收
@PostMapping("/users")
public ResultDTO<Long> addUser(@Valid @RequestBody UserAddReqDTO addDTO) {
Long userId = userService.addUser(addDTO);
return ResultDTO.success(userId, "新增用户成功");
}
@Valid触发参数校验，否则注解不生效；校验失败会抛出MethodArgumentNotValidException，需在全局异常处理器中捕获。@RequestPart接收文件，@RequestParam接收附加参数；spring:
servlet:
multipart:
max-file-size: 10MB # 单个文件大小
max-request-size: 50MB # 总文件大小
@PostMapping("/files/upload")
public ResultDTO<FileUploadRespDTO> uploadFile(
@RequestPart("file") MultipartFile file,
@RequestParam("fileName") String fileName
) {
// 校验文件类型/大小
if (!file.getContentType().startsWith("image/")) {
return ResultDTO.fail(400, "仅支持图片上传");
}
FileUploadRespDTO resp = fileService.upload(file, fileName);
return ResultDTO.success(resp);
}
orderNo（UUID），后端先查后插：@Transactional(rollbackFor = Exception.class)
public Long addOrder(OrderCreateReqDTO createDTO) {
// 1. 校验订单号是否已存在（幂等核心）
if (orderMapper.existsByOrderNo(createDTO.getOrderNo())) {
throw new BusinessException("订单已存在，请勿重复提交");
}
// 2. 新增订单
Order order = new Order();
BeanUtils.copyProperties(createDTO, order);
orderMapper.insert(order);
return order.getId();
}
// 复杂订单查询（参数多、含敏感条件）
@PostMapping("/orders/complex-query")
public ResultDTO<PageInfo<OrderListRespDTO>> complexQuery(@RequestBody OrderComplexQueryReqDTO queryDTO) {
PageInfo<OrderListRespDTO> page = orderService.complexQuery(queryDTO);
return ResultDTO.success(page);
}
@RequestMapping统一以 /api/v{版本号}/开头，资源用复数名词；@RequestMapping("/api/v1/users")，❌ 错误：@RequestMapping("/api/v1/user")/@RequestMapping("/api/v1/getUser")。ResultDTO，所有接口统一返回该类型，禁止直接返回业务对象 / 字符串；@Data
public class ResultDTO<T> {
// 状态码：200 成功，400 参数错误，403 权限不足，500 服务异常
private Integer code;
// 提示信息
private String msg;
// 业务数据
private T data;
// 成功响应（带数据）
public static <T> ResultDTO<T> success(T data) {
ResultDTO<T> result = new ResultDTO<>();
result.setCode(200);
result.setMsg("操作成功");
result.setData(data);
return result;
}
// 成功响应（无数据）
public static ResultDTO<Void> success() {
return success(null);
}
// 失败响应
public static ResultDTO<Void> fail(Integer code, String msg) {
ResultDTO<Void> result = new ResultDTO<>();
result.setCode(code);
result.setMsg(msg);
return result;
}
}
ResultDTO，禁止接口抛出未捕获异常；@RestControllerAdvice
public class GlobalExceptionHandler {
// 捕获参数校验异常
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResultDTO<Void> handleValidException(MethodArgumentNotValidException e) {
String msg = e.getBindingResult().getFieldError().getDefaultMessage();
return ResultDTO.fail(400, msg);
}
// 捕获自定义业务异常
@ExceptionHandler(BusinessException.class)
public ResultDTO<Void> handleBusinessException(BusinessException e) {
return ResultDTO.fail(e.getCode(), e.getMessage());
}
// 捕获所有未处理的异常
@ExceptionHandler(Exception.class)
public ResultDTO<Void> handleException(Exception e) {
// 记录详细异常日志
log.error("服务端异常", e);
return ResultDTO.fail(500, "服务器内部错误，请稍后重试");
}
}
?version=1）或请求头控制版本；@RequestMapping("/api/v1/users")，@RequestMapping("/api/v2/users")。| 场景 | 反例（禁止） | 正例（推荐） |
|---|---|---|
| GET 查询单个用户 | @GetMapping("/getUser") + @RequestParam("userId") Long userId | @GetMapping("/{userId}") + @PathVariable Long userId |
| POST 新增用户 | @PostMapping("/addUser") + URL 传参 | @PostMapping("/users") + @RequestBody UserAddReqDTO |
| 响应数据 | return user;（直接返回业务对象） | return ResultDTO.success(user); |
| 参数校验 | 手动 if 判断（if (username == null) { throw new Exception(); }） | JSR380 注解（@NotBlank）+ @Valid |
CorsConfig，允许前端的 Origin、Method、Header；Authorization请求头，后端用@RequestHeader("Authorization") String token接收。日志规范：
@GetMapping("/{userId}")
public ResultDTO<UserInfoRespDTO> getUserById(@PathVariable("userId") Long userId) {
log.info("【查询用户】入参：userId={}", userId);
UserInfoRespDTO user = userService.getUserById(userId);
log.info("【查询用户】出参：{}", JSON.toJSONString(user));
return ResultDTO.success(user);
}
@PathVariable/@RequestParam，POST 用@RequestBody，参数校验用 JSR380+@Valid；ResultDTO，异常统一由 GlobalExceptionHandler捕获；| 请求类型 | 参数传递位置 | 前端核心写法（示例） | 后端核心写法（Java） | 适用场景 | 关键规范 / 注意事项 |
|---|---|---|---|---|---|
| GET | URL 路径参数 | axios.get('/api/v1/users/1001') | @GetMapping("/{userId}")@PathVariable("userId") Long userId | 查询单个资源（如查用户 / 订单） | 1. 路径参数为唯一标识（ID / 编号） 2. URI 用复数名词，小写 |
| GET | URL 查询参数 | axios.get('/api/v1/orders', { params: { status: 'PAID', pageNum: 1 } }) | @GetMapping("/orders")@RequestParam String status@RequestParam Integer pageNum | 列表筛选 / 分页 / 排序 | 1. 参数名小驼峰 2. 非必传参数加 required = false3. 可封装为 DTO 用 @ModelAttribute接收 |
| POST | Request Body（JSON） | axios.post('/api/v1/users', { username: '张三', password: '123456' }) | @PostMapping("/users")@Valid @RequestBody UserAddReqDTO addDTO | 新增 / 修改资源、复杂查询 | 1. 必加 @Valid触发参数校验2. DTO 加 JSR380 注解（@NotBlank/@Pattern） 3. Content-Type: application/json |
| POST | Form Data（表单） | let formData = new FormData();formData.append('username', '张三');axios.post('/api/v1/users/login', formData) | @PostMapping("/login")@RequestParam String username@RequestParam String password | 简单表单提交（如登录） | 1. Content-Type: application/x-www-form-urlencoded 2. 敏感数据建议转 JSON 传递 |
| POST | Multipart Form Data（文件 + 参数） | let formData = new FormData();formData.append('file', file);formData.append('fileName', '头像.png');axios.post('/api/v1/files/upload', formData) | @PostMapping("/upload")@RequestPart("file") MultipartFile file@RequestParam("fileName") String fileName | 文件上传（单 / 多文件） | 1. 配置文件大小限制（spring.servlet.multipart） 2. 文件参数名统一为 file |
| GET/POST | 请求头参数 | axios.get('/api/v1/users', { headers: { Authorization: 'Bearer token123' } }) | @RequestHeader("Authorization") String token | 传递 token / 语言 / 版本等 | 1. 认证 token 统一放 Authorization头2. 非敏感、固定参数用请求头 |
| POST | 混合参数（路径 + JSON） | axios.post('/api/v1/users/1001/update', { phone: '13800138000' }) | @PostMapping("/{userId}/update")@PathVariable Long userId@RequestBody UserUpdateReqDTO updateDTO | 修改单个资源（带 ID + 参数） | 1. 路径传唯一标识，Body 传修改参数 2. 禁止路径传大量参数 |
pageNum: 1），禁止传字符串（如 pageNum: "1"），后端用 Integer/Long接收。yyyy-MM-dd HH:mm:ss（前端传字符串，后端用 @DateTimeFormat接收）。// 后端接收日期示例
@GetMapping("/orders")
public ResultDTO<?> getOrders(@RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") LocalDateTime startTime) {
// 业务逻辑
}
| 响应场景 | 前端接收格式 | 后端返回写法 |
|---|---|---|
| 成功 | { code: 200, msg: "成功", data: {} } | ResultDTO.success(data) |
| 参数校验失败 | { code: 400, msg: "用户名不能为空" } | ResultDTO.fail(400, "用户名不能为空") |
| 权限不足 | { code: 403, msg: "无权限" } | ResultDTO.fail(403, "无权限") |
| 服务端异常 | { code: 500, msg: "服务器错误" } | ResultDTO.fail(500, "服务器错误") |
| 场景 | 前端反例 | 后端反例 | 问题说明 |
|---|---|---|---|
| GET 传敏感数据 | axios.get('/login?pwd=123456') | @RequestParam String pwd | 密码暴露在 URL / 日志中 |
| POST 用 URL 传大量参数 | axios.post('/users?name=张三&age=20&phone=138...') | @RequestParam接收 10 + 个参数 | URL 长度有限制，可读性差 |
| 路径参数用动词 | axios.get('/api/v1/getUser/1001') | @GetMapping("/getUser/{userId}") | 违反 RESTful 规范，URI 仅表示资源 |
| 文件上传用 JSON | axios.post('/upload', { file: fileObj }) | 用 @RequestBody接收文件 | JSON 无法传输二进制文件 |
@PathVariable、查询参数→@RequestParam、JSON→@RequestBody、文件→@RequestPart；
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online