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
Веб-сервер на 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
```
Скрипт устанавливает зависимости для Debian/Ubuntu, собирает проект и создаёт deb-пакет.
Или вручную:
```bash
@ -44,19 +46,19 @@ cd ..
### Поля `config.json`
**server**
| Поле | Тип | Значение по умолчанию |
| Поле | Тип | Обязательно |
|---|---|---|
| address | string | `"0.0.0.0"` |
| port | int | `8080` |
| threads | int | `4` |
| address | string | да |
| port | int | да |
| threads | int | да |
**database**
| Поле | Тип | Значение по умолчанию |
|---|---|---|
| host | string | `"localhost"` |
| port | int | `5432` |
| dbname | string | `"testdb"` |
| user | string | `"postgres"` |
| dbname | string | пустая строка |
| user | string | пустая строка |
| password | string | (пусто) |
### Переменные окружения
@ -80,21 +82,52 @@ DB_PASSWORD=secret ./build/bin/cards
| Метод | Путь | Описание |
|---|---|---|
| GET | `/` | Случайная запись из таблицы `random_data` |
| GET | `/cards?count=N` | До `N` случайных записей из таблицы `random_data` |
| GET | `/health` | Проверка состояния сервера |
Параметр `count` обязателен для `/cards`, должен быть целым числом и ограничивается диапазоном от 1 до 1000. Если записей в базе меньше запрошенного числа, сервер вернёт все доступные записи. Для выборок до 10 записей применяется обычная стратегия, для бо́льших — рекурсивный SQL-запрос.
### Пример ответа `GET /`
```json
{
"id": 3,
"name": "Gamma",
"value": 300,
"text": "Third test record",
"description": "Third test record",
"created_at": "2025-01-01 12:00:00",
"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`
```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 (
id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
value INTEGER NOT NULL,
text TEXT NOT NULL,
description TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
> При обновлении существующей базы данных схему нужно мигрировать отдельно: `CREATE TABLE IF NOT EXISTS` не изменяет уже созданные таблицы. Например, для предыдущей схемы с полем `value` выполните `ALTER TABLE random_data RENAME COLUMN value TO text;`.
## systemd
Юнит-файл: `deploy/systemd/cards.service`
@ -158,7 +193,7 @@ cmake ..
cpack
```
Результат: `cards-1.0.0-Linux.deb`
Результат: `cards-1.0.1-Linux.deb`
### Содержимое deb-пакета