Англійський словник для розробників серверів Convex

Convex - це платформа backend-as-a-service, яка вводить свій власний точний словник для опису того, як дані перетікають, як функції структуровані, і як працюють оновлення в реальному часі. Якщо ви працюєте у команді, яка використовує Convex, ви зустрінете ці терміни у перегляді коду, обговоренні архітектури і технічній документації. У цій статті описано основні слова мови Convex і те, як використовувати їх у професійних розмовах англійською мовою.

Ключовий словник

Мутація Функція Opex, яка записує дані до бази даних. Мутації є транзакційними, автоматично повторюються при невдачі і виконуються на стороні сервера. Еквівалент POST/PUT/DELETE в REST API, але з вбудованими транзакційними гарантіями.

• Приклад: « Я написав мутацію Convex для обробки потоку оплати — вона оновлює стан замовлення і зменшує кількість запасів за одну транзакцію. » *

** Запит ** Функція Opex, яка читає дані з бази даних. Запити типово реактивні, якщо їх використовувати з гачком useQuery — вони автоматично перезапускаються, коли змінюються дані, що лежать в основі.

• Приклад: « Список продуктів підтримується запитом Convex, який підписується на таблицю products — він оновлюється в реальному часі без опитування ». *

Акція Випукла функція, яка може викликати зовнішні API, служби або виконувати побічні дії, які неможливо виконати за допомогою запитів і мутацій. Дії не є транзакційними і можуть бути довготривалими. Використовуйте їх для таких завдань, як надсилання електронної пошти, виклик Stripe або створення закінчень за допомогою штучного інтелекту.

• Приклад: « Я написав дію для створення звіту — вона викликає наш API аналітики і записує результат назад до бази даних за допомогою мутації. »*

** useQuery hook (підписка в реальному часі) ** Гачок React для підписування на запит Convex від клієнта. Коли на сервері змінюються основні дані, всі клієнти, які підписалися на цей запит, автоматично отримують оновлення — без опитування, без керування WebSocket.

• Приклад: « Підписатися на повідомлення балачки за допомогою useQuery(api.messages.list) — гачок автоматично обробляє підписку у реальному часі. »*

** Планувальник (запускПісля / запускНа) ** Вбудований у Convex механізм для планування виконання функцій у майбутньому. runAfter затримує виконання на певний час; runAt планує виконання з певним часом. Корисно для запізнених сповіщень, повторних спроб або асинхронних потоків робіт. Приклад: «Я використовував runAfter для розкладу наступного повідомлення через 24 години після реєстрації — це чистіше, ніж підтримувати окреме завдання cron.»

Кронс Convex підтримує функції з плануванням у стилі cron, які виконуються за повторюваним розкладом. Визначені в файлі crons.ts, вони працюють надійно без зовнішньої інфраструктури.

• Приклад: « У нас є cron Convex, який запускається щоночі о півночі для об’ єднання щоденних аналітичних даних і запису підсумкових записів до бази даних. » *

** Зберігання файлів ** Вбудована система зберігання файлів Convex, інтегрована з базою даних Convex. Файл зберігається і посилається за ідентифікатором, а доступ до файла можна керувати за допомогою функцій Convex.

• Приклад: « Фотографії профілю завантажуються за допомогою файлового сховища Convex — ми зберігаємо ідентифікатор файла у записі користувача і генеруємо підписаний URL за запитом. »*

** Векторний пошук ** Вбудований пошук векторної подібності у Convex, який зберігає і запитує високовимірні вбудовування поряд зі звичайними даними. Уможливлює семантичне пошуку і отримання з використанням штучного інтелекту без окремої бази даних векторів.

• Приклад: « Ми використовуємо випуклий векторний пошук для реалізації семантично пошуку документів — вбудовування створюються за допомогою дії і зберігаються у тій же базі даних, що і метадані документа. »*

** Випуклий аутент. ** Розв’ язок розпізнавання першої сторони Convex, який інтегрується з сервером Convex. Обробляє сеанси користувачів, постачальників OAuth і перевірку JWT без потреби у окремій службі автентифікації.

• Приклад: « Ми перейшли від стороннього постачальника автентифікації до Convex Auth — це значно спростило нашу налаштування, оскільки auth state тепер є громадянином першого класу в моделі даних Convex. »*

Фрази і фразеологізми

** “Написати опуклу мутацію” ** Стандартна фраза дії для створення функції запису у Convex.

• Приклад: « Чи можете ви написати мутацію Convex для обробки потоку запитів на друзів? Він повинен створити запит запису і надіслати повідомлення.”*

** « Підписатися на дані за допомогою useQuery » ** Описує шаблон на стороні клієнта для даних у реальному часі. Приклад: «Підпишіться на дані за допомогою useQuery замість отримання вручну — ви отримаєте оновлення в реальному часі безкоштовно.»

** « Запланувати фонове завдання » ** Використання планувальника випуклих об’ єктів для відкладання роботи.

• Приклад: « Давайте заплануємо виконання фонового завдання для надсилання електронної пошти з рахунком після успішного виконання мутації платежу — використовуйте runAfter з 5- секундною затримкою. » *

** « Виклик дії для зовнішніх інтеграцій » ** Стандартне керівництво щодо того, коли слід вживати дії проти мутації. Приклад: «Все, що торкається Stripe або надсилає електронну пошту, повинно викликати дію — мутації є тільки для запису в базу даних.»

** « Запит реактивно оновлюється » ** Описує автоматичну поведінку Convex у реальному часі.

• Приклад: « Вам не потрібно оновлювати сторінку — запит реактивно оновлюється кожного разу, коли змінюється список завдань. » *

Практичні рекомендації

1. «Я написав мутацію для обробки кнопки like — вона збільшує кількість like і створює запис повідомлення в одній атомній операції»
2. «Дашпанель використовує три useQuery підписки — вони всі оновлюють в реальному часі без будь-якого додаткового коду на нашому кінці»
3. «Ми використовуємо дію Convex для створення резюме AI, тому що вона повинна викликати OpenAI API, що не дозволяється в мутації»
4. «Логіка повторення обробляється runAfter — якщо перша спроба зазнає невдачі, дія планує повторити спробу через 60 секунд»
5. «Ми зберігаємо аватари користувачів у сховищі файлів Convex і посилаємося на них за ідентифікатором файлу в документі профілю користувача»

Необхідно уникати помилок

** Виклик зовнішніх API всередині мутації ** Мутації у Convex є транзакційними і повинні лише записуватися у базу даних. Виклик зовнішніх API всередині мутації призведе до помилки. Замість цього використовувати дію. Замість: “Я викликаю API Stripe всередині мутації.” Скажіть: “Я створю мутацію для запису намірів платежу, а потім запустити дію для виклику API Stripe.”

** Плутанина « запит » (Convex) з « запитом бази даних » (SQL) ** У Convex, «запит» є специфічним типом серверної функції з реактивністю і властивостями кешування. Це не те саме, що написання інструкції SQL SELECT. Будь ласка, будьте чіткими, щоб уникнути плутанини. Скажіть: « Я пишу функцію запиту Convex — вона відрізняється від сирого запиту бази даних. Вона підписує клієнтів на оновлення в реальному часі.”

** Опитування замість використання useQuery ** Команди, що мігрують з REST, часто додають інтервали опитування з звички. З опуклим це не потрібно і додає навантаження.

• Замість: « Я буду перевіряти кінцеву точку на оновлення кожні 5 секунд. » *
• Скажіть: « Використовуйте useQuery — Convex автоматично надсилає оновлення до клієнта. Не потрібно голосування.»*

Summary

У Convex є точний словник, який відображає його архітектуру: мутації для записів, запити для реактивних читань, дії для побічних ефектів, планувальники для відкладеної роботи. Зрозумівши ці відмінності — і маючи можливість обговорювати їх англійською — ви станете більш ефективним співробітником у командах, що працюють на Convex. Якщо ви можете сказати « написати мутацію для цього, викликати дію для електронної пошти і підписатися на інтерфейс користувача за допомогою useQuery », ви вільно розмовляєте мовою екосистеми Convex.

На практиці — навігація розмов навколо Convex

Одним з найбільших викликів для не-Convex розробників, які переходять до системи, як ця, не обов’язково розуміти самі технічні концепції - це * говорити * про них. Сама лексика може бути щільною, і переклад між технічними термінами і ясними поясненнями є ключовим для співпраці. Розглянемо сценарій: ви презентуєте нову пропозицію вашій команді, описуючи, як вона використовує підписки в реальному часі Convex. Просто сказати «ми використовуємо підписки» не вдасться. Вам потрібно сформулювати * чому * вони важливі і * як * вони пов’язані з загальною архітектурою системи.

Фрази на кшталт «оптимізація для оновлення з низькою затримкою» або «забезпечення послідовності даних серед одночасних абонентів» є набагато ефективнішими, ніж технічний жаргон. Аналогічно, обговорюючи мутації — зміни, які безпосередньо впливають на вашу базу даних — ви можете почути такі терміни, як « атомні операції » і « цілісність транзакцій ». Не бійтеся пояснити, що мутація — це не просто * будь- яка * зміна; це ретельно контролювана операція, призначена для підтримки точності даних, особливо під великим навантаженням. При перегляді чиєїсь коду, використовуючи такі фрази, як «Цей запит може отримати користь від сторінкування» або «Давайте переробимо цю дію для кращої продуктивності» демонструє спільний підхід і зосереджується на практичних поліпшень, а не просто критикує реалізацію.

Крім того, розуміння нюансів таких термінів, як «планувальник» проти «cron» є життєво важливим. Хоча концепції перекриваються - обидва автоматизують завдання - «планувальник» часто передбачає більш інтегрований робочий процес в екосистемі Convex, що потенційно викликає мутації або дії, засновані на конкретних подіях. Використання точної мови показує, що ви розумієте архітектуру системи і взаємодію компонентів. Це про передачу намірів чітко і впевнено. Не бійтеся ставити прояснюючі питання; краще шукати розуміння, ніж робити припущення.

Ось простий приклад, який показує команду conves, яку використовують для керування cron:

# This script adds a new cron job named "daily_report" that runs every day at 6 AM.
# The action will query the database for user activity and send an email summary.
conves run -- crons add daily-report -- schedule "0 6 * * *" -- action "send_daily_report"

Ця команда підсвічує, яким чином ви можете описати цей процес: « Ми додали завдання cron, яке запускає щоденне створення звітів. », замість простого повідомлення « Запускається cron ». Ясність і точність використовуваної мови демонструє глибше розуміння можливостей Convex. Зрештою, оволодіння цими варіантами вибору слів значно поліпшить спілкування у вашій команді і забезпечить, що всі будуть розуміти цілі і технічні деталі.