Що таке SDK? Комплекти для розробки простими словами

SDK (software development kit) — це готовий інструментарій, який компанія надає розробникам, щоб вони могли користуватися її сервісом чи платформою, не створюючи все з нуля. Зазвичай він містить бібліотеку коду для конкретної мови програмування, документацію та приклади, а іноді й додаткові інструменти, наприклад для тестування. Коли ваш застосунок «використовує SDK Stripe», це означає, що ваш код викликає готові функції Stripe, а не формує кожен запит до API Stripe вручну.

Чому SDK важливі, коли ви створюєте з ШІ

Коли ви просите ШІ-конструктор додати оплату, чат зі ШІ, карти чи електронну пошту, він зазвичай встановлює SDK цього провайдера і пише кілька рядків, які його викликають. Розуміння того, що таке SDK, допоможе вам:

• Розуміти, що додається до проєкту. SDK — це залежність, тобто зовнішній код, від якого тепер залежить ваш застосунок.
• Помічати необхідні налаштування. Майже кожен SDK потребує API-ключа, а багато мають окремі «серверні» та «браузерні» версії з різними правилами щодо того, які ключі безпечно використовувати.
• Просити саме те, що потрібно. «Використовуй офіційний SDK Stripe на сервері» — чіткіша інструкція, ніж «додай Stripe».
• Читати помилки. Багато помилок у застосунках, створених з ШІ, виникають через неправильно налаштований, застарілий SDK або SDK, який використано не в тому місці.

Повсякденна аналогія

Уявіть, що ви хочете повісити полиці.

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

Місце полиці й те, що на ній стоятиме, вирішуєте ви. Набір лише позбавляє від різання деревини й вгадування розмірів шурупів — і зменшує шанс пошкодити водогін.

SDK, API, бібліотека і фреймворк

Ці терміни перетинаються, і це плутає багатьох людей:

SDK зазвичай містить бібліотеку, а ця бібліотека зазвичай викликає API. Для вебсервісів терміни «SDK» і «клієнтська бібліотека» часто вживають як синоніми.

Деякі SDK взагалі не стосуються вебсервісів. Apple і Google публікують SDK для створення застосунків для iOS і Android, які містять компілятори, симулятори та код платформи. Ідея та сама: усе, що потрібно для розробки під їхню платформу, в одному наборі.

Що SDK робить за вас

Ось одне й те саме завдання — створення клієнта в платіжному провайдері — виконане двома способами.

Без SDK ваш код має сам сформувати HTTP-запит: задати URL, додати секретний ключ у потрібний заголовок, відформатувати дані так, як очікує API, надіслати їх, перевірити код статусу, розібрати відповідь і обробити повторні спроби, якщо мережа ненадовго зникла.

З SDK це ближче до одного рядка:

const customer = await stripe.customers.create({ email: "lena@example.com" });

За цим рядком SDK бере на себе:

• Автентифікацію — правильне додавання вашого ключа до кожного запиту
• Форматування даних — перетворення ваших даних у те, що очікує API, і відповіді назад в об'єкти
• Помилки — перетворення кодів статусу на зрозумілі типи помилок, які ваш код може перехопити
• Повторні спроби — безпечне повторення запиту, якщо він не вдався через тимчасові причини (багато офіційних SDK так роблять)
• Типи — у TypeScript редактор знає, які поля існують, тож помилки видно ще до запуску коду

Практичний приклад: додавання відповідей ШІ до застосунку підтримки

Ви просите ШІ-конструктор: «Коли клієнт надсилає звернення в підтримку, згенеруй пропоновану відповідь за допомогою моделі ШІ».

1. ШІ встановлює офіційний SDK провайдера моделі як пакет у ваш проєкт (для проєктів на JavaScript — з реєстру npm).
2. Ви додаєте API-ключ провайдера як секрет проєкту. SDK зчитує його із змінної середовища на сервері.
3. ШІ пише серверний маршрут, який викликає SDK з текстом звернення та короткою інструкцією, і зберігає запропоновану відповідь у базі даних.
4. Браузер ніколи не бачить ключа; він викликає лише ваш власний серверний маршрут.

Якщо провайдер згодом змінить свій API, зазвичай він випускає нову версію SDK. Оновлення пакета — і перевірка приміток до випуску на предмет несумісних змін — часто це все, що потрібно.

Ключові терміни

Поширені хибні уявлення

• «SDK і API — це одне й те саме». API — це інтерфейс сервісу; SDK — зручний шар поверх нього. Більшість веб-API можна викликати і без SDK, просто це більше роботи.
• «Якщо SDK встановлено, інтеграцію зроблено». Вам усе ще потрібен обліковий запис у провайдера, правильні ключі та код, який обробляє збої.
• «Будь-який пакет із правильною назвою — офіційний». Зловмисники іноді публікують схожі пакети з підробленими назвами. Точну назву пакета перевіряйте в документації провайдера.
• «SDK для браузера може використовувати мій секретний ключ». Ні, ніколи. Усе, що є в коді браузера, видно відвідувачам. Секретні ключі мають бути лише в серверному коді — див. як зберігати ключі API в безпеці.
• «SDK ніколи не потрібно оновлювати». Старі версії перестають отримувати виправлення і врешті-решт припиняють працювати, коли провайдери вимикають старі версії API.

Що запитати у вашого ШІ-конструктора

• «Використовуй офіційний SDK провайдера, а не сторонню обгортку. Назви точну назву пакета і версію, яку встановив».
• «Використовуй SDK лише на сервері і зчитуй ключ із змінної середовища».
• «Які частини цього SDK працюють у браузері і які ключі вони використовують?»
• «Що відбувається, якщо виклик SDK не вдався або перевищив час очікування? Покажи користувачеві зрозуміле повідомлення і запиши помилку в журнал».
• «Перелічи кожен SDK і пакет, від яких залежить цей застосунок, і для чого кожен з них».
• «Перевір, чи є в нас застарілі SDK або відомі проблеми безпеки в них».

SDK у Mythex

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

Щоб зрозуміти рівень під SDK, прочитайте що таке API. Про дві поширені функції на основі SDK дивіться як додати оплату до застосунку і як використовувати LLM API.

Запитання