parser is ready
This commit is contained in:
root
@@ -0,0 +1,340 @@
|
||||
# Руководство по API для фронтенда
|
||||
|
||||
## Обзор
|
||||
|
||||
После рефакторинга ParserController теперь поддерживает эффективную работу с фронтендом через строго типизированные DTO и расширенные возможности фильтрации и пагинации.
|
||||
|
||||
## Основные изменения
|
||||
|
||||
### 1. Строгая типизация ответов
|
||||
|
||||
Все ответы API теперь используют DTO классы вместо `Map<String, Object>`:
|
||||
|
||||
- `ApiResponse<T>` - универсальный wrapper для всех ответов
|
||||
- `ParserResultDto` - результат парсинга
|
||||
- `ParserStatsDto` - статистика системы
|
||||
- `HealthCheckDto` - состояние сервиса
|
||||
|
||||
### 2. Пагинация и сортировка
|
||||
|
||||
Поддержка Spring Data пагинации с параметрами:
|
||||
|
||||
- `page` - номер страницы (начиная с 0)
|
||||
- `size` - количество элементов на странице
|
||||
- `sort` - поле для сортировки и направление
|
||||
|
||||
### 3. Фильтрация данных
|
||||
|
||||
Возможность фильтрации по:
|
||||
|
||||
- `sourceName` - источнику новостей
|
||||
- `startDate` - начальной дате
|
||||
- `endDate` - конечной дате
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### 1. Получение записей с фильтрацией и пагинацией
|
||||
|
||||
```http
|
||||
GET /api/parser/items?page=0&size=10&sort=publishedAt,desc&sourceName=Kursiv&startDate=2025-01-01&endDate=2025-01-31
|
||||
```
|
||||
|
||||
**Параметры:**
|
||||
|
||||
- `page` (optional, default: 0) - номер страницы
|
||||
- `size` (optional, default: 20) - размер страницы
|
||||
- `sort` (optional, default: "publishedAt,desc") - сортировка
|
||||
- `sourceName` (optional) - фильтр по источнику
|
||||
- `startDate` (optional) - начальная дата (ISO format)
|
||||
- `endDate` (optional) - конечная дата (ISO format)
|
||||
|
||||
**Ответ:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Записи получены успешно",
|
||||
"data": {
|
||||
"content": [
|
||||
{
|
||||
"id": "...",
|
||||
"sourceName": "Kursiv (Бизнес/экономика)",
|
||||
"title": "Заголовок новости",
|
||||
"url": "https://kursiv.media/...",
|
||||
"publishedAt": "2025-01-14T10:30:00",
|
||||
"addedAt": "2025-01-14T12:00:00",
|
||||
"rawText": "Текст статьи...",
|
||||
"hash": "...",
|
||||
"category": "Бизнес",
|
||||
"analytics": {
|
||||
"summary": null,
|
||||
"sentiment": null,
|
||||
"tags": [],
|
||||
"entities": {}
|
||||
}
|
||||
}
|
||||
],
|
||||
"pageable": {
|
||||
"sort": {
|
||||
"sorted": true,
|
||||
"unsorted": false,
|
||||
"empty": false
|
||||
},
|
||||
"pageNumber": 0,
|
||||
"pageSize": 10,
|
||||
"offset": 0,
|
||||
"paged": true,
|
||||
"unpaged": false
|
||||
},
|
||||
"totalElements": 25,
|
||||
"totalPages": 3,
|
||||
"last": false,
|
||||
"first": true,
|
||||
"numberOfElements": 10,
|
||||
"size": 10,
|
||||
"number": 0,
|
||||
"sort": {
|
||||
"sorted": true,
|
||||
"unsorted": false,
|
||||
"empty": false
|
||||
},
|
||||
"empty": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Статистика системы
|
||||
|
||||
```http
|
||||
GET /api/parser/stats
|
||||
```
|
||||
|
||||
**Ответ:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Статистика получена успешно",
|
||||
"data": {
|
||||
"totalItems": 150,
|
||||
"sourceStatistics": {
|
||||
"Kursiv (Бизнес/экономика)": 75,
|
||||
"Kapital.kz (Бизнес)": 75
|
||||
},
|
||||
"lastUpdate": "2025-01-14T12:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Запуск парсинга
|
||||
|
||||
#### Парсинг всех источников
|
||||
|
||||
```http
|
||||
POST /api/parser/parse/all
|
||||
```
|
||||
|
||||
**Ответ:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Парсинг всех источников завершен успешно",
|
||||
"data": [
|
||||
{
|
||||
"source": "Kursiv",
|
||||
"processedItems": 15,
|
||||
"totalItemsInDb": 90,
|
||||
"status": "completed"
|
||||
},
|
||||
{
|
||||
"source": "Kapital",
|
||||
"processedItems": 12,
|
||||
"totalItemsInDb": 90,
|
||||
"status": "completed"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Парсинг конкретного источника
|
||||
|
||||
```http
|
||||
POST /api/parser/parse/kursiv
|
||||
POST /api/parser/parse/kapital
|
||||
```
|
||||
|
||||
### 4. Проверка состояния
|
||||
|
||||
#### Общее состояние
|
||||
|
||||
```http
|
||||
GET /api/parser/health
|
||||
```
|
||||
|
||||
**Ответ:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Сервис работает",
|
||||
"data": {
|
||||
"status": "UP",
|
||||
"service": "RSS Parser System",
|
||||
"timestamp": 1705123456789,
|
||||
"scheduler": "Enabled - runs every 30 minutes"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Состояние MongoDB
|
||||
|
||||
```http
|
||||
GET /api/parser/health/mongodb
|
||||
```
|
||||
|
||||
**Ответ при успехе:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "MongoDB подключение успешно",
|
||||
"data": {
|
||||
"status": "UP",
|
||||
"message": "MongoDB подключение успешно",
|
||||
"timestamp": 1705123456789
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Ответ при ошибке:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "Ошибка подключения к MongoDB",
|
||||
"data": {
|
||||
"status": "DOWN",
|
||||
"message": "Ошибка подключения к MongoDB: Command failed with error 13 (Unauthorized)",
|
||||
"timestamp": 1705123456789,
|
||||
"suggestion": "Проверьте учетные данные в application.properties"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Примеры использования
|
||||
|
||||
### 1. Получение последних новостей с пагинацией
|
||||
|
||||
```javascript
|
||||
// Получить первую страницу с 10 записями, отсортированными по дате публикации
|
||||
fetch('/api/parser/items?page=0&size=10&sort=publishedAt,desc')
|
||||
.then((response) => response.json())
|
||||
.then((data) => {
|
||||
if (data.success) {
|
||||
const items = data.data.content;
|
||||
const totalPages = data.data.totalPages;
|
||||
// Обработка данных
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### 2. Фильтрация по источнику
|
||||
|
||||
```javascript
|
||||
// Получить только новости от Kursiv
|
||||
fetch('/api/parser/items?sourceName=Kursiv (Бизнес/экономика)&page=0&size=20')
|
||||
.then((response) => response.json())
|
||||
.then((data) => {
|
||||
if (data.success) {
|
||||
const kursivNews = data.data.content;
|
||||
// Обработка данных
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### 3. Фильтрация по датам
|
||||
|
||||
```javascript
|
||||
// Получить новости за последнюю неделю
|
||||
const endDate = new Date().toISOString();
|
||||
const startDate = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
|
||||
|
||||
fetch(`/api/parser/items?startDate=${startDate}&endDate=${endDate}`)
|
||||
.then((response) => response.json())
|
||||
.then((data) => {
|
||||
if (data.success) {
|
||||
const recentNews = data.data.content;
|
||||
// Обработка данных
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### 4. Комплексная фильтрация
|
||||
|
||||
```javascript
|
||||
// Получить новости Kapital за последний месяц, отсортированные по дате
|
||||
const endDate = new Date().toISOString();
|
||||
const startDate = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
|
||||
|
||||
fetch(
|
||||
`/api/parser/items?sourceName=Kapital.kz (Бизнес)&startDate=${startDate}&endDate=${endDate}&sort=publishedAt,desc&page=0&size=50`
|
||||
)
|
||||
.then((response) => response.json())
|
||||
.then((data) => {
|
||||
if (data.success) {
|
||||
const kapitalNews = data.data.content;
|
||||
const totalCount = data.data.totalElements;
|
||||
// Обработка данных
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### 5. Получение статистики
|
||||
|
||||
```javascript
|
||||
fetch('/api/parser/stats')
|
||||
.then((response) => response.json())
|
||||
.then((data) => {
|
||||
if (data.success) {
|
||||
const stats = data.data;
|
||||
console.log(`Всего новостей: ${stats.totalItems}`);
|
||||
console.log('По источникам:', stats.sourceStatistics);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## Поддерживаемые форматы дат
|
||||
|
||||
API поддерживает следующие форматы дат:
|
||||
|
||||
- `yyyy-MM-dd` (например: 2025-01-14)
|
||||
- `yyyy-MM-dd'T'HH:mm:ss` (например: 2025-01-14T10:30:00)
|
||||
- `yyyy-MM-dd'T'HH:mm:ss.SSS` (например: 2025-01-14T10:30:00.000)
|
||||
- `yyyy-MM-dd HH:mm:ss` (например: 2025-01-14 10:30:00)
|
||||
|
||||
## Обработка ошибок
|
||||
|
||||
Все ответы API следуют единому формату:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "Описание ошибки",
|
||||
"error": "Детальная информация об ошибке"
|
||||
}
|
||||
```
|
||||
|
||||
HTTP статус коды:
|
||||
|
||||
- `200` - Успешный запрос
|
||||
- `500` - Внутренняя ошибка сервера
|
||||
- `503` - Сервис недоступен (например, MongoDB)
|
||||
|
||||
## Рекомендации для фронтенда
|
||||
|
||||
1. **Кэширование**: Используйте кэширование для статистики и часто запрашиваемых данных
|
||||
2. **Пагинация**: Реализуйте бесконечную прокрутку или традиционную пагинацию
|
||||
3. **Фильтры**: Предоставьте пользователю удобные фильтры по источнику и датам
|
||||
4. **Обновление**: Используйте WebSocket или polling для обновления данных в реальном времени
|
||||
5. **Обработка ошибок**: Всегда проверяйте поле `success` в ответе
|
||||
Reference in New Issue
Block a user