Какой результат отправляешь после обработки на рабочем проекте?

Результат обработки на рабочем проекте: Best Practices

Вопрос касается того, что отправляется клиенту или возвращается в пользовательский код после обработки данных на рабочем проекте. Это фундаментальный аспект архитектуры приложений и правильного API дизайна.

Основные типы результатов

1. Response Object (Объект ответа)

Основной и рекомендуемый подход — возвращение структурированного объекта ответа:

// DTO (Data Transfer Object)
public class UserResponse {
    private UUID id;
    private String name;
    private String email;
    private LocalDateTime createdAt;
    
    public UserResponse(UUID id, String name, String email, LocalDateTime createdAt) {
        this.id = id;
        this.name = name;
        this.email = email;
        this.createdAt = createdAt;
    }
    
    // Getters
    public UUID getId() { return id; }
    public String getName() { return name; }
    public String getEmail() { return email; }
    public LocalDateTime getCreatedAt() { return createdAt; }
}

// Service возвращает этот объект
@Service
public class UserService {
    public UserResponse getUserById(UUID userId) {
        User user = userRepository.findById(userId)
            .orElseThrow(() -> new EntityNotFoundException("User not found"));
        
        return new UserResponse(
            user.getId(),
            user.getName(),
            user.getEmail(),
            user.getCreatedAt()
        );
    }
}

// API endpoint
@RestController
@RequestMapping("/api/v1/users")
public class UserController {
    
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(@PathVariable UUID id) {
        UserResponse response = userService.getUserById(id);
        return ResponseEntity.ok(response);
    }
}

2. Standardized API Response (Стандартизированный ответ)

Для консистентности всего API используется единый формат ответа:

// Обёртка для всех ответов
public class ApiResponse<T> {
    private boolean success;
    private String message;
    private T data;
    private List<String> errors;
    private LocalDateTime timestamp;
    
    public ApiResponse(T data) {
        this.success = true;
        this.message = "Success";
        this.data = data;
        this.timestamp = LocalDateTime.now(ZoneId.of("UTC"));
    }
    
    public ApiResponse(String message, List<String> errors) {
        this.success = false;
        this.message = message;
        this.errors = errors;
        this.timestamp = LocalDateTime.now(ZoneId.of("UTC"));
    }
    
    // Getters
    public boolean isSuccess() { return success; }
    public String getMessage() { return message; }
    public T getData() { return data; }
    public List<String> getErrors() { return errors; }
    public LocalDateTime getTimestamp() { return timestamp; }
}

// Использование
@RestController
public class UserController {
    
    @GetMapping("/api/v1/users/{id}")
    public ResponseEntity<ApiResponse<UserResponse>> getUser(@PathVariable UUID id) {
        try {
            UserResponse user = userService.getUserById(id);
            return ResponseEntity.ok(new ApiResponse<>(user));
        } catch (EntityNotFoundException e) {
            return ResponseEntity.status(HttpStatus.NOT_FOUND)
                .body(new ApiResponse<>("User not found", List.of(e.getMessage())));
        }
    }
}

// JSON ответ:
// {
//   "success": true,
//   "message": "Success",
//   "data": {
//     "id": "123e4567-e89b-12d3-a456-426614174000",
//     "name": "John Doe",
//     "email": "john@example.com",
//     "createdAt": "2025-03-20T10:30:00Z"
//   },
//   "timestamp": "2025-03-20T10:35:00Z"
// }

3. HTTP Status Codes (Коды ответа)

Правильное использование HTTP статус кодов критично:

@RestController
public class UserController {
    
    // 200 OK — успешное получение
    @GetMapping("/users/{id}")
    public ResponseEntity<UserResponse> getUser(@PathVariable UUID id) {
        UserResponse user = userService.getUserById(id);
        return ResponseEntity.ok(user);  // 200
    }
    
    // 201 Created — успешное создание
    @PostMapping("/users")
    public ResponseEntity<UserResponse> createUser(@RequestBody CreateUserRequest req) {
        UserResponse user = userService.createUser(req);
        return ResponseEntity.status(HttpStatus.CREATED).body(user);  // 201
    }
    
    // 204 No Content — успешное удаление без тела ответа
    @DeleteMapping("/users/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable UUID id) {
        userService.deleteUser(id);
        return ResponseEntity.noContent().build();  // 204
    }
    
    // 400 Bad Request — ошибка клиента
    @PostMapping("/users")
    public ResponseEntity<ApiResponse<?>> createUser(@RequestBody @Valid CreateUserRequest req) {
        // Validation errors
        return ResponseEntity.badRequest()
            .body(new ApiResponse<>("Invalid request", errors));  // 400
    }
    
    // 404 Not Found — ресурс не найден
    @GetMapping("/users/{id}")
    public ResponseEntity<ApiResponse<?>> getUser(@PathVariable UUID id) {
        try {
            UserResponse user = userService.getUserById(id);
            return ResponseEntity.ok(new ApiResponse<>(user));
        } catch (EntityNotFoundException e) {
            return ResponseEntity.notFound().build();  // 404
        }
    }
    
    // 500 Internal Server Error — ошибка сервера
    @GetMapping("/users/{id}")
    public ResponseEntity<ApiResponse<?>> getUser(@PathVariable UUID id) {
        try {
            UserResponse user = userService.getUserById(id);
            return ResponseEntity.ok(new ApiResponse<>(user));
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(new ApiResponse<>("Internal server error", 
                    List.of("An unexpected error occurred")));  // 500
        }
    }
}

4. Page/List Response (Список результатов)

Для коллекций данных используется пагинация:

// Spring Data Page
public class PagedResponse<T> {
    private List<T> content;
    private int pageNumber;
    private int pageSize;
    private long totalElements;
    private int totalPages;
    private boolean isFirst;
    private boolean isLast;
    
    public PagedResponse(Page<T> page, List<T> content) {
        this.content = content;
        this.pageNumber = page.getNumber();
        this.pageSize = page.getSize();
        this.totalElements = page.getTotalElements();
        this.totalPages = page.getTotalPages();
        this.isFirst = page.isFirst();
        this.isLast = page.isLast();
    }
}

// Использование
@GetMapping("/users")
public ResponseEntity<PagedResponse<UserResponse>> listUsers(
    @RequestParam(defaultValue = "0") int page,
    @RequestParam(defaultValue = "10") int size) {
    
    Pageable pageable = PageRequest.of(page, size, Sort.by("createdAt").descending());
    Page<User> users = userRepository.findAll(pageable);
    
    List<UserResponse> content = users.getContent().stream()
        .map(user -> new UserResponse(user.getId(), user.getName(), user.getEmail(), user.getCreatedAt()))
        .collect(Collectors.toList());
    
    return ResponseEntity.ok(new PagedResponse<>(users, content));
}

// JSON ответ:
// {
//   "content": [...],
//   "pageNumber": 0,
//   "pageSize": 10,
//   "totalElements": 100,
//   "totalPages": 10,
//   "isFirst": true,
//   "isLast": false
// }

5. Error Handling (Обработка ошибок)

// Custom Exception
public class BusinessException extends RuntimeException {
    private String errorCode;
    private int statusCode;
    
    public BusinessException(String message, String errorCode, int statusCode) {
        super(message);
        this.errorCode = errorCode;
        this.statusCode = statusCode;
    }
    
    public String getErrorCode() { return errorCode; }
    public int getStatusCode() { return statusCode; }
}

// Global Exception Handler
@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(EntityNotFoundException.class)
    public ResponseEntity<ApiResponse<?>> handleEntityNotFound(EntityNotFoundException e) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
            .body(new ApiResponse<>("Resource not found", List.of(e.getMessage())));
    }
    
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiResponse<?>> handleValidationError(MethodArgumentNotValidException e) {
        List<String> errors = e.getBindingResult()
            .getAllErrors()
            .stream()
            .map(ObjectError::getDefaultMessage)
            .collect(Collectors.toList());
        
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
            .body(new ApiResponse<>("Validation failed", errors));
    }
    
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiResponse<?>> handleGenericError(Exception e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(new ApiResponse<>("Internal server error", 
                List.of("An unexpected error occurred")));
    }
}

6. Async/Callback Patterns (Асинхронные операции)

Для долгих операций:

// CompletableFuture
@RestController
public class TaskController {
    
    @PostMapping("/tasks")
    public ResponseEntity<TaskResponse> createTask(@RequestBody CreateTaskRequest req) {
        CompletableFuture<TaskResponse> future = taskService.processAsync(req)
            .thenApply(result -> new TaskResponse(result));
        
        // Возвращаем сразу с ID задачи
        TaskResponse response = new TaskResponse(UUID.randomUUID(), "PROCESSING");
        return ResponseEntity.status(HttpStatus.ACCEPTED).body(response);  // 202
    }
    
    @GetMapping("/tasks/{id}")
    public ResponseEntity<TaskResponse> getTask(@PathVariable UUID id) {
        TaskResponse response = taskService.getTaskStatus(id);
        return ResponseEntity.ok(response);
    }
}

7. Logging и Monitoring

@Aspect
@Component
public class ResponseLoggingAspect {
    
    private static final Logger logger = LoggerFactory.getLogger(ResponseLoggingAspect.class);
    
    @AfterReturning(pointcut = "@annotation(com.example.logging.LogResponse)", 
                    returning = "result")
    public void logResponse(JoinPoint joinPoint, Object result) {
        String methodName = joinPoint.getSignature().getName();
        logger.info("Method: {}, Result: {}", methodName, result);
    }
}

Best Practices

✅ Всегда возвращайте структурированный ответ

✅ Используйте правильные HTTP статус коды

✅ Стандартизируйте формат ответов для всего API

✅ Включайте метаданные (timestamp, pagination info)

✅ Логируйте результаты для debug и monitoring

✅ Используйте DTO вместо Entity для отправки клиенту

✅ Обрабатывайте ошибки централизованно

❌ Не отправляйте null без контекста

❌ Не раскрывайте внутренние детали реализации

❌ Не смешивайте бизнес-логику с HTTP ответами

Заключение

На рабочем проекте результат обработки отправляется в виде:

1. Response Object — структурированный DTO
2. HTTP Status Code — 200, 201, 400, 404, 500 и т.д.
3. Standardized Format — единый формат для всего API
4. Error Details — информация об ошибках (если есть)
5. Metadata — pagination, timestamp, request ID

Это позволяет клиенту легко парсить ответ и обрабатывать различные сценарии.