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

Directus обгортає існуючу базу даних SQL з автоматично створеним API і панеллю адміністрування, що означає, що його словник поєднує терміни бази даних з термінами CMS. Бути точним про те, чи є щось «збіркою» (таблиця), «потоком» (автоматизація) або «ролем» (група дозволів) зберігає розмови про проект Directus на землі і уникає плутанини з традиційною безголовою CMS. Цей підручник містить основні терміни.

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

** Collection ** — у Directus, таблиця бази даних, відкрита за допомогою API і панелі адміністрування, створена за допомогою Directus або інтроспектована з існуючої схеми. “Оскільки таблиця orders вже існувала в базі даних, Directus автоматично підібрав її як колекцію без будь-якої міграції.”

** Модель даних ** — загальна структура збірок, полів і зв’ язків у проекті Directus, яку можна налаштувати візуально або за допомогою API схеми. “Перед тим, як ми додамо нову функцію, давайте нарисуємо модель даних, щоб ми знали, чи reviews має бути пов’язаний з products як багато-до-одного або багато-до-багатьох.”

** Дозвіл ** — правило доступу з обмеженням за роллю, збіркою і дією (читання, створення, оновлення, вилучення), можливо, фільтрування за полем або за динамічною умовою. “Дозвіл надає доступ для читання до елементів draft тільки якщо користувач є власним автором елемента — це здійснюється за допомогою динамічного фільтра, а не статичного правила.”

** Потік ** — автоматизація без коду або з низьким кодом, яку запускає подія (наприклад, створюється елемент), яка виконує послідовність дій, наприклад, надсилання webhook або перетворення даних. “Ми створили поток, який запускається, коли стан замовлення змінюється на shipped і відсилає webhook до служби виконання.”

** Розширення ** — нетиповий код (інтерфейс, панель, кінцева точка або гачок), який додається до екземпляра Directus для розширення його поведінки за межі вбудованих параметрів налаштування. “Нестандартна логіка обчислення цін, яку Directus не підтримує, тому ми написали її як нестандартне розширення кінцевої точки.”

** Directus SDK ** — офіційний клієнт JavaScript/TypeScript для запитів до Directus API з безпекою типів, зазвичай використовується з фреймворку інтерфейсу. “Ми використовуємо Directus SDK в програмі Next.js, тому запиту на елементи вводяться проти нашої фактичної моделі даних.”

Звичайні фрази

• «Чи керує цією колекцією Directus, чи ми інтроспектували її з існуючої таблиці?»
• Чи потрібний цьому дозволу динамічний фільтр, чи достатньо статичного правила читання/запису?
• “Чи може це бути потоком замість нетипового коду? Можливо, йому не потрібно розширення взагалі»
• «Чи генерує SDK правильні типи тут, чи нам потрібно відтворювати знімок схеми?»
• «Яка роль цього дозволу застосовується до — чи це занадто широко?»

Приклади висловлювань

Пояснення вибору автоматизації у перегляді проекту:

• “Замість написання нетипового розширення, ми створили це як поток — він запускає процес створення елемента, викликає зовнішній webhook перевірки і оновлює поле стану, і все це без використання нетипового коду.” *

Звітування про ваду з правами доступу: “Редакторам надано можливість бачити чернетки, що належать іншим авторам — динамічний фільтр з дозволом на читання не розширює обсяг до user_created, як ми планували.”

Обговорення моделювання даних з колегою: “Ми повинні моделювати tags як відношення багато-до-багатьох між articles і збіркою tags, а не як текстове поле, відокремлене комами — це зробить фільтрування і права доступу набагато простішими для роздумів.”

Професійні поради

• Скажіть « collection », якщо ви маєте на увазі таблицю, відкриту Directus, і « table », якщо ви говорите про сиру базу даних — змішування цих слів може призвести до плутанини щодо того, у якому шарі знаходиться баґ.
• Під час повідомлення про проблему з правами доступу, вкажіть, чи є це статичним правилом або динамічною умовою фільтра, яка неправильно поводиться — їх налаштовують і зневаджують по- різному.
• Використовуйте “flow” спеціально для автоматизації без коду і “extension” для всього, що вимагає нетипового коду, оскільки зацікавлені сторони часто запитують “чи можемо ми уникнути нетипового коду тут?”
• Згадуйте ** Directus SDK ** за назвою, коли обговорюватимемо інтеграцію інтерфейсу, оскільки це означає створення типів, пов’ язаних з живою схемою, а не написання інтерфейсів від руки.

Практичні вправи

1. Поясніть двома реченнями різницю між потоком Directus і розширенням Directus.
2. Напишіть звіт про помилку у одному реченні, описавши дозвіл, який має занадто широкий обсяг.
3. Опишете вашими словами, чому інтроспекція існуючої таблиці бази даних відрізняється від створення нової збірки з нуля.

Переклади: «Переклад з німецької мови»

Сам Directus є надзвичайно ясним у своїй документації — ключова перевага для розробників, які вивчають англійську. Однак, перекладання * концепцій * - особливо навколо структур дозволів, складної логіки потоку або нюансованих вимог до розширення - часто вимагає більше, ніж просто прямого перекладу технічних термінів. Це розуміння основного наміру і чітке вираження цього в англомовному контексті. Це те, з чим борються багато нерідних носіїв, зосереджуючись на точному виборі слів, а не на ефективному передачі значення. Здається незначним зсув у фразування може повністю змінити запит або зворотній зв’язок - особливо при співпраці з міжнародними командами.

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

Крім того, важливо розуміти тонкі відмінності у фразуваннях, пов’язаних з підзвітністю. Фрази на зразок « Я виправив цю ваду » звучать занадто самовпевнено; замість цього спробуйте « Я виправив цю ваду », або ще краще, « Я вирішив проблему, визначену за [ІД вади] ». Це змінює акцент з індивідуального досягнення на спільний підхід до вирішення проблем. Аналогічно, при описі функціональності розширення, уникай жаргону, наприклад, «використання API» і оберіть більш описову мову: «Це розширення інтегрується з базою даних Directus для…»

Нарешті, зверніть увагу на рівень формальності, відповідний культурі вашої команди. Це неформальна розмова в Slack чи офіційний опис PR? Зміна вашого тону відповідно значно поліпшить розуміння і зменшить нерозуміння.

Ось приклад використання directus-cli для отримання даних за запитом:

directus-cli db query --table=products --where="category_id = 123"

За допомогою цієї команди можна вказати простий і чіткий спосіб вказання запиту на базу даних, що є обов’ язковим для ефективного передачі технічних інструкцій. Використання -- для відокремлення параметрів є стандартною практикою CLI, але навіть цей простий елемент повинен бути послідовно зрозумілим на різних платформах.