Wiki
猫Table of Contents
- DRAFT: план миграции Laniakea v2
- Уже принятые решения
- Подготовка совместимости в v1.2.0
- Предлагаемые breaking changes
- 1. Явно представить optional-участника опроса
- 2. Сделать cancellation обязательной частью runner
- 3. Не позволять по умолчанию создать невалидную клавиатуру
- 4. Использовать строгие и ограниченные defaults
- 5. Удалить deprecated compatibility names
- Ожидаемая работа при миграции
- Открытые решения дизайна
- Критерии готовности релиза
- Связанные страницы
DRAFT: план миграции Laniakea v2
English version: V2-Migration-Plan
Статус: DRAFT. Эта страница описывает возможное направление v2, а не реализованный или утверждённый публичный API. Имена, сигнатуры, значения по умолчанию и состав релиза могут измениться.
Laniakea v1.2.0 сохраняет публичный API v1 и одновременно добавляет совместимые мосты к более строгому, context-aware и ограниченному поведению. Будущая v2 сможет использовать эти мосты, чтобы убрать неоднозначные контракты и устаревшие aliases через в основном механическую миграцию, не смешивая breaking cleanup с minor-релизом.
Уже принятые решения
v1.2.0должна сохранять source compatibility с v1 везде, где существующая возможность работает.- Перечисленные здесь breaking changes откладываются до новой major-версии.
- В новом коде на v1.2 стоит предпочитать показанные ниже compatibility API, чтобы сократить будущую миграцию.
- Совместимость с Telegram на уровне wire format намеренно не ломается; исправленные JSON-имена полей уже входят в v1.2 как bug fix.
- Этот черновик не назначает дату выхода v2 и не гарантирует реализацию каждого предложения.
Подготовка совместимости в v1.2.0
| Область | Предпочтительный API v1.2 | Что сохраняется для совместимости в v1.2 |
|---|---|---|
| Участники опроса | PollAnswer.VoterUser() и VoterChatInfo() |
User и VoterChat остаются value-полями |
| Runners | NewContextRunner(...) |
RunnerFn и NewRunner(...) остаются доступны |
| Callback payloads | CallbackData.EncodeValidated(...) |
Encode(...) сохраняет сигнатуру без error |
| Построение клавиатур | Build()/Validate() кнопки и GetValidated()/Validate() клавиатуры |
Существующие fluent builders и Get() остаются доступны |
| Rich messages | UnmarshalRichMessageStrict(...) для недоверенного ввода |
UnmarshalRichMessage(...) остаётся permissive для пустого root |
| Загрузка файлов | GetFileByLinkLimit(...) или OpenFileByLink(...) |
Неограниченный GetFileByLink(...) остаётся доступен |
| Очистка реакций | DeleteAllMessageReactionsWithContext(...) |
Singular alias с опечаткой остаётся deprecated |
| Поля Telegram | Существующие Go-поля с исправленными wire keys | Имена полей на уровне исходного кода не меняются |
Переход на предпочтительный столбец уже в v1.2 должен сделать большинство изменений v2 видимыми при компиляции и простыми в применении.
Предлагаемые breaking changes
1. Явно представить optional-участника опроса
Изменить PollAnswer.User и PollAnswer.VoterChat с value-полей на pointers. Telegram присылает ровно один вариант участника, а pointers выражают отсутствие без проверки нулевого ID.
Направление миграции:
// совместимая подготовка на v1.2
user, ok := answer.VoterUser()
if ok {
use(user)
}
// возможная форма v2
if answer.User != nil {
use(answer.User)
}
2. Сделать cancellation обязательной частью runner
Включить context.Context в основной контракт callback для runner. Длительные и I/O-задачи должны останавливаться при завершении polling- или webhook-runtime.
Только иллюстрация API:
runner := laniakea.NewRunner("sync", func(ctx context.Context, bot *laniakea.Bot[*App]) error {
return app.Sync(ctx)
})
Финальные имена могут сохранить NewContextRunner: черновик фиксирует context-aware поведение, но не конкретное имя конструктора.
3. Не позволять по умолчанию создать невалидную клавиатуру
Перенести проверку длины callback data, типа payload и размера строки в обычный путь построения. Fluent-методы без error могут быть заменены или дополнены builder-ом, возвращающим ошибку. Неограниченные строки должны включаться явной опцией вместо перегрузки maxRow <= 0.
Точная форма builder-а ещё не выбрана. Текущим мостом для миграции служат методы v1.2 Build, Validate, EncodeValidated и GetValidated.
4. Использовать строгие и ограниченные defaults
- Сделать так, чтобы
UnmarshalRichMessage(...)по умолчанию отклонялnull,{}, а также отсутствующий или nullblocks. - Сохранять неизвестные rich block objects без потерь вместо сведения к известной текстовой обёртке.
- Удалить или заменить неограниченный
GetFileByLink(...); предпочесть обязательный лимит байт или streaming body.
Эти изменения делают недоверенный ввод и удалённые загрузки безопаснее, но точные типы ошибок и fallback ещё не выбраны.
5. Удалить deprecated compatibility names
- Удалить
DeleteAllMessageReactionWithContext(...)в пользуDeleteAllMessageReactionsWithContext(...). - Рассмотреть следующие переименования экспортированных полей:
ChatFullInfo.AvailableReaction→AvailableReactions;ReplyParameters.QuoteParsingMode→QuoteParseMode;InputChecklist.OtherCanAddTasks→OthersCanAddTasks;InputChecklist.OtherCanMarkTasksAsDone→OthersCanMarkTasksAsDone.
Wire keys уже исправлены в v1.2. Эти предложения затрагивают только имена в исходном Go-коде.
Ожидаемая работа при миграции
| Вызов или поле v1 | Предпочтительная подготовка сейчас | Возможная миграция на v2 |
|---|---|---|
answer.User.ID != 0 |
answer.VoterUser() |
nil-check answer.User |
NewRunner(name, func(*Bot) error) |
NewContextRunner(name, func(context.Context, *Bot) error) |
перейти на основной context-aware конструктор |
keyboard.Get() |
keyboard.GetValidated() |
обрабатывать ошибку из основного пути построения |
data.Encode(kind) |
data.EncodeValidated(kind) |
обрабатывать возвращаемую ошибку валидации |
UnmarshalRichMessage(data) для внешних данных |
UnmarshalRichMessageStrict(data) |
strict-поведение становится default |
GetFileByLink(link) |
GetFileByLinkLimit(link, max) или OpenFileByLink(link) |
использовать только bounded- или streaming-загрузку |
| Singular alias для реакций | Plural-метод | дополнительных изменений не потребуется |
Открытые решения дизайна
- Какой публичный тип должен сохранять неизвестные rich objects для lossless round trip?
- Должна ли buffered-загрузка требовать лимит от caller, иметь документированный default или быть удалена в пользу streaming?
- Нужно ли сохранять какие-либо deprecated aliases ещё на один major-цикл?
- Должна ли валидация клавиатур использовать immutable builders, mutation с
errorили финальный шаг валидации? - Нужны ли временные accessors для переименованных полей в prerelease-версиях v2?
- Какие предложения должны войти в первый релиз v2, а какие можно перенести в последующий minor v2?
Критерии готовности релиза
До первого стабильного релиза v2 нужно:
- Зафиксировать предлагаемый публичный API и опубликовать парные English/Russian инструкции по миграции.
- Сгенерировать и проверить полный diff публичного API относительно последнего релиза v1.
- Добавить compile-focused примеры миграции и regression tests для каждого удаляемого compatibility path.
- Проверить Telegram JSON fixtures и lossless round trip неизвестных rich objects.
- Определить лимиты загрузки и правила владения streaming response bodies.
- Решить или явно отложить каждый открытый вопрос этой страницы.
- Согласованно отметить завершённые framework backlog items в
Framework-BacklogиCHANGELOG.mdосновного репозитория.
Связанные страницы
Navigation
Start here
Runtime and Architecture
- Bot-Lifecycle
- Webhook-Runtime
- Middleware
- Runners
- Error-Handling
- Logging
- Update-Routing-Model
- Policies
- Scenes
Interaction and Telegram API
- Inline-Keyboards-and-Payloads
- Auto-Generated-Commands
- Drafts
- Rich-Messages
- Localization
- Rate-Limiting
- tgapi-Overview