buffalo

module
v1.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 20, 2026 License: MIT

README

🦬 Buffalo - Multi-Language Protobuf/gRPC Build System

License Go Version Version

Buffalo — это мощная кросс-платформенная система сборки для protobuf/gRPC проектов с поддержкой множества языков программирования. Интеллектуальное кэширование, параллельная компиляция и инкрементальные сборки делают Buffalo идеальным выбором для современных микросервисных архитектур.

✨ Основные возможности

🚀 Поддержка множества языков
  • Python - полная поддержка protobuf и gRPC
  • Go - нативная интеграция с Go toolchain
  • Rust - современная кодогенерация с Tonic
  • C++ - оптимизированная компиляция
⚡ Производительность
  • Интеллектуальное кэширование - пересборка только измененных файлов
  • Параллельная компиляция - максимальное использование CPU
  • Инкрементальные сборки - минимальное время сборки
🎯 Гибкость
  • Система плагинов - расширение функциональности
  • Гибкая конфигурация - YAML/TOML/JSON + environment variables
  • Шаблонизация - кастомизация генерируемого кода
  • Dependency management - автоматическое управление зависимостями
🔧 Удобство
  • CLI интерфейс - интуитивная командная строка
  • Watch mode - автоматическая пересборка при изменениях
  • Метрики и статистика - отслеживание производительности
  • Docker support - контейнеризированные сборки

📦 Установка

Быстрая установка
Linux/macOS
curl -sSL https://raw.githubusercontent.com/massonsky/buffalo/main/install.sh | bash
Windows (PowerShell)
irm https://raw.githubusercontent.com/massonsky/buffalo/main/install.ps1 | iex
Проверка установки
buffalo --version
Альтернативные способы
С помощью Go
go install github.com/massonsky/buffalo/cmd/buffalo@latest
Из исходников
git clone https://github.com/massonsky/buffalo.git
cd buffalo
make install
Docker
docker pull ghcr.io/massonsky/buffalo:1.0.0
docker run --rm ghcr.io/massonsky/buffalo:1.0.0 buffalo --version

🚀 Быстрый старт

1. Инициализация проекта
# Создать новый проект Buffalo
buffalo init myproject
cd myproject

Это создаст структуру:

myproject/
├── buffalo.yaml          # Конфигурация
├── protos/              # .proto файлы
│   └── service.proto
└── generated/           # Сгенерированный код (создается автоматически)
2. Создание proto файла
// protos/service.proto
syntax = "proto3";

package myservice;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}
3. Конфигурация buffalo.yaml
version: "1.0"

project:
  name: myproject
  proto_root: protos
  output_root: generated

languages:
  python:
    enabled: true
    output: generated/python
    plugins:
      - grpc
  
  go:
    enabled: true
    output: generated/go
    module: github.com/myorg/myproject
    plugins:
      - grpc
4. Сборка
# Собрать все языки
buffalo build

# Собрать конкретный язык
buffalo build --lang python

# Watch mode - автоматическая пересборка
buffalo watch

# Параллельная сборка с 8 воркерами
buffalo build --jobs 8

📚 Примеры использования

Python проект
# buffalo.yaml
version: "1.0"

project:
  name: python-service
  proto_root: protos
  output_root: generated

languages:
  python:
    enabled: true
    output: generated/python
    plugins:
      - grpc
      - mypy
    options:
      mypy_enabled: true

buffalo build --lang python
cd generated/python
python -m pip install -e .
Go проект
# buffalo.yaml
version: "1.0"

project:
  name: go-service
  proto_root: protos
  output_root: generated

languages:
  go:
    enabled: true
    output: generated/go
    module: github.com/myorg/go-service
    plugins:
      - grpc
      - grpc-gateway
      - validate

buffalo build --lang go
cd generated/go
go mod tidy
go build ./...
Мультиязычный проект
# buffalo.yaml
version: "1.0"

project:
  name: polyglot-service
  proto_root: protos
  output_root: generated

languages:
  python:
    enabled: true
    output: generated/python
  
  go:
    enabled: true
    output: generated/go
    module: github.com/myorg/polyglot
  
  rust:
    enabled: true
    output: generated/rust
    crate: polyglot_service
  
  cpp:
    enabled: true
    output: generated/cpp

# Собрать все языки параллельно
buffalo build --jobs 4

# Использовать watch mode для всех языков
buffalo watch

🔧 Основные команды

Сборка и компиляция
buffalo build                    # Собрать все включенные языки
buffalo build --lang python      # Собрать только Python
buffalo build --jobs 8           # Использовать 8 воркеров
buffalo build --no-cache         # Пересобрать все без кэша
buffalo rebuild                  # Полная пересборка (очистка + сборка)
Разработка
buffalo watch                    # Автоматическая пересборка при изменениях
buffalo watch --lang go          # Watch для конкретного языка
buffalo check                    # Проверка готовности проекта к сборке
buffalo check -v                 # Детальная проверка с выводом всех компонентов
buffalo validate                 # Валидация proto файлов
buffalo doctor                   # Диагностика окружения (все языки)
buffalo doctor --config-only     # Проверка только включенных языков
Управление проектом
buffalo init myproject           # Создать новый проект
buffalo deps install             # Установить зависимости
buffalo deps update              # Обновить зависимости
buffalo list                     # Показать доступные языки и плагины
Кэш и очистка
buffalo clear cache              # Очистить кэш
buffalo clear generated          # Удалить сгенерированные файлы
buffalo clear all                # Очистить всё
Метрики и диагностика
buffalo metrics                  # Показать метрики сборки
buffalo stats                    # Статистика проекта
buffalo doctor                   # Диагностика окружения
buffalo diff                     # Показать изменения proto файлов
Плагины и шаблоны
buffalo plugin list              # Список доступных плагинов
buffalo plugin install <name>    # Установить плагин
buffalo template list            # Список шаблонов
buffalo template generate        # Генерация из шаблона

⚙️ Конфигурация

buffalo.yaml структура
version: "1.0"

# Настройки проекта
project:
  name: myproject              # Имя проекта
  proto_root: protos           # Корневая папка .proto файлов
  output_root: generated       # Корневая папка для генерации
  
# Настройки сборки
build:
  parallel: true               # Параллельная компиляция
  jobs: 4                      # Количество воркеров
  incremental: true            # Инкрементальные сборки
  cache_enabled: true          # Использовать кэш
  
# Языки программирования
languages:
  python:
    enabled: true
    output: generated/python
    version: "3.8+"
    plugins:
      - grpc
      - mypy
    options:
      mypy_enabled: true
      package_name: myservice
  
  go:
    enabled: true
    output: generated/go
    module: github.com/myorg/myproject
    version: "1.21+"
    plugins:
      - grpc
      - grpc-gateway
      - validate
    options:
      go_package_prefix: github.com/myorg/myproject
  
  rust:
    enabled: false
    output: generated/rust
    crate: myproject
    plugins:
      - tonic
  
  cpp:
    enabled: false
    output: generated/cpp
    std: "c++17"

# Зависимости
dependencies:
  - name: googleapis
    url: https://github.com/googleapis/googleapis
    version: master
    path: google/api

# Плагины
plugins:
  - name: custom-validator
    path: ./plugins/validator
    enabled: true

# Шаблоны
templates:
  enabled: true
  path: ./templates
  
# Метрики
metrics:
  enabled: true
  output: .buffalo/metrics.json
Переменные окружения
BUFFALO_CONFIG=./custom.yaml    # Путь к конфигурации
BUFFALO_VERBOSE=true            # Подробный вывод
BUFFALO_JOBS=8                  # Количество воркеров
BUFFALO_NO_CACHE=true           # Отключить кэш
BUFFALO_LOG_LEVEL=debug         # Уровень логирования

🔌 Система плагинов

Buffalo поддерживает расширяемую систему плагинов для кастомизации генерации кода.

Встроенные плагины
  • grpc - генерация gRPC кода
  • grpc-gateway - REST API gateway для gRPC (Go)
  • validate - валидация сообщений
  • mypy - типизация для Python
  • tonic - современный gRPC фреймворк для Rust
Создание собственного плагина
// plugins/custom/plugin.go
package custom

import "github.com/massonsky/buffalo/pkg/plugin"

type CustomPlugin struct {
    plugin.BasePlugin
}

func (p *CustomPlugin) Name() string {
    return "custom-plugin"
}

func (p *CustomPlugin) Execute(ctx plugin.Context) error {
    // Ваша логика плагина
    return nil
}

Подробнее: Plugin Development Guide

📊 Метрики и мониторинг

Buffalo собирает детальные метрики о процессе сборки:

# Показать метрики последней сборки
buffalo metrics

# Экспорт метрик в JSON
buffalo metrics --format json > metrics.json

# Статистика проекта
buffalo stats

Пример вывода:

📊 Build Metrics
═══════════════════════════════════════
Total files:        42
Changed files:      3
Build time:         2.34s
Cache hit rate:     92.3%
Workers used:       8
Peak memory:        156MB

📈 Performance by language:
Python:   0.89s  (38%)
Go:       1.12s  (48%)
Rust:     0.33s  (14%)

🐳 Docker интеграция

Использование официального образа
FROM ghcr.io/massonsky/buffalo:1.0.0 AS builder

WORKDIR /workspace
COPY protos ./protos
COPY buffalo.yaml .

RUN buffalo build

# Копировать сгенерированный код в ваш образ
FROM python:3.11-slim
COPY --from=builder /workspace/generated/python /app/proto
Docker Compose
version: '3.8'

services:
  buffalo-build:
    image: ghcr.io/massonsky/buffalo:1.0.0
    volumes:
      - .:/workspace
    working_dir: /workspace
    command: buffalo build

🛠️ Разработка

Требования
  • Go 1.21+
  • Make (опционально)
  • Git
Сборка из исходников
git clone https://github.com/massonsky/buffalo.git
cd buffalo

# Сборка
make build

# Тестирование
make test

# Проверка кода
make check

# Установка
make install
Запуск тестов
make test              # Все тесты
make test-unit         # Unit тесты
make test-integration  # Integration тесты
make coverage          # С покрытием кода

Подробнее: Development Guide

🤝 Участие в разработке

Мы приветствуем вклад сообщества! Вот как вы можете помочь:

  1. 🐛 Сообщайте о багах через GitHub Issues
  2. 💡 Предлагайте новые функции в Discussions
  3. 🔧 Отправляйте Pull Requests
  4. 📖 Улучшайте документацию
  5. ⭐ Ставьте звезды проекту на GitHub

Перед началом работы прочитайте Contributing Guide.

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

🎯 Use Cases

Микросервисная архитектура

Buffalo идеален для проектов с множеством микросервисов на разных языках:

  • Централизованное управление proto-контрактами
  • Консистентная генерация кода для всех сервисов
  • Быстрые итерации благодаря инкрементальным сборкам
CI/CD пайплайны

Интеграция с популярными CI/CD системами:

# .github/workflows/build.yml
name: Build Proto
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Buffalo
        run: curl -sSL https://raw.githubusercontent.com/massonsky/buffalo/main/install.sh | bash
      - name: Build
        run: buffalo build
      - name: Upload artifacts
        uses: actions/upload-artifact@v3
        with:
          name: generated-code
          path: generated/
Монорепозитории

Buffalo отлично работает с монорепо:

  • Одна конфигурация для всего репозитория
  • Параллельная сборка независимых модулей
  • Эффективное кэширование

🔍 Сравнение с альтернативами

Функция Buffalo Buf Prototool Ручная сборка
Мультиязычность ✅ Python, Go, Rust, C++ ✅ Множество ⚠️ Ограничено ✅ Любой
Интеллектуальное кэширование ✅ ⚠️ Базовое ❌ ❌
Параллельная компиляция ✅ ✅ ⚠️ ❌
Система плагинов ✅ ✅ ⚠️ ⚠️
Watch mode ✅ ❌ ✅ ❌
Dependency management ✅ ✅ ❌ ❌
Шаблонизация ✅ ⚠️ ❌ ✅
Метрики ✅ ❌ ❌ ❌
Простота настройки ✅ ✅ ✅ ❌

📈 Производительность

Buffalo оптимизирован для максимальной производительности:

Бенчмарки (проект с 100 proto файлов)
Полная сборка (без кэша):
Buffalo:        12.3s
Buf:            18.7s
Manual (make):  34.2s

Инкрементальная сборка (5% изменений):
Buffalo:        0.9s  (93% faster)
Buf:            4.2s  (77% faster)
Manual (make):  34.2s (no cache)

Параллельная сборка (4 языка):
Buffalo:        15.4s (4 workers)
Sequential:     58.6s
Speedup:        3.8x

🐛 Известные проблемы

Актуальный список проблем: GitHub Issues

Обходные пути
Проблема с Windows path
# Используйте forward slashes в путях
project:
  proto_root: protos  # ✅
  # proto_root: protos\api  # ❌
Медленная первая сборка

Первая сборка может быть медленной из-за загрузки зависимостей. Последующие сборки будут быстрыми.

🗺️ Roadmap

v1.1.0 (Q2 2026)
  • Поддержка TypeScript
  • Улучшенная система шаблонов
  • Remote caching
  • Web UI для управления проектами
v1.2.0 (Q3 2026)
  • Поддержка Swift и Kotlin
  • Distributed builds
  • Advanced metrics и dashboards
  • AI-powered code optimization
v2.0.0 (Q4 2026)
  • Cloud-native build service
  • Integration с популярными IDE
  • Advanced dependency resolution
  • Built-in proto registry

Полный roadmap: GitHub Projects

📄 Лицензия

Buffalo распространяется под лицензией MIT License.

🙏 Благодарности

Buffalo создан с использованием отличных open-source проектов:

💬 Поддержка и сообщество

📊 Статистика проекта

GitHub stars GitHub forks GitHub watchers

Website • Documentation • Examples • Changelog

Made with ❤️ by the Buffalo Team

Directories

Path Synopsis
cmd
buffalo command
internal
builder
cli
compiler
Package compiler defines the common interface for language-specific compilers.
 Package compiler defines the common interface for language-specific compilers.
compiler/cpp
compiler/golang
compiler/python
Package python implements the Python protobuf compiler.
 Package python implements the Python protobuf compiler.
compiler/rust
config
Package config provides configuration management for Buffalo.
 Package config provides configuration management for Buffalo.
dependency
Package dependency provides dependency management for proto files.
 Package dependency provides dependency management for proto files.
metrics
plugin
Package plugin provides a flexible plugin system for extending Buffalo functionality.
 Package plugin provides a flexible plugin system for extending Buffalo functionality.
plugin/examples
Package examples provides example plugins for Buffalo This demonstrates how to create a simple validator plugin
 Package examples provides example plugins for Buffalo This demonstrates how to create a simple validator plugin
system
template
version
Package version provides version information for Buffalo.
 Package version provides version information for Buffalo.
versioning
pkg
errors
Package errors provides enhanced error handling with codes, stack traces, and context.
 Package errors provides enhanced error handling with codes, stack traces, and context.
logger
Package logger provides a flexible, structured logging system for Buffalo.
 Package logger provides a flexible, structured logging system for Buffalo.
metrics
utils

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.