Як пояснити помилку CORS команді Frontend в англійській мові

Помилки CORS відомі тим, що вони заплутують навіть досвідчених розробників, оскільки браузер беззвучно блокує запит у консолі, тоді як сам API часто працює ідеально, коли його викликають з інструменту, на зразок Postman. Якщо ви розробник backend або API, можливість чітко пояснити — англійською мовою — що браузер блокує і чому, збереже команді frontend години вгадування і зупинить їх від припущення, що сам API пошкоджено.

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

** CORS (Cross- Origin Resource Sharing) ** — механізм безпеки переглядача, який блокує веб- сторінку від надсилання запитів до іншого домену, порту або протоколу, якщо сервер явно не дозволить це.

• “Запит зазнав невдачі через CORS, а не через те, що кінцева точка не працює — браузер блокує відповідь ще до того, як ваш код навіть побачить її.” *

** Походження ** — поєднання протоколу, домену і порту, яке визначає, чи вважати два адреси URL « однаковими » або « перехресними » за допомогою переглядача. “Ваш інтерфейс працює на localhost:3000, а API знаходиться на іншому джерелі, тому переглядач розглядає кожен запит як похідний від іншого джерела.”

** Запит попередньої перевірки ** — автоматичний запит OPTIONS, який переглядач надсилає перед певними запитами, щоб запитати сервера про дозвіл перед надсиланням справжнього запиту. “Перед тим, як запит PUT закінчиться, браузер надсилає запит OPTIONS, і саме він зараз зазнає невдачі.”

** Access- Control- Allow- Origin header ** — заголовок відповіді, який повідомляє переглядачу, з яких джерел можна читати відповідь. “У API відсутній заголовок Access-Control-Allow-Origin для вашого домену, тому переглядач відкидає відповідь, навіть якщо сервер повернув 200.”

** Запит з уповноваженими даними ** — запит, який містить куки або заголовки розпізнавання, що вимагає суворіших правил CORS, зокрема явного (не шаблонного) дозволеного походження.

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

Пояснення кореневої причини

• Це не баґ у вашому коді — API повертає дані правильно, але браузер блокує його, перш ніж ваш JavaScript може його прочитати
• «Сервера на даний момент дозволяє тільки запити з нашого виробничого домену, і він не розпізнає ваш локальний URL розробника як схвалене походження.»
• «Ваш запит містить заголовок Authorization, який викликає перевірку перед польотом, і ця перевірка перед польотом є тим, що зараз не працює»

Що потрібно змінити?

• «Я додам ваш dev origin до дозволеного списку на нашій стороні — чи можете ви підтвердити точний URL і порт, з якого ви тестуєте?»
• «Ми повинні додати Access-Control-Allow-Credentials: true на сервері, оскільки ви надсилаєте куки, і походження не може бути шаблоном в цьому випадку.»
• «Я збираюся оновити API, щоб явно дозволити метод PUT і нетипові заголовки, які надсилає ваша форма, тому перевірка перед відправкою проходить»

Перевірка спільного виправлення

• «Чи можете ви перезапустити запит у вкладці Мережа і перевірити, чи виклик preflight OPTIONS тепер повертає 204 замість невдачі?»
• “Якщо я розгорну зміну заголовка, спробуйте знову з вашої гілки і дайте мені знати, чи включають фактичні заголовки відповіді наш допустимий початок.”
• Якщо після цього він все ще не працює, перевірте, чи ваш запит надсилає додатковий нетиповий заголовок, якого ми ще не дозволили

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

1. ** Назвіть шар, де відбулася помилка. ** Якщо ви скажете « це блокує переглядач, а не сервер, який відкидає це », команда з налагодження інтерфейсу негайно перенаправить зневадження з логіки API на правильний виправлення.
2. ** Запитайте точне походження, не припускайте його. ** Запитання точної схеми, домену і порту уникають другого раунду « це все ще не працює », який спричинено несумісним записом у списку дозволених.
3. ** Розрізняти помилки перевірки перед запуском від справжніх помилок відповіді. ** Пояснення того, що виклик OPTIONS і справжній запит є окремими, допомагає членам команди правильно читати вкладку Мережа, замість того, щоб дивитися лише на невдалий запит, який вони очікували побачити.

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

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

Зв’язані ресурси

• Як пояснити затримку поширення DNS англійською мовою

Переклад з англійської: Світлана Кравчук

Пояснення помилок CORS (Cross- Origin Resource Sharing) команді інтерфейсу може бути схожим на навігацію складною технічною дискусією. Це не просто заява про те, що « браузер не довіряє цьому». Ключовим є повідомлення про те, чому це відбувається, і надання чітких, реальних кроків. Часто, розробники інтерфейсу можуть бути не знайомі з основними протоколами безпеки, які регулюють веб-запити - вони просто бачать розчаруюче повідомлення про помилку і намагаються виправити його, змінюючи код JavaScript без розуміння більшої картини. Це може призвести до марного часу і, можливо, ввести нові вразливості, якщо не обробляти обережно. Щоб допомогти їм зрозуміти ситуацію, вам слід використовувати певний словниковий запас і дати пояснення таким чином, щоб це відповідало їхньому робочому процесу.

Поширеним сценарієм є отримання коментаря на запит pull: “Це виклик API не працює! Помилка CORS.” Хороша відповідь не буде просто « Виправте CORS ». Замість цього спробуйте щось на зразок: « Добре, я бачу, що ви зіткнулися з проблемою CORS з запитом на https://api.example.com/data. По суті, браузер застосовує заходи безпеки, які називаються Same-Origin Policy — він обмежує веб-сторінки від здійснення запитів на домени, які відрізняються від місця походження сторінки. Це запобігає перехопленню шкідливих веб- сайтів даних з надійних джерел. Щоб розв’язати це, нам потрібно налаштувати наш сервер backend ( api.example.com ) щоб явно дозволити запити з вашого фронтендного домену - зазвичай https://www.myfrontendapp.com. Зокрема, ми додамо заголовок Access-Control-Allow-Origin, який включає ваше походження»

Іншим підходом є повідомлення Slack під час зневадження: «Команда Frontend, я бачу помилку CORS на початковому завантаженні сторінки. Здається, переглядач блокує запит, оскільки він не розпізнає заголовки відповідей сервера. Давайте подвоїмо нашу конфігурацію Access-Control-Allow-Origin і переконаємося, що ми надсилаємо правильний заголовок Content-Type — це говорить браузеру, який тип даних очікувати. Використання фраз на кшталт «явно дозволити запити», «Політика спільного походження» або «засіб безпеки» демонструє, що ви розумієте основні поняття, навіть якщо команда інтерфейсу не розуміє. Это показывает, что вы не просто указываете пальцем на общие ошибки, но и обращаетесь к ним с технической точностью.

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