Spring ResponseEntity的使用详解

public class responseentity<t> extends httpentity<t> {
private final object status;
// 构造方法和其他成员
}

java
// 基本构造 - 只有状态码
responseentity<string> response1 = new responseentity<>(httpstatus.ok);
// 包含响应体和状态码
responseentity<string> response2 = new responseentity<>("hello, world!", httpstatus.ok);
// 包含响应头、响应体和状态码
httpheaders headers = new httpheaders();
headers.add("custom-header", "value");
responseentity<string> response3 = new responseentity<>("data", headers, httpstatus.created);

// 返回 200 ok
responseentity<string> response1 = responseentity.ok("success");
// 返回 201 created（常用于资源创建）
uri location = new uri("/api/users/1");
responseentity<string> response2 = responseentity.created(location).body("user created");
// 返回 204 no content（常用于删除操作）
responseentity<void> response3 = responseentity.nocontent().build();
// 返回 400 bad request
responseentity<string> response4 = responseentity.badrequest().body("invalid request");
// 返回 404 not found
responseentity<void> response5 = responseentity.notfound().build();
// 自定义状态码
responseentity<string> response6 = responseentity.status(httpstatus.accepted).body("request accepted");

@target(elementtype.type)
@retention(retentionpolicy.runtime)
@documented
@controller
@responsebody
public @interface restcontroller {
@aliasfor(annotation = controller.class)
string value() default "";
}

//这行代码定义了一个新的注解类型，名为 restcontroller。
//  @interface关键字是 java 中用于声明注解的特殊语法。
//其余以 @开头的代码（如 @target, @retention等）被称为元注解，
//  它们被应用于另一个注解之上，用于定义该注解的基本行为规则。

//string value() default "";: 这表示 @restcontroller注解有一个
//  名为 value的字符串属性，并且默认值为空字符串。在使用注解时，你可 
//  以写@restcontroller("mycontroller")来设置这个值。
//@aliasfor(annotation = controller.class): 这是 spring 框架
//  提供的强大功能，用于声明别名。它表示 @restcontroller的 value属
//  性，同时也是其元注解 @controller的 value属性的一个别名 。

@restcontroller("userapicontroller") // 指定bean名称
@requestmapping("/api/users")
public class usercontroller {
// 控制器方法
}

@getmapping(
value = "/users/{id}",
produces = mediatype.application_json_value,
consumes = mediatype.application_json_value,
params = "type=admin",
headers = "x-api-version=1"
)
public responseentity<user> getuser(@pathvariable long id) {
// 方法实现
}

@getmapping("/users/{userid}/orders/{orderid}")
public responseentity<order> getorder(
@pathvariable("userid") long userid, // 指定路径变量名
@pathvariable(required = false) long orderid // 可选参数
) {
// 方法实现
}

@getmapping("/users")
public responseentity<page<user>> getusers(
@requestparam(defaultvalue = "0") int page, // 默认值
@requestparam(required = false) string keyword, // 可选参数
@requestparam(name = "page_size", defaultvalue = "10") int size // 参数重命名
) {
// 方法实现
}

public class responseentity<t> extends httpentity<t> {
// 包含状态码、头部信息和响应体
}

// 基本构造
responseentity<string> response = new responseentity<>("hello", httpstatus.ok);
// 包含头部信息
httpheaders headers = new httpheaders();
headers.add("custom-header", "value");
responseentity<string> response = new responseentity<>("data", headers, httpstatus.ok);

// 常用静态方法
responseentity.ok("success"); // 200 ok
responseentity.status(httpstatus.created).body(data); // 201 created
responseentity.nocontent().build(); // 204 no content
responseentity.badrequest().body("error message"); // 400 bad request
responseentity.notfound().build(); // 404 not found

responseentity<string> response = responseentity.status(httpstatus.ok)
.header("custom-header", "value")
.header("cache-control", "no-cache")
.body("response with custom headers");

// 删除操作成功，无需返回内容
@deletemapping("/{id}")
public responseentity<void> deleteresource(@pathvariable long id) {
boolean isdeleted = service.deletebyid(id);
return isdeleted ?
responseentity.nocontent().build() : // 204 no content
responseentity.notfound().build(); // 404 not found
}

responseentity<string> response = responseentity.status(httpstatus.ok)
.header("content-type", "application/json")
.header("cache-control", "no-cache")
.header("x-custom-header", "custom-value")
.body("response with multiple headers");

public class responseentity<t> extends httpentity<t> {
private final object status;
// 多个构造方法
public responseentity(httpstatus status) {
    this(null, null, status);
}

public responseentity(@nullable t body, httpstatus status) {
    this(body, null, status);
}

public responseentity(@nullable t body, @nullable multivaluemap<string, string> headers, 
                     httpstatus status) {
    super(body, headers);
    assert.notnull(status, "httpstatus must not be null");
    this.status = status;
}

// 静态工厂方法
public static bodybuilder status(httpstatus status) {
    assert.notnull(status, "httpstatus must not be null");
    return new defaultbuilder(status);
}

public static bodybuilder ok() {
    return status(httpstatus.ok);
}
}

public enum httpstatus {
// 1xx informational
continue(100, "continue"),
switching_protocols(101, "switching protocols"),
// 2xx success
ok(200, "ok"),
created(201, "created"),
accepted(202, "accepted"),
no_content(204, "no content"),

// 3xx redirection
moved_permanently(301, "moved permanently"),
found(302, "found"),

// 4xx client error
bad_request(400, "bad request"),
unauthorized(401, "unauthorized"),
forbidden(403, "forbidden"),
not_found(404, "not found"),

// 5xx server error
internal_server_error(500, "internal server error"),
bad_gateway(502, "bad gateway");

private final int value;
private final string reasonphrase;

httpstatus(int value, string reasonphrase) {
    this.value = value;
    this.reasonphrase = reasonphrase;
}

// getter 方法
public int value() { return this.value; }
public string getreasonphrase() { return this.reasonphrase; }
}

@restcontroller
@requestmapping("/api/users")
public class usercontroller {
@autowired
private userservice userservice;

// 获取用户 - 200 ok 或 404 not found
@getmapping("/{id}")
public responseentity<userdto> getuser(@pathvariable long id) {
    return userservice.findbyid(id)
            .map(user -> responseentity.ok(user))
            .orelse(responseentity.notfound().build());
}

// 创建用户 - 201 created
@postmapping
public responseentity<userdto> createuser(@valid @requestbody usercreaterequest request) 
        throws urisyntaxexception {
    userdto saveduser = userservice.save(request);
    
    uri location = servleturicomponentsbuilder.fromcurrentrequest()
            .path("/{id}")
            .buildandexpand(saveduser.getid())
            .touri();
            
    return responseentity.created(location).body(saveduser);
}

// 更新用户 - 200 ok
@putmapping("/{id}")
public responseentity<userdto> updateuser(@pathvariable long id, 
                                         @valid @requestbody userupdaterequest request) {
    userdto updateduser = userservice.update(id, request);
    return responseentity.ok(updateduser);
}

// 删除用户 - 204 no content
@deletemapping("/{id}")
public responseentity<void> deleteuser(@pathvariable long id) {
    userservice.deletebyid(id);
    return responseentity.nocontent().build();
}
}

@getmapping("/download/{filename}")
public responseentity<resource> downloadfile(@pathvariable string filename) {
try {
path filepath = paths.get("uploads").resolve(filename).normalize();
resource resource = new urlresource(filepath.touri());
if (resource.exists() && resource.isreadable()) {
    return responseentity.ok()
            .header(httpheaders.content_type, "application/octet-stream")
            .header(httpheaders.content_disposition, 
                   "attachment; filename=\"" + resource.getfilename() + "\"")
            .body(resource);
} else {
    return responseentity.notfound().build();
}
} catch (exception e) {
return responseentity.status(httpstatus.internal_server_error).build();
}
}

@controlleradvice
public class globalexceptionhandler {
@exceptionhandler(resourcenotfoundexception.class)
public responseentity<errorresponse> handlenotfound(resourcenotfoundexception ex) {
    errorresponse error = new errorresponse("not_found", ex.getmessage());
    return responseentity.status(httpstatus.not_found).body(error);
}

@exceptionhandler(methodargumentnotvalidexception.class)
public responseentity<errorresponse> handlevalidationerrors(
        methodargumentnotvalidexception ex) {
    list<string> errors = ex.getbindingresult()
            .getfielderrors()
            .stream()
            .map(error -> error.getfield() + ": " + error.getdefaultmessage())
            .collect(collectors.tolist());
            
    errorresponse errorresponse = new errorresponse("validation_error", "参数验证失败");
    errorresponse.setdetails(errors);
    return responseentity.badrequest().body(errorresponse);
}

@exceptionhandler(exception.class)
public responseentity<errorresponse> handlegenericexception(exception ex) {
    errorresponse error = new errorresponse("internal_error", "服务器内部错误");
    return responseentity.status(httpstatus.internal_server_error).body(error);
}
}

@getmapping
public responseentity<pageresponse<userdto>> getusers(
@requestparam(defaultvalue = "0") int page,
@requestparam(defaultvalue = "20") int size,
@requestparam(defaultvalue = "id,desc") string[] sort) {
page<userdto> users = userservice.findusers(pagerequest.of(page, size, sort.by(sort)));

pageresponse<userdto> response = new pageresponse<>(
    users.getcontent(), 
    users.getnumber(), 
    users.getsize(), 
    users.gettotalelements()
);

return responseentity.ok()
        .header("x-total-count", string.valueof(users.gettotalelements()))
        .header("x-total-pages", string.valueof(users.gettotalpages()))
        .body(response);
}

@getmapping(value = "/{id}",
produces = {mediatype.application_json_value,
mediatype.application_xml_value})
public responseentity<user> getuser(@pathvariable long id) {
user user = userservice.findbyid(id)
.orelsethrow(() -> new resourcenotfoundexception("user not found"));
return responseentity.ok(user);
}

@getmapping("/{id}")
public responseentity<user> getuser(@pathvariable long id,
webrequest request) {
user user = userservice.findbyid(id)
.orelsethrow(() -> new resourcenotfoundexception("user not found"));
// 检查资源是否修改
if (request.checknotmodified(user.getlastmodified().gettime())) {
    return responseentity.status(httpstatus.not_modified).build();
}

return responseentity.ok()
        .lastmodified(user.getlastmodified().gettime())
        .body(user);
}

@getmapping("/{id}")
public mono<responseentity<user>> getuserreactive(@pathvariable long id) {
return userservice.findbyidreactive(id)
.map(user -> responseentity.ok(user))
.defaultifempty(responseentity.notfound().build());
}

@getmapping("/{id}")
public responseentity<userdto> getuser(@pathvariable long id) {
// 使用 optional 避免空指针
return userservice.findbyid(id)
.map(responseentity::ok)
.orelse(responseentity.notfound().build());
}

@data
public class apiresponse<t> {
private boolean success;
private string message;
private t data;
private localdatetime timestamp;
public static <t> apiresponse<t> success(t data) {
    apiresponse<t> response = new apiresponse<>();
    response.setsuccess(true);
    response.setmessage("操作成功");
    response.setdata(data);
    response.settimestamp(localdatetime.now());
    return response;
}

public static <t> apiresponse<t> error(string message) {
    apiresponse<t> response = new apiresponse<>();
    response.setsuccess(false);
    response.setmessage(message);
    response.settimestamp(localdatetime.now());
    return response;
}
}
// 在控制器中使用
@getmapping("/{id}")
public responseentity<apiresponse<userdto>> getuser(@pathvariable long id) {
return userservice.findbyid(id)
.map(user -> responseentity.ok(apiresponse.success(user)))
.orelse(responseentity.status(httpstatus.not_found)
.body(apiresponse.error("用户不存在")));
}