jin132 / urlshortener

REST-сервис сокращения ссылок на Java

Url Shortener

Краткое описание

REST-сервис сокращения ссылок на Java. Используемые фреймворки и библиотеки:

• Spring (Boot, Data, Test);
• Lombok;
• JUnit и Mockito;
• встраиваемая СУБД H2.

Сборка проекта:

$ cd urlshortener
$ mvn package

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

$ java -jar ./target/urlshortener-1.0.jar

Ограничения

Максимальное количество возможных ссылок составляет Integer.MAX_VALUE из-за поля id класса edu.yuferovalex.urlshortener.model.Url, а также реализации класса edu.yuferovalex.urlshortener.utils.Base62.

Описание алгоритма генерации коротких имен

Генерация короткого имени происходит переводом идентификатора записи, сгенерированного базой данных, в 62-ричную систему счисления.

Краткое описание классов

В корневом пакете проекта edu.yuferovalex.urlshortener находится класс Application, содержащий в себе точку входа в приложение.

В пакете controller содержатся следующие классы:

• RedirectController - контроллер, осуществляющий переадресацию;
• GenerateController - контроллер, осуществляющий генерацию новых коротких ссылок;
• StatisticController - контроллер, позволяющий получить доступ к статистике переходов по ссылкам;
• GlobalExceptionHandler - обработчик ошибок, возвращаемых контроллерами.

В пакете service содержатся классы:

• UrlService - сервис, реализующий основную логику данной программы;
• UrlServiceException - базовый класс исключений, генерируемых классом UrlService;
• LinkNotFoundException - исключение, генерируемое классом UrlService, если ссылка, переданная как параметр, не была найдена в хранилище;
• WrongLinkException - исключение, генерируемое классом UrlService, если ссылка, переданная как параметр, имела неверный формат.

В пакете repository содержится интерфейс хранилища данных UrlRepository, логика которого имплементируется автоматически с помощью библиотеки Spring Data JPA.

В пакете model содержатся:

• Url - класс-модель данных, хранящихся в UrlRepository;
• RankedUrl - интерфейс проекции Url с данными о ранге ссылки (позиции в рейтинговом списке по количеству переходов)

В пакете utils содержится статический класс Base62, осуществляющий перевод чисел типа Integer в строку, содержащую то же число в 62-ричной системе счисления, и обратно. Также пакет содержит класс исключений Base62Exception, выбрасываемый выше описанным классом, при неверном формате строки.

Описание внешнего программного интерфейса

Генерация коротких ссылок

Для создания новой короткой ссылки необходимо послать POST-запрос на адрес /generate. В теле запроса дожен находиться объект в формате JSON со строковым параметром original. Этот параметр дожен удовлетворять следующим требованиям:

• не пустая строка;
• максимальный допустимый размер строки - 2000 символов;
• строка должна соответствовать формату URL с обязательным указанием протокола.

В ответе возвращается объект с единственным полем link, в котором указывается сгенерированная короткая ссылка.

Пример запроса:

POST /generate HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
	"original": "https://some-server.com/some/url?some_param=1"
}

Пример ответа:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "link": "/l/1va"
}

В случаях если поле original будет иметь неверный формат, клиенту возвращается код 400 Bad Request и короткая ссылка не будет создана.

Переход по короткой ссылке

Для перехода по короткой ссылке необходимо осуществить GET-запрос по ссылке, возвращенной на шаге генерации.

GET /l/1va HTTP/1.1

В случаях если короткое имя будет иметь неверный формат, клиенту возвращается код 400 Bad Request. В случаях если короткое имя не существует в базе данных, клиенту возвращается код 404 Not Found.

Статистика

Статистика по конкретным ссылкам

Ресурс /stats/{some-short-name} обрабатывает GET-запрос и возвращает статистику переходов по конкретной ссылке. Параметры пути запроса:

• some-short-name - идентификатор ссылки.

В ответе сервиса должен содержаться JSON-объект со следующими полями:

• link - сгенерированная короткая ссылка;
• original - оригинальная ссылка;
• rank - место ссылки в топе запросов;
• count - число запросов по короткой ссылке.

Пример запроса:

GET /stats/some-short-name HTTP/1.1

Пример ответа:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "link": "/l/some-short-name",
    "original": "http://some-server.com/some/url",
    "rank": 1,
    "count": 100500
}

В случаях если короткое имя будет иметь неверный формат, клиенту возвращается код 400 Bad Request. В случаях если короткое имя не существует в базе данных, клиенту возвращается код 404 Not Found.

Рейтинг ссылок

Ресурс /stats обрабатывает GET-запрос и возвращает статистику запросов с сортировкой по частоте запросов по убыванию и возможностью постраничного отображения. Параметры строки запроса:

• page - номер страницы (значение по умолчанию: 0, ограничения: только положительные числа или 0);
• count - число записей, отображаемых на странице (минимальное значение: 1, максимальное возможное значение: 100, значение по умолчанию: 100)

В ответе сервиса содержится массив из JSON-объектов, описанных в разделе Статистика по конкретным ссылкам.

Пример запроса:

GET /stats?page=1&count=2 HTTP/1.1

Пример ответа:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "link": "/l/some-short-name",
        "original": "http://some-server.com/some/url",
        "rank": 1,
        "count": 100500
    },
    {
        "link": "/l/some-another-short-name",
        "original": "http://another-server.com/some/url",
        "rank": 2,
        "count": 40000
    }
]

В случаях нарушения ограничений на параметры page и/или count будет возвращен код 400 Bad Request.