Форма, кнопка, запис у базі

Що ти зробиш сьогодні

Теорія

1. Чотири різні дії за однією адресою

Коли браузер звертається до сервера, він надсилає не тільки адресу, а ще й одне слово перед нею — метод HTTP. Метод каже, що саме треба зробити з тим, що лежить за цією адресою.

HTTP — це набір правил, за якими браузер і сервер обмінюються повідомленнями. Коли ти відкриваєш сторінку, браузер надсилає повідомлення на кшталт «GET /u/bohdan.g9/» і отримує у відповідь текст сторінки. Усе, що ти робив на заняттях 02 і 04, було методом GET: відкрив адресу в браузері — браузер зробив GET.

GET

«Покажи мені те, що там є». Нічого не змінює. Саме цей метод браузер надсилає, коли ти вводиш адресу в рядок або клацаєш посилання.

POST

«Додай ось ці дані». Разом із методом сервер отримує вміст — наприклад, назву нової звички. Це те, що робить кнопка «надіслати» під формою.

DELETE

«Видали те, що за цією адресою». Даних із собою не несе — все, що потрібно, є в самій адресі: /api/habits/7 означає «запис із номером 7».

API

Набір адрес, за якими дані забирає інша програма, а не людина. У твоєму сервісі це все, що починається з /api/. Термін уже був на занятті 02, нагадуємо, бо сьогодні він трапиться кілька разів.

Ендпоінт

Окрема адреса всередині API разом із методом. Пара «метод + адреса», яку вміє обробляти твій сервіс: GET /api/habits і POST /api/habits — це два різні ендпоінти, хоча адреса в них однакова.

Адреса може повторюватися, а пара «метод + адреса» — ні. У коді FastAPI це видно одразу: рядок над функцією називає і метод, і адресу.

@app.get("/api/habits")      # віддати список
@app.post("/api/habits")     # додати запис
@app.delete("/api/habits/{habit_id}")   # видалити запис за номером

Чому зміни не роблять через GET

Технічно ніщо не заважає написати ендпоінт GET /api/habits/7/delete і видаляти запис при відкритті цієї адреси. Так робити не можна, і причина практична.

GET вважається безпечним: усі, хто працює з вебом, виходять із того, що відкрити адресу методом GET можна скільки завгодно разів без наслідків. Тому браузер може завантажити посилання наперед, поки ти ще тільки навів на нього курсор. Месенджер, у який ти кинув посилання, відкриває його сам, щоб показати попередній перегляд. Антивірус і поштові фільтри перевіряють посилання так само — заходять і дивляться. Якщо за GET-адресою стоїть видалення, усі ці програми почнуть видаляти твої записи, і жодна з них не зробить нічого поганого зі свого боку.

2. JSON — формат, у якому передають дані

Форма має надіслати на сервер назву звички й кількість днів. Треба якось запакувати ці два значення в один текст, який сервер зможе розібрати назад. Для цього використовують JSON — текстовий формат запису даних, який розуміють усі мови програмування.

{"title": "Читати 20 хвилин", "days": 7}

Виглядає майже як словник Python, і читається так само: ключ, двокрапка, значення. Правил небагато:

• Ключі завжди в подвійних лапках. Одинарні лапки JSON не приймає.
• Текст — у подвійних лапках, числа — без лапок. "days": 7 і "days": "7" — це різні речі: число й текст.
• Список — у квадратних дужках: {"tags": ["книги", "вечір"]}.
• Так і ні пишуться маленькими: true і false, не True.
• Коми після останнього елемента бути не може.

Твій ендпоінт GET /api/habits уже віддає JSON — саме тому в браузері він показує текст у фігурних і квадратних дужках, а не звичну сторінку. Сьогодні той самий формат працюватиме у зворотному напрямку: сторінка надсилатиме JSON серверу.

3. Код відповіді: що сервер каже про результат

На кожен запит сервер відповідає трицифровим числом — кодом стану. Це коротка відповідь на питання «як усе минуло», і вона надходить раніше за самі дані. Ти вже бачив код 200 на занятті 02, коли перевіряв, що /api/ping працює.

Перша цифра ділить коди на групи, і в нашій роботі важливі три:

Різниця між групою 4xx і групою 5xx принципова, і сьогодні вона тобі знадобиться в обох критеріях перевірки.

• 4xx — проблема у вхідних даних. Сервер отримав запит, перевірив його і відмовив. Код при цьому відпрацював так, як задумано.
• 5xx — проблема в коді сервера. Запит міг бути цілком нормальний, але функція, яка його обробляє, зупинилася з помилкою. Це завжди питання до автора коду, тобто до тебе.

Практичний висновок такий. Порожнє поле форми — звичайна ситуація, яку код має передбачити й відповісти на неї кодом 422. Якщо у відповідь приходить 500, це означає, що порожнє поле в коді не передбачене й функція на ньому зупинилася з помилкою. Тому критерій заняття сформульований саме так: порожня назва має давати 422.

4. Валідація: чому перевірки у браузері недостатньо

Валідація — перевірка даних перед тим, як їх використати: чи є обов’язкові поля, чи не порожні вони, чи справді число там, де має бути число.

Перевірити можна у двох місцях, і вони роблять різну роботу.

Перевірка у формі, у браузері

Атрибути required, maxlength, type="number". Браузер сам не дає надіслати форму й підсвічує поле. Це зручність для людини: помилку видно одразу, без звернення до сервера.

Перевірка на сервері

Код усередині ендпоінта, який дивиться на те, що реально прийшло. Це єдина перевірка, яку не можна обійти.

Обійти перевірку у формі просто, і для цього не треба нічого вміти. Запит до твого сервісу можна надіслати командою curl прямо з термінала, узагалі не відкриваючи сторінку. curl — програма командного рядка, яка надсилає запит на вказану адресу й друкує відповідь текстом; ти вже користувався нею на заняттях 01 і 02, сьогодні вона знадобиться знову. Або можна відкрити інструменти розробника — вбудовану в браузер панель, яка відкривається клавішею F12 і показує код сторінки, помилки й усі запити до сервера, — і прибрати атрибут required двома клацаннями. Тому все, що написано у формі, для сервера є побажанням, а не гарантією.

Модель Pydantic

Писати перевірки вручну в кожному ендпоінті довго й легко щось забути. FastAPI вміє перевіряти вхідні дані сам, якщо ти опишеш, які поля очікуєш. Такий опис називається моделлю Pydantic. Pydantic — бібліотека, яка цим займається; вона вже встановлена у спільному віртуальному оточенні групи /opt/club/venv — це тека з бібліотеками Python, одна на всіх, про неї йшлося на занятті 02. Установлювати нічого не треба.

from pydantic import BaseModel, Field

class NewHabit(BaseModel):
    title: str = Field(min_length=1, max_length=200)
    days: int = Field(ge=1, le=365)

Читається це так: очікуємо два поля. title — текст довжиною від 1 до 200 символів. days — ціле число від 1 до 365 (ge — «не менше», le — «не більше»).

Далі ти пишеш у функції ендпоінта item: NewHabit, і FastAPI бере перевірку на себе. Якщо дані не підходять під опис, функція навіть не запускається — у відповідь іде код 422 і текст із переліком полів, які не пройшли. Якщо підходять, у функцію приходить готовий об’єкт, у якого item.title точно рядок, а item.days точно число.

5. Видалення того, чого вже немає

Ситуація трапляється щодня. Людина натиснула «видалити», нічого не відбулося за півсекунди, вона натиснула ще раз. Або відкрила сайт у двох вкладках, видалила запис в одній, а в другій список ще старий і кнопка на місці.

Перший запит видалив рядок і відповів 200. Другий приходить до сервера, коли рядка вже немає. Правильна відповідь тут — 404, «такого немає». Це відповідь із групи 4xx: запит опрацьовано, у таблиці шукали, потрібного рядка не знайшли, і код 404 повідомляє саме про це.

Щоб так вийшло, ендпоінт спочатку перевіряє, чи є такий рядок, і лише потім видаляє. Якщо написати одразу DELETE FROM habit WHERE id = ? без перевірки, помилки не буде: SQLite видалить нуль рядків і поверне звичайний результат. Сервіс відповість 200, хоча насправді нічого не сталося, і сторінка покаже людині, що все гаразд.

6. fetch: сторінка звертається до сервера сама

Звичайна форма в HTML працює так: натиснув кнопку — браузер звернувся до сервера й повністю перезавантажив сторінку. Це помітно: сторінка на мить стає порожньою, потім показується наново, і прокрутка повертається на початок.

fetch — команда JavaScript, яка надсилає запит на сервер із самої сторінки, не перезавантажуючи її. Відповідь приходить у вигляді даних, і код на сторінці сам вирішує, що з ними зробити: дописати рядок у список, показати повідомлення, очистити форму.

JavaScript — мова, якою пишуть код, що виконується в браузері, а не на сервері. Ми її не вивчаємо. Сьогодні блок із fetch ти отримаєш готовим і підставиш у нього назви своїх полів.

форма на сторінці --fetch POST--> ендпоінт FastAPI --INSERT--> таблиця в базі
       ^                                                              |
       +----------- список оновився (fetch GET) <---------------------+

Ще одна деталь, через яку найчастіше плутаються. У браузера є власна, стара поведінка: натиснули кнопку в формі — перезавантажуємо сторінку. Вона спрацьовує сама, поза твоїм кодом. Щоб її зупинити, у першому ж рядку обробника пишуть event.preventDefault() — дослівно «скасувати дію за замовчуванням». Без цього рядка сторінка перезавантажиться, і твій fetch не встигне нічого зробити.

Практика

У прикладах — таблиця habit з полями id, title, days. Це та сама таблиця зі зразка заняття 04. Скрізь підставляй назву своєї таблиці й своїх полів — вони записані у project.yaml у розділі database. project.yaml — це маніфест проєкту, який ти заповнював на занятті 01: короткий файл із назвами, які програма перевірки не має вгадувати, а читає звідти. Нагадування, як виглядає таблиця зразка:

CREATE TABLE habit (
  id    INTEGER PRIMARY KEY,
  title TEXT NOT NULL,
  days  INTEGER NOT NULL
);

NOT NULL у цьому описі означає «у стовпці має бути значення»: додати рядок, не вказавши title, база не дасть. Зверни увагу на межу цієї перевірки — порожній рядок '' для бази теж значення, і NOT NULL його пропускає. Саме тому порожню назву доводиться відсіювати в коді, а не сподіватися на базу.

ssh bohdan.g9@91.219.61.4
curl -s http://127.0.0.1/u/bohdan.g9/api/habits

PORT=$(grep -oP '(?<=--port )\d+' ~/.config/systemd/user/club-api.service)
curl -s http://127.0.0.1:$PORT/api/habits

nano ~/app/main.py

from pathlib import Path

import yaml
from fastapi import FastAPI
from fastapi.responses import JSONResponse

from db import query  # готова заготовка, не редагуємо

from pathlib import Path

import yaml
from fastapi import FastAPI, HTTPException   # ← дописав HTTPException
from fastapi.responses import JSONResponse
from pydantic import BaseModel, Field        # ← цілком новий рядок

from db import query, execute  # ← дописав execute; сам db.py не редагуємо

class NewHabit(BaseModel):
    title: str = Field(min_length=1, max_length=200)
    days: int = Field(ge=1, le=365)

@app.post("/api/habits")
def create_habit(item: NewHabit):
    """Додає запис і повертає його разом із новим id."""
    title = item.title.strip()
    if not title:
        raise HTTPException(status_code=422, detail="Назва не може бути порожня")

    new_id = execute(
        "INSERT INTO habit (title, days) VALUES (?, ?)",
        (title, item.days),
    )
    rows = query("SELECT * FROM habit WHERE id = ?", (new_id,))
    return rows[0]

@app.delete("/api/habits/{habit_id}")
def delete_habit(habit_id: int):
    """Видаляє запис. Якщо такого немає — 404."""
    rows = query("SELECT id FROM habit WHERE id = ?", (habit_id,))
    if not rows:
        raise HTTPException(status_code=404, detail="Такого запису немає")

    execute("DELETE FROM habit WHERE id = ?", (habit_id,))
    return {"deleted": habit_id}

nano ~/app/project.yaml

endpoints:
  ping: "GET /api/ping"
  about: "GET /api/about"
  list: "GET /api/habits"
  create: "POST /api/habits"
  delete: "DELETE /api/habits/{habit_id}"
  login: ""

systemctl --user restart club-api
systemctl --user status club-api

journalctl --user -u club-api -n 30

curl -i -X POST http://127.0.0.1/u/bohdan.g9/api/habits \
  -H "Content-Type: application/json" \
  -d '{"title":"Читати 20 хвилин","days":7}'

curl -i -X POST http://127.0.0.1/u/bohdan.g9/api/habits \
  -H "Content-Type: application/json" \
  -d '{"title":"","days":7}'

curl -i -X POST http://127.0.0.1/u/bohdan.g9/api/habits \
  -H "Content-Type: application/json" \
  -d '{"title":"Пробіли","days":"сім"}'

curl -i -X DELETE http://127.0.0.1/u/bohdan.g9/api/habits/999999

<h2>Додати звичку</h2>
<form id="add-form">
  <label for="f-title">Назва звички</label>
  <input id="f-title" type="text" required maxlength="200">

  <label for="f-days">Скільки днів поспіль</label>
  <input id="f-days" type="number" min="1" max="365" value="1" required>

  <button type="submit">Додати</button>
</form>
<p id="form-msg"></p>

<h2>Мої звички</h2>
<ul id="list"></ul>

<script>
const API = 'api/habits';                            // ← адреса твого ендпоінта

const form   = document.getElementById('add-form');  // ← id форми з кроку 9
const msg    = document.getElementById('form-msg');  // ← id абзацу для повідомлень
const list   = document.getElementById('list');      // ← id списку
const fTitle = document.getElementById('f-title');   // ← id поля назви
const fDays  = document.getElementById('f-days');    // ← id поля числа

async function loadList() {
  let items;
  try {
    const res = await fetch(API);
    if (!res.ok) { msg.textContent = 'Не вдалося прочитати список: ' + res.status; return; }
    items = await res.json();
  } catch (e) {
    msg.textContent = 'Сервер не відповідає. Перевір, чи запущена служба.';
    return;
  }
  list.innerHTML = '';
  for (const it of items) {
    const li = document.createElement('li');
    li.textContent = it.title + ' — ' + it.days + ' дн.';   // ← твої стовпці
    const del = document.createElement('button');
    del.type = 'button';
    del.textContent = 'видалити';
    del.addEventListener('click', function () { removeItem(it.id); });
    li.appendChild(del);
    list.appendChild(li);
  }
}

form.addEventListener('submit', async function (event) {
  event.preventDefault();
  msg.textContent = '';
  let res;
  try {
    res = await fetch(API, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        title: fTitle.value,          // ← твій стовпець
        days: Number(fDays.value)     // ← твій стовпець
      })
    });
  } catch (e) {
    msg.textContent = 'Сервер не відповідає. Перевір, чи запущена служба.';
    return;
  }
  if (res.ok) {
    form.reset();
    await loadList();
  } else if (res.status === 422) {
    msg.textContent = 'Дані не пройшли перевірку. Назва не може бути порожня, ' +
                      'а днів має бути цілим числом від 1 до 365.';
  } else {
    msg.textContent = 'Сервер відповів помилкою ' + res.status;
  }
});

async function removeItem(id) {
  let res;
  try {
    res = await fetch(API + '/' + id, { method: 'DELETE' });
  } catch (e) {
    msg.textContent = 'Сервер не відповідає. Перевір, чи запущена служба.';
    return;
  }
  if (res.ok || res.status === 404) {
    await loadList();
  } else {
    msg.textContent = 'Не вдалося видалити: ' + res.status;
  }
}

loadList();
</script>

sqlite3 ~/data/app.db "SELECT id, title FROM habit ORDER BY id DESC LIMIT 5;"

/opt/club/venv/bin/python -c "import sqlite3, pathlib; \
print(sqlite3.connect(pathlib.Path.home()/'data/app.db') \
.execute('SELECT id, title FROM habit ORDER BY id DESC LIMIT 5').fetchall())"

cd ~/app
git add main.py project.yaml
git commit -m "додав POST і DELETE з перевіркою вхідних даних"
git push origin master

git branch --show-current

Що перевіряє автоматика

Три критерії заняття 05, усі три перевіряє програма. Перевірка запускається за розкладом, тому відмітка в кабінеті з’являється не в ту саму секунду, коли ти виконав команду. Адреси ендпоінтів програма бере з project.yaml, а назву головної таблиці — з розділу database.

Домашнє завдання

journalctl --user -u club-api -n 50

Якщо щось не працює

Сторінка перезавантажується при натисканні кнопки, запис не додається

Це стандартна поведінка браузера для форм, і вона спрацьовує сама. Перший рядок обробника має бути таким:

form.addEventListener('submit', async function (event) {
  event.preventDefault();

Друга можлива причина — код не знайшов форму, тому обробник до неї не додався. Це буває, коли id у тегу <form> написаний інакше, ніж у getElementById('add-form'). Відкрий F12, вкладку Console: там буде рядок Cannot read properties of null із номером рядка. Третя причина — блок <script> стоїть вище за форму й виконався раніше, ніж вона з’явилася; переміщуй його в самий кінець, перед </body>.

У відповідь на форму приходить 422, хоча всі поля заповнені

Назви полів у JSON не збігаються з назвами в моделі Pydantic. Модель чекає рівно ті імена, які в ній написані: title і days. Якщо в блоці fetch відправляється {"name": ..., "count": ...}, для моделі обидва потрібні поля відсутні.

Подивись, яке саме поле не пройшло перевірку — у відповіді 422 FastAPI їх перелічує:

curl -s -X POST http://127.0.0.1/u/bohdan.g9/api/habits \
  -H "Content-Type: application/json" \
  -d '{"title":"Тест","days":3}'

У тексті відповіді шукай "loc" — там указано, у якому полі проблема, і "msg" — у чому вона.

Друга поширена причина: у полі числа порожньо або там не число. Значення з поля вводу завжди приходить рядком, тому в блоці стоїть Number(fDays.value). Якщо поле порожнє, Number('') дає 0, а модель чекає число не менше 1 — і це 422. Якщо в полі текст, Number('три') дає NaN, яке JSON.stringify записує як null, — теж 422. У відповіді це видно за рядком "loc": ["body", "days"]: проблема не в назві, а в днях.

Відповідь 500, у журналі — «no such table» або «no such column»

journalctl --user -u club-api -n 30

Такий рядок означає, що в SQL написана назва, якої в базі немає. Перевір, як таблиця й стовпці називаються насправді:

sqlite3 ~/data/app.db ".schema"

Якщо sqlite3 не встановлений, той самий опис таблиць покаже Python зі спільного оточення:

/opt/club/venv/bin/python -c "import sqlite3, pathlib; \
print('\n'.join(r[0] for r in sqlite3.connect(pathlib.Path.home()/'data/app.db') \
.execute('SELECT sql FROM sqlite_master WHERE sql IS NOT NULL')))"

Найчастіше причина — назва зі зразка (habit, title, days) лишилася в новому коді, а твоя таблиця називається інакше. Регістр тут ні до чого: назви таблиць і стовпців SQLite порівнює без урахування великих і малих літер, тому SELECT Title знайде стовпець title. Натомість варто перевірити написання: одна зайва літера (habits замість habit) або кирилична літера серед латинських — с замість c — дають рівно таке саме повідомлення. Порівняй назву в коді з тим, що надрукувала .schema, символ у символ.

DELETE із браузера відповідає 404, хоча запис існує

Порівняй адресу з тим, що бачиш у вкладці Network (F12). Типові розбіжності: у removeItem замість номера підставляється undefined — це означає, що в записі немає поля id, бо ендпоінт POST повертає не весь рядок, а щось інше; або в адресі з’явилася подвійна коса риска api/habits//7, бо константа API написана з рискою в кінці.

Перевір ендпоінт напряму, без сторінки — підстав номер запису, який точно є в базі:

curl -i -X DELETE http://127.0.0.1/u/bohdan.g9/api/habits/3

Якщо тут 200, а зі сторінки 404, проблема в адресі, яку будує код сторінки. Якщо і тут 404, перевір, які номери взагалі є в таблиці:

sqlite3 ~/data/app.db "SELECT id FROM habit;"

Якщо sqlite3 не встановлений, той самий список віддасть сам сервіс: curl -s http://127.0.0.1/u/bohdan.g9/api/habits.

Служба не піднімається після правки main.py

systemctl --user status club-api показує failed, сторінка /api/ping не відповідає. Причина завжди в останніх рядках журналу:

journalctl --user -u club-api -n 30

• IndentationError — збилися відступи. Python вимагає, щоб у межах одного блоку відступ був однаковий, і забороняє змішувати пробіли з табуляцією. Скільки саме пробілів, мова не диктує; загальноприйнято чотири, і в заготовці зроблено саме так — тримайся цього, щоб файл лишався однорідним.
• NameError: name 'HTTPException' is not defined — забув дописати імпорт із кроку 2 практики.
• NameError: name 'NewHabit' is not defined — клас моделі стоїть у файлі нижче за функцію, яка на нього посилається. Переміщуй class NewHabit вище за @app.post.
• yaml.scanner.ScannerError — зіпсований project.yaml: табуляція замість пробілів або пропущений пробіл після двокрапки.

Виправ файл і повтори systemctl --user restart club-api. Якщо не бачиш помилки очима, поверни останню робочу версію: git diff main.py покаже, що ти змінив, а git restore main.py відкотить файл до останнього коміта.