Где хранятся протофайлы?

Хранение файлов протоколов (proto files) в Go проектах

Файлы .proto — это исходные файлы для Protocol Buffers (Protobuf) — системы сериализации данных от Google. Они определяют структуру сообщений и сервисов. В Go проектах эти файлы хранятся в специально организованных директориях, чтобы обеспечить четкую структуру проекта и удобную генерацию кода.

Основные места размещения протофайлов

1. Внутри проекта в отдельной директории Самый распространенный подход — создание директории proto, api или pb в корне проекта или рядом с кодом, который будет использовать эти определения.

   myproject/
   ├── proto/           # Основная директория для .proto файлов
   │   ├── user.proto
   │   ├── product.proto
   │   └── service.proto
   ├── internal/        # Внутренние пакеты Go
   ├── cmd/             # Команды приложения
   └── go.mod
   

   Это позволяет хранить протофайлы рядом с исходным кодом и легко ссылаться на них в командах генерации.

2. В отдельном репозитории (API репозиторий) В крупных проектах или микросервисных архитектурах протофайлы часто хранятся в отдельном Git репозитории, который служит контрактом API между различными сервисами или клиентами.

   company-api-repo/
   ├── v1/
   │   ├── user.proto
   │   └── product.proto
   ├── v2/
   │   └── user.proto   # Новая версия API
   └── README.md
   

   Такой подход обеспечивает:

   • Централизованное управление API — все сервисы используют единые определения.
   • Версионирование — четкое разделение версий API (v1, v2).
   • Независимость от языка — протофайлы могут использоваться сервисами на Go, Java, Python и др.

Организация внутри директории proto

Внутри директории с протофайлами принято соблюдать определенную структуру:

proto/
├── user/                    # Пакет для сообщений User
│   ├── user.proto          # Основные сообщения User
│   └── user_service.proto  # Сервисы для работы с User
├── product/                # Пакет Product
│   └── product.proto
├── common/                 # Общие сообщения, используемые несколькими пакетами
│   ├── timestamp.proto
│   └── error.proto
└── api/                    # Основные API определения
    └── v1/
        └── service.proto   # Главный сервис API v1

Как генерируется Go код из протофайлов

После размещения протофайлов, из них генерируется Go код с помощью компилятора protoc и Go плагинов (protoc-gen-go, protoc-gen-go-grpc).

Пример команды генерации:

protoc --proto_path=./proto \
       --go_out=./internal/pb \
       --go-grpc_out=./internal/pb \
       ./proto/user/user.proto \
       ./proto/api/v1/service.proto

Объяснение ключевых параметров:

• --proto_path — указывает, где искать импортируемые .proto файлы (обычно корневая директория proto).
• --go_out — директория, в которую будет сгенерирован Go код для сообщений.
• --go-grpc_out — директория для генерации gRPC клиента и сервера (если в proto файле определены сервисы).

Практический пример структуры проекта

Рассмотрим проект с gRPC сервисом:

mygrpcservice/
├── proto/
│   ├── user/
│   │   ├── user.proto
│   │   └── user_service.proto
│   └── api/
│       └── v1/
│           └── service.proto
├── internal/
│   ├── pb/                 # Сгенерированный код из proto
│   │   ├── user/          # Соответствует структуре proto/
│   │   └── api/v1/
│   ├── server/            # Реализация gRPC сервера
│   └── handler/           // обработчики запросов
├── cmd/
│   └── server/
│       └── main.go        // точка входа сервера
├── Makefile               // содержит команды для генерации protobuf
└── go.mod

Makefile для автоматизации генерации:

gen-proto:
	protoc --proto_path=./proto \
	       --go_out=./internal/pb \
	       --go-grpc_out=./internal/pb \
	       proto/user/*.proto proto/api/v1/*.proto

Важные рекомендации

• Используйте go_package в proto файлах — это позволяет указать, в какой Go пакет должен быть сгенерирован код.

  syntax = "proto3";
  
  package user;
  
  option go_package = "github.com/mycompany/myproject/internal/pb/user"; // Путь к Go пакету
  

• Учитывайте импорты между proto файлами — при импорте другого .proto файла, путь должен быть относительным от корня --proto_path.

  import "common/timestamp.proto"; // Импорт из директории common внутри proto/
  

• Следите за версионированием — изменение proto файлов может привести к нарушению контракта API. Для публичных API используйте отдельные директории v1, v2.

Итог: Файлы .proto обычно хранятся в директории proto/ внутри проекта или в отдельном репозитории API. Ключевое — обеспечить четкую структуру, удобную для генерации Go кода и поддержания контракта API между сервисами. Правильная организация протофайлов упрощает развитие проекта, особенно в микросервисных архитектурах.