fix: PageHead header alignment, analytics proxy, and infra improvements (#64)
🤖 Pull request created from `various-fixes` containing PageHead
breadcrumbs and navigation alignment fixes, Umami analytics proxy, and
infrastructure updates.
This commit is contained in:
deytenit authored and 
GitHub committed
1 parent
ff5a50bad8
commit
9ee672504f
110 files changed
+2649
-1760
No files matched your search
@@ -3,64 +3,64 @@ title: Начало работы
|
||||
weight: 1
|
||||
---
|
||||
|
||||
**Quetza** — это модульный фреймворк для Discord-ботов, построенный на TypeScript, который позволяет разработчикам создавать многофункциональные приложения для Discord с помощью самодостаточных, композитных модулей.
|
||||
**Quetza** — модульный фреймворк на TypeScript для Discord-ботов. Он позволяет собирать ботов из самодостаточных независимых модулей.
|
||||
|
||||
## Что такое Quetza?
|
||||
|
||||
Quetza предоставляет архитектурный фундамент, который превращает разработку функций из модификации ядра в добавление модулей. Он решает проблему жесткого дизайна ботов за счет инверсии структур зависимостей: ядро ничего не знает о модулях, однако модули имеют полный доступ к возможностям через определенные контракты.
|
||||
Quetza даёт архитектурный каркас, где разработка новой функциональности сводится к добавлению модулей, а не правке ядра. Это решает проблему жёсткой архитектуры за счёт инверсии зависимостей: ядро ничего не знает о модулях, а модули взаимодействуют с системой через типизированные контракты.
|
||||
|
||||
## Основная философия
|
||||
|
||||
### Проблема
|
||||
|
||||
Традиционные монолитные боты страдают от хрупкости. Добавление функций требует изменения логики ядра, переплетения зависимостей и управления растущими базами кода, которые трудно тестировать или изменять.
|
||||
Традиционные монолитные боты хрупки: каждая новая функция требует правок в ядре, запутывает зависимости и раздувает кодовую базу, которую со временем становится сложно тестировать и поддерживать.
|
||||
|
||||
### Решение
|
||||
|
||||
Quetza рассматривает модули как плагины.
|
||||
Quetza работает с модулями как с плагинами:
|
||||
|
||||
- **Расширение без правки ядра:** Добавляйте функции, создавая папку. Модификация кода ядра не требуется.
|
||||
- **Изоляция:** Модули работают независимо.
|
||||
- **Композиция:** Включайте или выключайте функции, просто добавляя или удаляя папки модулей.
|
||||
- **Расширение без правки ядра:** добавьте каталог с модулем, и функция подключена. Менять исходный код ядра не нужно.
|
||||
- **Изоляция:** модули выполняются независимо друг от друга.
|
||||
- **Композиция:** подключайте и отключайте возможности, добавляя или удаляя каталоги модулей.
|
||||
|
||||
## Высокоуровневая архитектура
|
||||
|
||||
Quetza состоит из трех основных уровней:
|
||||
Quetza состоит из трёх уровней:
|
||||
|
||||
1. **Базовый уровень (Foundation Layer)**: Клиент `Discord.js`, расширенный реестрами модулей (команды, события, модули). Он действует как сервис-локатор.
|
||||
2. **Модульный уровень (Module Layer)**: Самодостаточные пакеты функций. Каждый модуль предоставляет собственные команды и события через стандартизированную структуру файлов.
|
||||
3. **Сервисный уровень (Service Layer)**: Опциональные **Контроллеры**, которые управляют состоянием бизнес-логики (например, аудиоплееры, контекст разговора) на разных серверах (guilds).
|
||||
1. **Базовый уровень (Foundation Layer):** клиент `Discord.js`, расширенный реестрами команд, событий и модулей. Выступает в роли сервис-локатора.
|
||||
2. **Модульный уровень (Module Layer):** изолированные наборы функций. Модуль объявляет собственные команды и события через стандартизированную структуру файлов.
|
||||
3. **Сервисный уровень (Service Layer):** контроллеры для управления состоянием бизнес-логики (например, аудиоплеером или контекстом диалога) на разных серверах (guilds).
|
||||
|
||||
## Ключевые концепции
|
||||
|
||||
### Ментальная модель
|
||||
|
||||
Для эффективной работы с Quetza примите следующую парадигму:
|
||||
При работе с Quetza полезна следующая аналогия:
|
||||
|
||||
- **Модули — это плагины:** Независимые папки, обнаруживаемые во время выполнения.
|
||||
- **Команды — это конечные точки (Endpoints):** Обработчики без сохранения состояния, действующие подобно эндпоинтам REST API.
|
||||
- **События — это наблюдатели (Observers):** Реактивная логика, подписывающаяся на события жизненного цикла Discord.
|
||||
- **Контроллеры — это сервисы:** Менеджеры состояния, восполняющие пробел между командами без состояния и постоянным поведением.
|
||||
- **Модули — плагины:** независимые каталоги, обнаруживаемые во время запуска.
|
||||
- **Команды — эндпоинты:** обработчики без состояния, работающие аналогично конечным точкам REST API.
|
||||
- **События — наблюдатели (observers):** реактивная логика, подписанная на события жизненного цикла Discord.
|
||||
- **Контроллеры — сервисы:** менеджеры состояния, связывающие команды без состояния с долговременной логикой бота.
|
||||
|
||||
### Границы системы
|
||||
|
||||
Понимание ограничений критически важно для проектирования:
|
||||
Ограничения, которые важно учитывать при проектировании:
|
||||
|
||||
- **Отсутствие постоянства (Persistence):** Состояние в памяти теряется при перезагрузке. Для постоянного хранения требуется внешняя база данных.
|
||||
- **Отсутствие межмодульного взаимодействия:** Модули не могут напрямую вызывать друг друга, что обеспечивает слабую связанность.
|
||||
- **Отсутствие динамической загрузки:** Модули загружаются только при запуске.
|
||||
- **Нет встроенного постоянного хранилища (persistence):** состояние в памяти сбрасывается при перезапуске. Для долговременного хранения нужна внешняя база данных.
|
||||
- **Нет межмодульного взаимодействия:** модули не вызывают друг друга напрямую, что гарантирует слабую связанность.
|
||||
- **Нет динамической перезагрузки:** модули загружаются один раз при старте процесса.
|
||||
|
||||
## Архитектурные инварианты
|
||||
|
||||
Quetza жертвует гибкостью ради предсказуемости с помощью строгих соглашений:
|
||||
Quetza ставит предсказуемость выше избыточной гибкости за счёт строгих соглашений:
|
||||
|
||||
- **Обнаружение на основе соглашений:** Модули _обязаны_ следовать структуре директорий (`module.ts`, `commands/`, `events/`) для загрузки.
|
||||
- **Однофазная инициализация:** Вся загрузка происходит до установления соединения с Discord.
|
||||
- **Соблюдение интерфейсов:** Все команды и события должны экспортировать специфические интерфейсы для их регистрации.
|
||||
- **Обнаружение по соглашениям:** чтобы модуль загрузился, структура его каталога _обязана_ содержать `module.ts`, `commands/` и `events/`.
|
||||
- **Однофазная инициализация:** все модули загружаются до установки соединения с Discord.
|
||||
- **Соблюдение контрактов:** команды и события должны экспортировать типизированные интерфейсы, необходимые для регистрации.
|
||||
|
||||
---
|
||||
|
||||
**See also:**
|
||||
## См. также
|
||||
|
||||
- [Discord.js Documentation](https://discord.js.org/)
|
||||
- [TypeScript Documentation](https://www.typescriptlang.org/)
|
||||
- [Документация Discord.js](https://discord.js.org/)
|
||||
- [Документация TypeScript](https://www.typescriptlang.org/)
|
||||
Reference in new issue
Block a user