92 lines
4.0 KiB
Markdown
92 lines
4.0 KiB
Markdown
# BotPages Framework
|
||
|
||
BotPages — это архитектурный фреймворк для построения Telegram/MAX‑ботов с чистыми слоями, расширяемыми API и удобным developer experience.
|
||
|
||
## ✨ Возможности
|
||
- **Навигация через страницы**: каждая страница — отдельный обработчик логики.
|
||
- **Единый метод GoToAsync**: автоматически поддерживает как `SingletonPage`, так и `StatefulPage`.
|
||
- **StatefulPage**: свойства автоматически сохраняются в `StateStorage`.
|
||
- **SingletonPage**: один экземпляр на всё приложение, без состояния.
|
||
- **Middleware**: подключение промежуточных обработчиков (логирование, обработка ошибок).
|
||
- **Автоматическая регистрация страниц**: через рефлексию.
|
||
- **Роутинг страниц**: возможность устанавливать пути вызова для страниц.
|
||
- **Команды**: возможность установки команд, которые работают приоритетнее обработчиков страниц.
|
||
- **Минимум boilerplate**: декларативные интерфейсы и fluent API.
|
||
|
||
## 🚀 Быстрый старт
|
||
```csharp
|
||
var app = new BotPagesApp(factory, state, logger)
|
||
.UseDefaultPage<WelcomePage>()
|
||
.MapCommand<WelcomePage>("/start")
|
||
.AddMiddleware(new LoggingMiddleware(logger))
|
||
.AddMiddleware(new ErrorHandlingMiddleware(logger));
|
||
```
|
||
|
||
## 📄 Пример страниц
|
||
|
||
### StatefulPage
|
||
```csharp
|
||
public sealed class WelcomePage : StatefulPage
|
||
{
|
||
[Statefull("visitCount")]
|
||
private int VisitCount;
|
||
|
||
private PageContext? Context { get; set; }
|
||
|
||
public override async Task OnEnter(PageContext ctx, CancellationToken ct)
|
||
{
|
||
Context = ctx;
|
||
|
||
LoadState();
|
||
VisitCount++;
|
||
SaveState();
|
||
|
||
await ctx.SendTextAsync($"Добро пожаловать 🚀. Вы заходили сюда {VisitCount} раз(а).", ct: ct);
|
||
}
|
||
}
|
||
```
|
||
|
||
### SingletonPage
|
||
```csharp
|
||
public sealed class HelpPage : SingletonPage
|
||
{
|
||
public override Task OnEnter(PageContext ctx, CancellationToken ct)
|
||
=> ctx.SendTextAsync("Это справка 📖", ct: ct);
|
||
}
|
||
```
|
||
|
||
## 🧩 Навигация
|
||
```csharp
|
||
await ctx.Navigation.GoToAsync<WelcomePage>(ctx, ct); // Stateful
|
||
await ctx.Navigation.GoToAsync<WelcomePage>(ctx, agrs, ct); // Stateful with arguments
|
||
await ctx.Navigation.GoToAsync<HelpPage>(ctx, ct); // Singleton
|
||
await ctx.Navigation.GoToHome(ctx, ct); // Stateful
|
||
```
|
||
|
||
## ⚙️ Middleware
|
||
```csharp
|
||
public sealed class LoggingMiddleware : IPageMiddleware
|
||
{
|
||
private readonly ILogger _logger;
|
||
public LoggingMiddleware(ILogger logger) => _logger = logger;
|
||
|
||
public async Task InvokeAsync(PageContext ctx, Func<Task> next, CancellationToken ct)
|
||
{
|
||
_logger.Log(LogLevel.Info, $"Update: {ctx.Update.Kind}");
|
||
await next();
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🏗 Архитектурные принципы
|
||
- **Separation of concerns**: страницы не знают о транспорте, всё через адаптеры.
|
||
- **Расширяемость**: новые страницы и middleware подключаются декларативно.
|
||
- **Прозрачность**: минимум скрытой логики, всё явно через контекст.
|
||
- **Developer Experience**: удобные API, автоматическая регистрация, документация через `///summary`.
|
||
|
||
## 📌 Итог
|
||
BotPages позволяет писать чистые, расширяемые и удобные для команды боты:
|
||
- минимум boilerplate,
|
||
- декларативные интерфейсы,
|
||
- прозрачная навигация,
|
||
- автоматическое управление состоянием. |