Java 后端 HTTP 请求（GET/POST）传输规范

（3）复杂查询参数（多个筛选条件）

• 封装为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);
}

3. 长度与编码

• 后端无需手动 URL 解码（SpringMVC 自动解码）；
• 若参数含中文 / 特殊字符，确保 application.yml中配置：

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

4. 敏感数据禁止

• 后端通过拦截器 / 切面校验：若 GET 请求参数包含 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;
}

三、POST 请求规范

1. 用途限制

• 用于新增 / 修改 / 删除资源，或传递大量 / 敏感数据的查询；
• 后端注解：统一使用@PostMapping，禁止用@RequestMapping(method = RequestMethod.POST)。

2. 参数传递规则（Java 编码落地）

（1）JSON 参数（主流）

• 后端用@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，需在全局异常处理器中捕获。

（2）文件上传（multipart/form-data）

• 后端用@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);
}

（3）幂等性保障（新增接口）

• 后端通过'唯一业务编号'+ 数据库唯一索引实现幂等；
• 示例：新增订单时，前端传递 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();
}

3. 特殊场景：POST 查询（敏感 / 大量参数）

• 适用于参数过多（超过 URL 长度限制）、含敏感数据的查询；
• ✅ 正确代码示例：

// 复杂订单查询（参数多、含敏感条件）
@PostMapping("/orders/complex-query")
public ResultDTO<PageInfo<OrderListRespDTO>> complexQuery(@RequestBody OrderComplexQueryReqDTO queryDTO) {
    PageInfo<OrderListRespDTO> page = orderService.complexQuery(queryDTO);
    return ResultDTO.success(page);
}

四、通用规范（GET/POST 均适用）

1. URI 命名规则（Java 编码落地）

• Controller 类上的@RequestMapping统一以 /api/v{版本号}/开头，资源用复数名词；
• ✅ 正确：@RequestMapping("/api/v1/users")，❌ 错误：@RequestMapping("/api/v1/user")/@RequestMapping("/api/v1/getUser")。

2. 响应规范（统一返回体）

• 后端封装通用响应类 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;
    }
}

3. 异常处理（Java 编码落地）

• 全局异常处理器统一捕获所有异常，返回标准化 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, "服务器内部错误，请稍后重试");
    }
}

4. 接口版本控制

• 后端通过 URI 携带版本号（推荐），禁止通过参数（如 ?version=1）或请求头控制版本；
• ✅ 正确：@RequestMapping("/api/v1/users")，@RequestMapping("/api/v2/users")。

五、反例与正例对照表（Java 编码）

六、Java 后端编码额外规范

1. 请求头规范：
   • 跨域请求：后端配置 CorsConfig，允许前端的 Origin、Method、Header；
   • 认证请求：token 统一放在 Authorization请求头，后端用@RequestHeader("Authorization") String token接收。
   • 所有接口入参 / 出参必须打印日志（使用 SLF4J），禁止打印敏感数据（如密码）；
   • ✅ 示例：
2. 性能规范：
   • GET 请求建议添加缓存（如 Redis），避免频繁查库；
   • POST 请求建议异步处理（如 MQ），耗时操作（如文件解析、数据同步）不阻塞接口响应。

日志规范：

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

总结

1. 编码核心：GET 用@PathVariable/@RequestParam，POST 用@RequestBody，参数校验用 JSR380+@Valid；
2. 响应核心：所有接口统一返回 ResultDTO，异常统一由 GlobalExceptionHandler捕获；
3. 安全核心：GET 禁止传敏感数据，POST 新增接口保证幂等，日志屏蔽敏感信息；
4. 规范核心：URI 用小写复数名词 + 版本号，参数命名小驼峰，编码统一 UTF-8。

补充：前后端参数传递对照总表

补充：说明（前后端协作关键）

1. 通用数据格式

• 字符编码：前后端统一用 UTF-8；
• 数值类型：前端传递数字（如 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) {
    // 业务逻辑
}

2. 错误码 / 响应格式统一

3. 反例对照（禁止写法）

总结

1. 核心匹配：路径参数→@PathVariable、查询参数→@RequestParam、JSON→@RequestBody、文件→@RequestPart；
2. 场景优先：查询用 GET（路径 / 查询参数），新增 / 修改 / 文件用 POST（JSON/FormData）；
3. 规范统一：参数名小驼峰、日期格式统一、响应体结构一致，前后端按表对齐即可避免 90% 的参数传递问题。