Англійська для Astro Actions

Astro Actions дозволяє командам визначати логіку на стороні сервера, яку можна викликати з клієнта з повною безпекою типів, замінюючи ad-hoc API маршрути для подачі форм і мутацій. Обговорення їх чітко означає відрізняти «дію» від простої кінцевої точки API, і бути точним щодо перевірки, форм помилок і прогресивного поліпшення. У цьому підручнику наведено словник, який використовується для обговорення дій під час перегляду коду і обговорення архітектури.

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

Action — типова функція на стороні сервера, визначена в src/actions/, викликана з клієнтських компонентів з автоматичним виведенням типу і без ручного fetch boilerplate.

• “Ми перенесли підписку на розсилку новин з необробленого маршруту API до дії, щоб клієнт автоматично отримував помилки введення.” *

** Схема вводу ** — схема Zod, приєднана до дії, яка перевіряє і аналізує вхідні аргументи перед запуском обробника.

• “Схема вводу відкидає запит ще до того, як він досягне нашого обробника, якщо відсутнє поле електронної пошти.” *

** Прогресивно розширено ** — властивість Actions, яка дозволяє формі працювати як звичайний HTML POST, коли JavaScript ще не завантажено, а потім переходити до виклику на основі отримання, коли JavaScript буде завантажено.

• “Оскільки цей модуль створено з метою покращення, форма все одно буде надсилати дані коректно, навіть якщо пакунок JS не завантажиться.” *

** Action error ** — об’ єкт структурованої помилки ( ActionError ) з code і message, який може бути викинуто дією, надаючи клієнту передбачувану форму для обробки. “Замість того, щоб показувати загальну помилку, показуйте ActionError з кодом CONFLICT, щоб клієнт міг показати правильну помилку.”

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

** Обробник дій ** — тіло функції, яке виконує логіку сервера після того, як буде виконано перевірку введення. “Зберігати обробник дій у вигляді звичайної функції — відправляти фактичні записи бази даних до окремої функції служби, щоб її можна було перевірити поза дією.”

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

• “Це дія або простий API маршрут? Ми повинні бути послідовними в коді.»
• «Вхідна схема повинна відкидати це перед тим, як вона потрапить в базу даних, а не після.»
• «Чи працює ця форма з вимкненим JavaScript, чи ми порушили прогресивне поліпшення?»
• «Відкинь ActionError тут замість сирого Error, щоб клієнт отримав правильний код помилки»
• «Давайте розмістимо пов’язані дії в одному файлі, замість того, щоб розкидати їх по маршрутах»

Приклади речення

Пояснення вибору реалізації у описі PR:

• “Я перетворив форму контакту на дію Astro, щоб ми могли отримати безпеку типів від початку до кінця між схемою і клієнтом, і форма все ще працює елегантно без JavaScript.” *

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

Обговорення архітектури з колегою:

• “Оскільки дії є лише функціями сервера, ми можемо використовувати ту ж схему перевірки як для дії, так і для фонового завдання, яке обробляє ті ж дані пізніше.” *

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

• Використовуйте “action” замість “endpoint” при обговоренні Astro Actions — цей термін містить інформацію про безпеку типів і колокацію, яку не містить “endpoint”.
• Під час повідомлення про ваду перевірки, вкажіть, чи є помилка у схемі вводу або у логіці обробки — їх зневаджують по- іншому.
• Підкреслюйте прогресивно розширення, коли пояснюєте нетехнічним користувачам, чому форма « просто працює » навіть на повільних з’ єднаннях.
• Використовувати ** ActionError ** за назвою у коментарях перегляду коду замість того, щоб говорити « throw a proper error », що є неоднозначним щодо очікуваної форми.

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

1. Поясніть у двох реченнях, чому дію Astro Action легше зберегти безпечним для введення, ніж написаний вручну маршрут API.
2. Написати звіт про помилку у одному реченні з описом дії, яка не перевіряє введення належним чином.
3. Опишете вашими словами, що означає « поступове поліпшення » для форми, створеної за допомогою Astro Actions.

На практиці: Навігація та співпраця

Будьмо чесними - навіть з твердим розумінням технічних концепцій за Astro Actions - безпечні серверні функції, ретельна перевірка вводу і стратегічне прогресивне поліпшення - справжня проблема часто полягає в * комунікації * цих ідей ефективно в професійному середовищі розробки. Це не просто написання коду; це про вираження ваших міркувань, отримання конструктивного зворотнього зв’язку і внесок у спільне розуміння серед вашої команди. Тут нюансований словник стає абсолютно критичним.

Розглянемо такий сценарій: ви надіслали запит на витягнення (PR), у якому описано нову функціональність, яка використовує Astro Actions для обробки розпізнавання користувача. Під час перегляду коду старший розробник залишає коментар до одного з ваших визначень функцій: « Ця логіка перевірки виглядає трохи розмовною. Чи можемо ми спростити його, використовуючи більш декларативний синтаксис?” Це не звинувачення; це пропозиція щодо поліпшення, яка ґрунтується на досвіді. Відповідь в оборонному ключі, можливо, з «я дотримувався найкращих практик», ймовірно, зведе нанівець розмову. Замість цього, вам потрібно визнати їхню точку зору і пояснити * чому * вибрали ваш підхід. Скажіть щось на зразок: “Це гарне спостереження. Я вибрав цей рівень деталізації, щоб переконатися, що ми обробляємо всі можливі крайні випадки, пов’язані з введенням користувача - ключовим принципом Astro Actions, особливо щодо безпеки - і що функція залишається високо тестованою. ” демонструє розуміння і підсилює цінність вашого вибору дизайну. Аналогічно, в обговореннях Slack про архітектурні рішення, такі фрази як «мінімізація обробки на стороні клієнта» (що стосується прогресивного поліпшення) або «зменшення когнітивного навантаження на розробників» (при обговоренні безпеки типів) є набагато більш впливовими, ніж просто заява про те, що ви використовували Astro Actions.

Інша поширена ситуація виникає, коли ви пояснюєте свою роботу нетехнічним учасникам. Вам нужно перевести технический жаргон на понятные им термины, не жертвуя точностью. Замість того, щоб сказати: « Я реалізував надійну перевірку вводу за допомогою Astro Actions », ви можете пояснити: « Ми вбудували захисні заходи у систему, щоб переконатися, що всі дані, введені користувачами, є правильними і безпечними, запобігаючи потенційним проблемам у майбутньому. » Сфокусування на * результаті * — цілісність даних, безпека, досвід користувача — є ключовим.

Нарешті, пам’ ятайте, що сама документація вимагає точної мови. Описи PR повинні чітко вказувати на мету зміни, логіку використання Astro Actions (наприклад, «для забезпечення безпечного обробки конфіденційних даних»), а також будь-які потенційні наслідки для інших частин системи.

Ось короткий приклад того, як ви можете скористатися astro actions у контексті CLI для перевірки перевірки введення:

astro actions validate --file my_function.js --input "invalid_data"

За допомогою цієї команди можна, гіпотетично, запустити перевірку на відповідність вашій функції ( my_function.js ) з наданим некоректним вхідним рядком, а потім отримати вивід, чи відповідає введена функція правилам перевірки. Це лише спрощена ілюстрація того, як ви можете використовувати інструменти для * демонстрації * переваг Astro Actions у дії.