Java 后端HTTP 请求(GET/POST)传输规范

// 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);
    }
}

// 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);
}

// 封装查询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);
}

server:
  tomcat:
    uri-encoding: UTF-8
spring:
  http:
    encoding:
      charset: UTF-8
      enabled: true
      force: true

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;
}

// 新增用户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, "新增用户成功");
}

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);
}

@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);
}

@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;
    }
}

@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, "服务器内部错误，请稍后重试");
    }
}

@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);
}

// 后端接收日期示例
@GetMapping("/orders")
public ResultDTO<?> getOrders(@RequestParam @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") LocalDateTime startTime) {
    // 业务逻辑
}