Какие типы данных могут быть возвращены в Spring MVC?

Типы данных, которые могут быть возвращены в Spring MVC

Spring MVC предоставляет мощный механизм для возврата различных типов данных из контроллеров. Фреймворк автоматически обрабатывает сериализацию и форматирование ответа в зависимости от типа данных и указанных аннотаций.

1. Простые объекты (POJO)

Возврат пользовательских объектов:

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return new User(id, "John Doe", "john@example.com");
    }
}

public class User {
    private Long id;
    private String name;
    private String email;
    
    // Конструктор, getter'ы, setter'ы
    public User(Long id, String name, String email) {
        this.id = id;
        this.name = name;
        this.email = email;
    }
    
    // ... getters and setters
}

// Ответ будет:
// {
//   "id": 1,
//   "name": "John Doe",
//   "email": "john@example.com"
// }

Использование DTO (Data Transfer Object):

@RestController
@RequestMapping("/api/products")
public class ProductController {
    
    @GetMapping("/{id}")
    public ProductDTO getProduct(@PathVariable Long id) {
        // DTO для передачи данных, скрывает внутреннюю структуру
        return new ProductDTO(
            id,
            "Laptop",
            new BigDecimal("999.99"),
            "Electronics"
        );
    }
}

public class ProductDTO {
    private Long id;
    private String name;
    private BigDecimal price;
    private String category;
    
    // Конструктор, getter'ы, setter'ы
}

2. Коллекции (Collections)

Список объектов:

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @Autowired
    private UserService userService;
    
    @GetMapping
    public List<User> getAllUsers() {
        return userService.findAll();
    }
    
    // Ответ будет:
    // [
    //   {"id": 1, "name": "John", "email": "john@example.com"},
    //   {"id": 2, "name": "Jane", "email": "jane@example.com"}
    // ]
}

Массивы:

@RestController
public class DataController {
    
    @GetMapping("/array")
    public int[] getArray() {
        return new int[]{1, 2, 3, 4, 5};
    }
    
    @GetMapping("/objects")
    public User[] getUsers() {
        return new User[]{
            new User(1L, "John", "john@example.com"),
            new User(2L, "Jane", "jane@example.com")
        };
    }
    
    // Ответ будет:
    // [1, 2, 3, 4, 5]
    // [
    //   {"id": 1, "name": "John"},
    //   {"id": 2, "name": "Jane"}
    // ]
}

Set и другие коллекции:

@RestController
@RequestMapping("/api/tags")
public class TagController {
    
    @GetMapping
    public Set<String> getAllTags() {
        return Set.of("java", "spring", "database", "rest");
    }
    
    @GetMapping("/collection")
    public Collection<Tag> getTags() {
        return List.of(
            new Tag("java"),
            new Tag("spring")
        );
    }
    
    // Ответ будет:
    // ["java", "spring", "database", "rest"]
}

3. Map (Словарь)

Возврат HashMap:

@RestController
@RequestMapping("/api/stats")
public class StatsController {
    
    @GetMapping("/summary")
    public Map<String, Object> getSummary() {
        Map<String, Object> summary = new HashMap<>();
        summary.put("totalUsers", 1500);
        summary.put("activeUsers", 1200);
        summary.put("lastUpdated", LocalDateTime.now());
        summary.put("status", "operational");
        return summary;
    }
    
    @GetMapping("/errors")
    public Map<String, Integer> getErrorCounts() {
        return Map.of(
            "404", 45,
            "500", 12,
            "403", 8
        );
    }
    
    // Ответ будет:
    // {
    //   "totalUsers": 1500,
    //   "activeUsers": 1200,
    //   "lastUpdated": "2026-03-22T10:30:45",
    //   "status": "operational"
    // }
}

LinkedHashMap (с сохранением порядка):

@GetMapping("/sorted")
public Map<String, String> getSortedData() {
    Map<String, String> data = new LinkedHashMap<>();
    data.put("first", "A");
    data.put("second", "B");
    data.put("third", "C");
    return data; // Порядок сохранится
}

4. Примитивные типы

Возврат базовых типов:

@RestController
@RequestMapping("/api/data")
public class PrimitiveController {
    
    // String
    @GetMapping("/message")
    public String getMessage() {
        return "Hello, World!";
        // Ответ: "Hello, World!"
    }
    
    // Integer
    @GetMapping("/count")
    public int getCount() {
        return 42;
        // Ответ: 42
    }
    
    // Long
    @GetMapping("/timestamp")
    public long getTimestamp() {
        return System.currentTimeMillis();
        // Ответ: 1711186245000
    }
    
    // Double / Float
    @GetMapping("/pi")
    public double getPi() {
        return Math.PI;
        // Ответ: 3.141592653589793
    }
    
    // Boolean
    @GetMapping("/is-available")
    public boolean isAvailable() {
        return true;
        // Ответ: true
    }
}

5. Объекты-обёртки (Wrapper Types)

Integer, Double, Boolean и т.д.:

@RestController
public class WrapperController {
    
    @GetMapping("/nullable-count")
    public Integer getNullableCount() {
        return 10;
        // Можно вернуть null
    }
    
    @GetMapping("/nullable-value")
    public Double getNullableValue() {
        boolean hasValue = false;
        return hasValue ? 3.14 : null;
        // Ответ: null или число
    }
}

6. Optional

Использование Optional для явного указания, что значение может быть пусто:

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @Autowired
    private UserRepository userRepository;
    
    @GetMapping("/{id}")
    public Optional<User> getUserById(@PathVariable Long id) {
        return userRepository.findById(id);
        // Если пользователь не найден:
        // Ответ: HTTP 200 с пустым телом или HTTP 404 (в зависимости от конфигурации)
    }
    
    // Более явный способ обработки
    @GetMapping("/{id}/explicit")
    public ResponseEntity<User> getUserByIdExplicit(@PathVariable Long id) {
        Optional<User> user = userRepository.findById(id);
        return user.map(ResponseEntity::ok)
                  .orElseGet(() -> ResponseEntity.notFound().build());
        // Ответ: HTTP 200 с пользователем или HTTP 404
    }
}

7. Page / Slice (для пагинации)

Работа с пагинированными результатами:

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @Autowired
    private UserRepository userRepository;
    
    @GetMapping
    public Page<User> getAllUsers(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {
        return userRepository.findAll(
            PageRequest.of(page, size, Sort.by("id").descending())
        );
    }
    
    // Ответ будет:
    // {
    //   "content": [
    //     {"id": 1, "name": "John"},
    //     {"id": 2, "name": "Jane"}
    //   ],
    //   "pageable": {
    //     "pageNumber": 0,
    //     "pageSize": 20,
    //     "sort": {...}
    //   },
    //   "totalPages": 5,
    //   "totalElements": 100,
    //   "numberOfElements": 20,
    //   "first": true,
    //   "last": false
    // }
}

Slice (более лёгкий вариант пагинации):

@GetMapping("/slice")
public Slice<User> getUsersSlice(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "20") int size) {
    return userRepository.findAll(
        PageRequest.of(page, size)
    ).map(user -> user); // Преобразование в Slice
}

8. ResponseEntity

Полный контроль над ответом (статус, заголовки, тело):

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        User savedUser = userRepository.save(user);
        return ResponseEntity
            .status(HttpStatus.CREATED) // HTTP 201
            .header("X-Custom-Header", "value")
            .body(savedUser);
    }
    
    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        Optional<User> user = userRepository.findById(id);
        return user
            .map(u -> ResponseEntity.ok(u)) // HTTP 200
            .orElse(ResponseEntity.notFound().build()); // HTTP 404
    }
    
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userRepository.deleteById(id);
        return ResponseEntity.noContent().build(); // HTTP 204
    }
}

9. Объекты с пользовательской сериализацией

Использование @JsonSerialize:

public class User {
    private Long id;
    private String name;
    
    @JsonSerialize(using = DateTimeSerializer.class)
    private LocalDateTime createdAt;
    
    // Кастомный сериализатор
    public static class DateTimeSerializer extends JsonSerializer<LocalDateTime> {
        @Override
        public void serialize(LocalDateTime value, JsonGenerator gen, SerializerProvider provider) 
                throws IOException {
            gen.writeString(value.format(DateTimeFormatter.ISO_DATE_TIME));
        }
    }
}

10. Потоки (Stream)

Возврат потока данных:

@RestController
@RequestMapping("/api/data")
public class StreamController {
    
    @GetMapping("/stream", produces = "application/x-ndjson") // newline delimited JSON
    public ResponseEntity<StreamingResponseBody> streamData() {
        return ResponseEntity.ok((OutputStream os) -> {
            try {
                for (int i = 0; i < 1000; i++) {
                    Map<String, Object> data = Map.of("index", i, "value", i * 2);
                    os.write((objectMapper.writeValueAsString(data) + "\n").getBytes());
                    os.flush();
                    Thread.sleep(100); // Имитируем обработку
                }
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
        });
    }
}

11. Void

Когда не нужно возвращать тело ответа:

@RestController
@RequestMapping("/api/operations")
public class OperationController {
    
    @PostMapping("/process")
    public ResponseEntity<Void> processData() {
        // Обработка данных
        return ResponseEntity.accepted().build(); // HTTP 202
    }
    
    @PostMapping("/send")
    public void sendNotification() {
        // Отправляем уведомление
        // Ответ: HTTP 200 с пустым телом
    }
}

12. Конвертеры типов (Type Conversion)

Spring MVC автоматически конвертирует типы:

@RestController
@RequestMapping("/api/convert")
public class ConversionController {
    
    @GetMapping("/{date}")
    public String getDateInfo(
            @PathVariable @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate date) {
        return "Дата: " + date;
        // Автоматически конвертирует строку в LocalDate
    }
    
    @GetMapping("/enum/{status}")
    public String getStatusInfo(@PathVariable Status status) {
        return "Статус: " + status.getDescription();
        // Автоматически конвертирует строку в Enum
    }
}

public enum Status {
    ACTIVE("Активен"),
    INACTIVE("Неактивен"),
    DELETED("Удалён");
    
    private String description;
    
    Status(String description) {
        this.description = description;
    }
    
    public String getDescription() {
        return description;
    }
}

13. Любой объект с HttpMessageConverter

Spring использует HttpMessageConverter'ы для сериализации:

// Доступные по умолчанию форматы:
// - JSON (Jackson или Gson)
// - XML (JAXB)
// - Protobuf
// - YAML
// - Форма-закодированные данные

@RestController
@RequestMapping("/api/documents")
public class DocumentController {
    
    @GetMapping("/{id}", produces = "application/json")
    public Document getAsJson(@PathVariable Long id) {
        return documentRepository.findById(id).orElse(null);
    }
    
    @GetMapping("/{id}", produces = "application/xml")
    public Document getAsXml(@PathVariable Long id) {
        return documentRepository.findById(id).orElse(null);
    }
    
    @GetMapping("/{id}", produces = "text/csv")
    public String getAsCsv(@PathVariable Long id) {
        Document doc = documentRepository.findById(id).orElse(null);
        return doc.toCsv(); // Кастомная конвертация
    }
}

Лучшие практики

// 1. Используй DTO для контролля над сериализацией
@GetMapping("/{id}")
public UserDTO getUser(@PathVariable Long id) {
    User user = userRepository.findById(id).orElseThrow();
    return new UserDTO(user); // Только нужные поля
}

// 2. Используй ResponseEntity для контроля над статусом
@PostMapping
public ResponseEntity<UserDTO> createUser(@RequestBody CreateUserRequest request) {
    User user = userRepository.save(new User(request.getName()));
    return ResponseEntity.status(HttpStatus.CREATED).body(new UserDTO(user));
}

// 3. Используй Page для пагинации
@GetMapping
public Page<UserDTO> getAllUsers(Pageable pageable) {
    return userRepository.findAll(pageable).map(UserDTO::new);
}

// 4. Явно указывай produces для контроля формата
@GetMapping(produces = MediaType.APPLICATION_JSON_VALUE)
public List<UserDTO> getAllUsersJson() {
    return userRepository.findAll().stream()
        .map(UserDTO::new)
        .collect(Collectors.toList());
}

Выводы

Spring MVC поддерживает возврат:

• Простых объектов (POJO, DTO)
• Коллекций (List, Set, Array, Map)
• Примитивных типов
• Optional, Page, Slice
• ResponseEntity для полного контроля
• Потоков данных
• Любых объектов через HttpMessageConverter'ы

Правило выбора:

• List/Page — для коллекций
• DTO — для контроля над полями
• ResponseEntity — для контроля над статусом и заголовками
• Map — для неструктурированных данных
• Примитивы — для простых значений

Fra правильный выбор типа данных делает API более понятным, безопасным и легким в поддержке.