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) {
    // 业务逻辑
}