Skip to main content

​
Overview

The microservices-app project uses Protocol Buffers (protobuf) for defining service contracts and message schemas. Buf is used as the build system and schema registry for managing proto definitions.

​
Directory Structure

All proto definitions are stored in the proto/ directory at the root of the repository: 
proto/
├── greeter/v1/greeter.proto
├── caller/v1/caller.proto
└── gateway/v1/gateway.proto

​
buf.yaml Configuration

The buf.yaml file at the repository root configures buf’s behavior: 
version: v2
modules:
  - path: proto
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE

​
Configuration Details

  • version: Uses buf v2 configuration format
  • modules.path: Defines proto/ as the module root containing all proto files
  • lint.use: Applies the STANDARD lint ruleset, which enforces Google’s proto style guide
  • breaking.use: Uses FILE level breaking change detection to ensure backward compatibility

​
Linting Proto Files

Buf automatically validates proto files against style and consistency rules: 
buf lint
The STANDARD lint rules enforce:
  • Proper naming conventions (PascalCase for messages, snake_case for fields)
  • Required package declarations
  • Consistent file structure
  • Comment formatting

​
Breaking Change Detection

To ensure backward compatibility, buf can detect breaking changes against a previous version: 
# Check against main branch
buf breaking --against main

# Check against a specific git ref
buf breaking --against '.git#branch=develop'
The FILE breaking change strategy detects:
  • Removed or renamed messages, fields, or services
  • Changed field types or numbers
  • Removed enum values
  • Changed service method signatures

​
Combined Lint and Breaking Check

The repository provides a convenient command to run both checks: 
buf-check
This command executes:
  1. buf lint - Validates proto style and structure
  2. buf breaking --against main - Checks for breaking changes
This command is automatically run in CI on every pull request.

​
Proto File Naming Conventions

The project follows these conventions:
  • Package names: <service>.v1 (lowercase with version)
  • File structure: proto/<service>/v1/<service>.proto
  • Go package option: Includes full import path with version suffix

​
Example Structure

For a service named greeter: 
proto/greeter/v1/greeter.proto
With package declaration: 
package greeter.v1;

option go_package = "github.com/hackz-megalo-cup/microservices-app/services/gen/go/greeter/v1;greeterv1";

​
Version Management

All services use v1 versioning in their package names and directory structure. When introducing breaking changes:
  1. Create a new version directory: proto/<service>/v2/
  2. Update package name: package <service>.v2
  3. Update go_package option to include v2
  4. Maintain both versions during migration

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us