Перейти к основному содержимому

Документация Tonica Framework

Добро пожаловать в документацию фреймворка Tonica! Tonica — это современный Go-фреймворк с proto-first подходом для создания production-ready микросервисов с gRPC, REST API, воркерами и message consumers.

Оглавление​

Основная документация​

  1. Начало работы - Быстрая настройка и первое приложение на Tonica
  2. Справочник CLI - Инструменты командной строки и генерация кода
  3. Обзор архитектуры - Как работает Tonica
  4. Режимы запуска - AIO, Service, Worker, Consumer и Gateway режимы
  5. Конфигурация - Все параметры конфигурации и переменные окружения
  6. Пользовательские роуты - Добавление кастомных HTTP маршрутов с OpenAPI документацией
  7. Руководство по тестированию - Как тестировать Tonica приложения
  8. Лучшие практики - Паттерны, антипаттерны и рекомендации

Дополнительные ресурсы​

Быстрые ссылки​

Для новых пользователей​

Начните с Начала работы, чтобы создать первое приложение за 5 минут.

Для опытных пользователей​

Что такое Tonica?​

Tonica — это комплексный Go-фреймворк, который предоставляет:

  • Proto-First дизайн: Определяйте API с помощью Protocol Buffers
  • Автогенерация OpenAPI: Swagger спецификации генерируются из proto аннотаций
  • Множество режимов запуска: Запускайте как единый сервис (AIO), standalone сервис, воркер или consumer
  • Встроенная наблюдаемость: OpenTelemetry трейсинг, Prometheus метрики, структурированное логирование
  • Graceful Shutdown: Правильное управление жизненным циклом всех компонентов
  • Поддержка БД: PostgreSQL, MySQL, SQLite с Bun ORM
  • Поддержка Redis: Connection pooling и кэширование
  • Интеграция Temporal: Встроенная поддержка Temporal воркеров
  • Message Consumers: Поддержка Kafka/PubSub consumers
  • UI для API документации: Встроенный Scalar UI для интерактивного изучения API

Ключевые возможности​

🚀 Proto-First разработка​

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse) {
    option (google.api.http) = {
      get: "/api/v1/users/{id}"
    };
  }
}

🎯 Гибкие режимы запуска​

import (
    "github.com/tonica-go/tonica/pkg/tonica"
    "github.com/tonica-go/tonica/pkg/tonica/config"
)

// All-in-one mode: gRPC + REST + Workers + Consumers
app := tonica.NewApp(
    tonica.WithConfig(
        config.NewConfig(
            config.WithRunMode(config.ModeAIO),
        ),
    ),
)
err := app.Run()

// Service only: gRPC + REST
app := tonica.NewApp(
    tonica.WithConfig(
        config.NewConfig(
            config.WithRunMode(config.ModeService),
        ),
    ),
)
err := app.Run()

// Workers only: Temporal workers
app := tonica.NewApp(
    tonica.WithConfig(
        config.NewConfig(
            config.WithRunMode(config.ModeWorker),
        ),
    ),
)
err := app.Run()

// Consumers only: Message consumers
app := tonica.NewApp(
    tonica.WithConfig(
        config.NewConfig(
            config.WithRunMode(config.ModeConsumer),
        ),
    ),
)
err := app.Run()

🔌 Пользовательские маршруты​

tonica.NewRoute(app).
    GET("/health").
    Summary("Health check endpoint").
    Tags("Monitoring").
    Response(200, "Healthy", tonica.InlineObjectSchema(map[string]string{
        "status": "string",
    })).
    Handle(func(c *gin.Context) {
        c.JSON(200, gin.H{"status": "healthy"})
    })

📊 Встроенная наблюдаемость​

import "log/slog"

// Metrics
app.GetMetricManager().NewCounter("requests_total", "Total requests")

// Tracing (automatic)
// Logging (structured with slog)
app.GetLogger().Info("Processing request", "user_id", userID)
// GetLogger() returns *slog.Logger

Архитектура​

Tonica следует модульной архитектуре:

Сообщество и поддержка​

Лицензия​

[Ваша лицензия здесь]

Вклад в проект​

Мы приветствуем вклад в проект! Пожалуйста, посетите наш GitHub репозиторий для ознакомления с руководством по внесению вклада.