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("用户不存在")));
}