Реализация SDK для разработки мини-программ сторонними разработчиками
SDK для мини-программ — это публичный контракт вашей экосистемы. Раз выпустив в продакшен, вы берёте на себя обязательство поддерживать обратную совместимость годами. WeChat это понял болезненно в 2019-м, когда ломающее изменение в базовом компоненте <scroll-view> положило сотни тысяч мини-программ. Поэтому проектирование SDK — это в первую очередь проектирование API boundaries.
Что входит в SDK для сторонних разработчиков
SDK — не одна библиотека. Это экосистема инструментов:
- Runtime JS-библиотека — подключается внутри мини-программы, предоставляет API (геолокация, платежи, камера, сеть через bridge)
- CLI-инструмент — сборка, превью, публикация в маркетплейс
- Локальный симулятор — запуск мини-программы на десктопе без реального Super App
- TypeScript-определения — без них IDE не подскажет, и разработчики будут делать опечатки в именах методов
- Документация с интерактивными примерами
Первая ошибка команд, которые мы видим при аудите: они начинают с runtime-библиотеки и забывают про CLI и симулятор. В итоге внешние разработчики вынуждены заливать каждую версию в реальный Super App для тестирования. Onboarding превращается в nightmare, экосистема не растёт.
Проектирование runtime API
Ядро SDK — JavaScript-библиотека, которая работает внутри WebView мини-программы. Она формирует абстракцию поверх bridge-протокола контейнера.
Структура типичного вызова:
// Плохо — прямой bridge вызов
window.__miniapp_bridge__.call('camera.take', {quality: 0.8}, callback)
// Хорошо — через SDK
import { camera } from '@superapp/sdk'
const result = await camera.take({ quality: 0.8 })
SDK берёт на себя: correlation ID для асинхронных вызовов, обработку тайм-аутов, нормализацию ошибок в стандартный формат {code, message, data}, полифиллы для различий между iOS и Android реализацией bridge. Это критично: если Android возвращает координаты с 6 знаками после запятой, а iOS с 8 — без нормализации разработчики получают несовместимые результаты на разных платформах.
Версионирование API в runtime-библиотеке строим через capability detection, а не через version string:
if (sdk.supports('payment.applePay')) {
// iOS 16+, только определённые регионы
} else {
sdk.payment.card()
}
CLI: сборка и публикация
CLI — это точка входа для большинства разработчиков. Он должен работать из коробки без трёхстраничного гайда по настройке.
Типичный workflow:
superapp init my-miniapp --template=react
cd my-miniapp
superapp dev # hot-reload локальный симулятор
superapp build # production bundle с tree-shaking
superapp publish # загрузка в маркетплейс, создание review request
Под капотом сборщик — Webpack 5 или Vite с кастомными плагинами: tree-shaking нативных API (если мини-программа не использует Bluetooth — он не попадает в bundle), анализ манифеста permissions и предупреждение о незадекларированных вызовах, минификация и code splitting для ускорения cold start внутри WebView.
Размер bundle — болезненная тема. WebView внутри мини-программ не кэширует ресурсы так, как браузер. Каждый запуск — загрузка bundle. Цель: main bundle < 200 KB gzipped. Всё что тяжелее — lazy chunks через динамический import().
Локальный симулятор
Симулятор — десктопное приложение (Electron или нативное), которое эмулирует runtime-контейнер Super App на локальной машине разработчика. Он реализует тот же bridge API, что и реальный контейнер, но с devtools: инспектор bridge-вызовов, мок-данные для геолокации и камеры, network throttling, симуляция разных размеров экрана.
На практике симулятор даёт 90% coverage для разработки. Оставшиеся 10% — специфическое поведение реального WebView на конкретных устройствах. Для них поддерживаем режим remote debug: симулятор транслирует bridge-вызовы на реальное устройство через USB/ADB.
TypeScript-определения и developer experience
SDK без типов в 2024 году — антипаттерн. Разработчики используют TypeScript, и IDE-подсказки напрямую влияют на скорость разработки и количество ошибок.
Определения генерируем из единого источника правды — JSON Schema манифеста API. Это гарантирует синхронность между документацией, runtime-поведением и типами. Монорепозиторий SDK: packages/types, packages/runtime, packages/cli, packages/simulator — с общей схемой в packages/schema.
Обратная совместимость и deprecation policy
Это самая недооценённая часть. Как только SDK в продакшене с внешними разработчиками — каждое ломающее изменение требует migration guide и deprecation window минимум 6 месяцев.
Что помогает:
- Semantic versioning с чёткими правилами (patch — только баги, minor — новые API, major — breaking changes)
-
@deprecatedаннотации в TypeScript с JSDoc-описанием альтернативы - Runtime warnings при использовании deprecated API (с возможностью отключить в prod)
- Changelog с migration examples для каждой major версии
Сроки разработки полного SDK (runtime + CLI + симулятор + типы) с нуля: от 4 до 8 месяцев. Только runtime-библиотека под существующий bridge — от 6 до 12 недель.