adwet
/
cards
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update API and schema documentation

This commit is contained in:
Andrey Kutin 2026-10-23 20:39:45 +03:00
parent 07f571dbc9
commit 151676df2b
1 changed files with 46 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
README.md
View File

@ -1,6 +1,6 @@
# cards # cards
Веб-сервер на C++20 с использованием Boost.Beast и PostgreSQL. Отдаёт случайные записи из базы данных по REST API. Веб-сервер на C++20 с использованием Boost.Beast и PostgreSQL. Отдаёт случайные записи из таблицы `random_data` по HTTP API.
## Требования ## Требования
@ -22,6 +22,8 @@ sudo apt-get install libboost-all-dev libpq-dev libpqxx-dev nlohmann-json3-dev c
./configure.sh ./configure.sh
``` ```
Скрипт устанавливает зависимости для Debian/Ubuntu, собирает проект и создаёт deb-пакет.
Или вручную: Или вручную:
```bash ```bash
@ -44,19 +46,19 @@ cd ..
### Поля `config.json` ### Поля `config.json`
**server** **server**
| Поле | Тип | Значение по умолчанию | | Поле | Тип | Обязательно |
|---|---|---| |---|---|---|
| address | string | `"0.0.0.0"` | | address | string | да |
| port | int | `8080` | | port | int | да |
| threads | int | `4` | | threads | int | да |
**database** **database**
| Поле | Тип | Значение по умолчанию | | Поле | Тип | Значение по умолчанию |
|---|---|---| |---|---|---|
| host | string | `"localhost"` | | host | string | `"localhost"` |
| port | int | `5432` | | port | int | `5432` |
| dbname | string | `"testdb"` | | dbname | string | пустая строка |
| user | string | `"postgres"` | | user | string | пустая строка |
| password | string | (пусто) | | password | string | (пусто) |
### Переменные окружения ### Переменные окружения
@ -80,21 +82,52 @@ DB_PASSWORD=secret ./build/bin/cards
| Метод | Путь | Описание | | Метод | Путь | Описание |
|---|---|---| |---|---|---|
| GET | `/` | Случайная запись из таблицы `random_data` | | GET | `/` | Случайная запись из таблицы `random_data` |
| GET | `/cards?count=N` | До `N` случайных записей из таблицы `random_data` |
| GET | `/health` | Проверка состояния сервера | | GET | `/health` | Проверка состояния сервера |
Параметр `count` обязателен для `/cards`, должен быть целым числом и ограничивается диапазоном от 1 до 1000. Если записей в базе меньше запрошенного числа, сервер вернёт все доступные записи. Для выборок до 10 записей применяется обычная стратегия, для бо́льших — рекурсивный SQL-запрос.
### Пример ответа `GET /` ### Пример ответа `GET /`
```json ```json
{ {
"id": 3, "id": 3,
"name": "Gamma", "name": "Gamma",
"value": 300, "text": "Third test record",
"description": "Third test record", "description": "Third test record",
"created_at": "2025-01-01 12:00:00", "created_at": "2025-01-01 12:00:00",
"timestamp": 1735732800000000000 "timestamp": 1735732800000000000
} }
``` ```
### Пример ответа `GET /cards?count=2`
```json
{
"data": [
{
"id": 3,
"name": "Gamma",
"text": "Third test record",
"description": "Third test record",
"created_at": "2025-01-01 12:00:00"
},
{
"id": 5,
"name": "Delta",
"text": "Fourth test record",
"description": "Fourth test record",
"created_at": "2025-01-01 12:00:00"
}
],
"count": 2,
"requested_count": 2,
"total_available": 5,
"strategy": "slow",
"timestamp": 1735732800000000000
}
```
### Пример ответа `GET /health` ### Пример ответа `GET /health`
```json ```json
@ -106,7 +139,7 @@ DB_PASSWORD=secret ./build/bin/cards
## База данных ## База данных
При первом запуске автоматически создаётся таблица `random_data` и заполняется десятью тестовыми записями. При первом запуске автоматически создаётся таблица `random_data`. Начальные данные сервер не добавляет: их необходимо загрузить самостоятельно.
Схема таблицы: Схема таблицы:
@ -114,12 +147,14 @@ DB_PASSWORD=secret ./build/bin/cards
CREATE TABLE random_data ( CREATE TABLE random_data (
id SERIAL PRIMARY KEY, id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL, name VARCHAR(100) NOT NULL,
value INTEGER NOT NULL, text TEXT NOT NULL,
description TEXT, description TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
); );
``` ```
> При обновлении существующей базы данных схему нужно мигрировать отдельно: `CREATE TABLE IF NOT EXISTS` не изменяет уже созданные таблицы. Например, для предыдущей схемы с полем `value` выполните `ALTER TABLE random_data RENAME COLUMN value TO text;`.
## systemd ## systemd
Юнит-файл: `deploy/systemd/cards.service` Юнит-файл: `deploy/systemd/cards.service`
@ -158,7 +193,7 @@ cmake ..
cpack cpack
``` ```
Результат: `cards-1.0.0-Linux.deb` Результат: `cards-1.0.1-Linux.deb`
### Содержимое deb-пакета ### Содержимое deb-пакета