Number Service

Сервис для поиска N-го минимального числа в Excel файлах формата .xlsx

Описание

Сервис предоставляет REST API для нахождения N-го минимального числа среди чисел, расположенных в столбик в Excel файле. Используется эффективный алгоритм на основе Max Heap без применения встроенных функций сортировки.

Требования

• Java 21
• Maven 3.8+
• Доступ к локальным файлам (для чтения Excel документов)

Сборка проекта с помощью Maven

  mvn clean package

Запуск приложения

Запуск через Maven

  mvn spring-boot:run

Запуск собранного JAR файла

java -jar target/number-service-1.0.0.jar

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

После запуска приложение будет доступно по адресу: http://localhost:8080

Документация API

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI Specification: http://localhost:8080/api-docs

Пример использования

1. Создайте тестовый Excel файл с числами (можно использовать встроенный генератор):

  java -cp target/number-service-1.0.0.jar ru.test.numberservice.util.TestFileCreator

2. Это создаст файл C:/temp/test_numbers.xlsx

3. Откройте Swagger UI (http://localhost:8080/swagger-ui.html)

4. Вызовите метод POST /api/find-nth-min с параметрами:

   • filePath: C:/temp/test_numbers.xlsx
   • n: 3 (для поиска 3-го минимального числа)

5. В ответе вы получите результат - N-ое минимальное число из файла:

Пример содержимого test_numbers.xlsx: 12 17 41 31 54 15 11 10 1

Результат для n=3: 11 (3-е минимальное число: 1, 10, 11, 12, 15...)

Поддерживаемые форматы

• Только .xlsx файлы
• Максимальный размер файла: 10 МБ
• Числа могут быть представлены как числами, так и текстом, содержащим цифры

Обработка ошибок

Сервис возвращает соответствующие HTTP коды ошибок:

• 400 Bad Request - при неверных параметрах или проблемах с файлом
• 500 Internal Server Error - при внутренних ошибках обработки

Пример ошибки:

{
  "status": "BAD_REQUEST",
  "reason": "Validation Error", 
  "message": "File should be xlsx extension",
  "timestamp": "2025-11-15:10:10:10"
}

Структура проекта

• controller - REST контроллеры
• service - бизнес-логика
• validator - валидация входных данных
• exception - обработка исключений
• util - вспомогательные утилиты

Алгоритм работы

Сервис использует алгоритм Max Heap для эффективного поиска N-го минимального элемента:

• Временная сложность: O(M log N), где M - количество чисел в файле
• Пространственная сложность: O(N)
• Не требует полной сортировки всех элементов

Тестирование

Запуск тестов:

   mvn test