Tutorial Buf - Convert Protobuf ke Go Code dengan Mudah

Kenapa Pakai Buf untuk Protocol Buffer? 🤔

Kalau kamu pernah pakai protoc (Protocol Buffer compiler) traditional, pasti tau betapa ribet setup dan konfigurasinya. Buf CLI hadir sebagai solusi modern yang bikin hidup developer Protocol Buffer jadi lebih mudah!

🔥 Keunggulan Buf vs protoc Traditional:

All-in-One Tool - Linting, breaking change detection, dan code generation dalam satu tool
Dependency Management - Gak perlu download proto files manual
Remote Plugins - Plugin tersedia langsung dari Buf Schema Registry
Better Performance - Lebih cepat dan efficient
Modern Configuration - YAML-based config yang clean

🛠️ Setup Buf CLI

Install Buf CLI

# macOS (Homebrew)
brew install bufbuild/buf/buf

# Linux/macOS (curl)
curl -sSL "https://github.com/bufbuild/buf/releases/latest/download/buf-$(uname -s)-$(uname -m)" -o "/usr/local/bin/buf"
chmod +x /usr/local/bin/buf

# Verify installation
buf --version

Project Structure

Sebelum mulai, pastikan project structure kamu seperti ini:

your-project/
├── buf.yaml           # Workspace configuration
├── buf.gen.yaml       # Code generation configuration
├── proto/             # Proto files directory
│   ├── hello/
│   │   └── v1/
│   │       ├── hello.proto
│   │       └── service.proto
│   └── config/
└── protogen/          # Generated code output

⚙️ Konfigurasi Buf

1. buf.yaml - Workspace Configuration

File ini define workspace dan module configuration:

# buf.yaml
version: v2
modules:
  - path: proto

lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE

deps:
  - buf.build/protocolbuffers/wellknowntypes:v21.12
  - buf.build/bufbuild/protovalidate:52f32327d4b045a79293a6ad4e7e1236
  - buf.build/googleapis/googleapis:61b203b9a9164be9a834f58c37be6f62
  - buf.build/grpc-ecosystem/grpc-gateway

2. buf.gen.yaml - Code Generation Configuration

Ini yang paling penting - define plugins untuk generate Go code:

# buf.gen.yaml
version: v2

managed:
  enabled: true

plugins: 
  # Generate basic Go structs from proto messages
  - remote: buf.build/protocolbuffers/go:v1.36.10
    out: protogen
    opt: paths=source_relative

  # Generate gRPC service stubs
  - remote: buf.build/grpc/go:v1.5.1
    out: protogen
    opt: paths=source_relative

  # Generate gRPC Gateway (HTTP REST API)
  - remote: buf.build/grpc-ecosystem/gateway:v2.27.3
    out: protogen
    opt:
      - paths=source_relative
      - generate_unbound_methods=true
  
  # Generate OpenAPI/Swagger documentation
  - remote: buf.build/grpc-ecosystem/openapiv2:v2.27.3
    out: openapiv2
    opt:
      - allow_merge=true
      - merge_file_name=openapiv2

🔄 Generate Go Code dari Proto

1. Initialize Buf Workspace

# Initialize buf workspace (jika belum ada buf.yaml)
buf config init

# Install dependencies
buf dep update

2. Lint Proto Files

# Check proto files quality
buf lint

# Format proto files
buf format --write

3. Generate Go Code

# Generate semua code berdasarkan buf.gen.yaml
buf generate

# Generate dari remote proto module
buf generate buf.build/googleapis/googleapis

# Generate dengan custom template
buf generate --template buf.gen.yaml proto/

4. Hasil Generate

Setelah run buf generate, kamu akan dapat file-file ini:

protogen/
├── hello/
│   └── v1/
│       ├── hello.pb.go          # Proto message structs
│       ├── service.pb.go        # Service definitions
│       ├── service_grpc.pb.go   # gRPC client & server stubs
│       └── service.pb.gw.go     # gRPC Gateway (HTTP REST)
└── config/
    └── v1/
        └── config.pb.go

openapiv2/
├── embed.go                     # Embedded swagger files
└── openapiv2.swagger.json       # OpenAPI documentation

🧪 Contoh Proto File

hello/v1/hello.proto

syntax = "proto3";

package hello.v1;

import "google/protobuf/timestamp.proto";

option go_package = "github.com/achtarudin/grpc-sample/protogen/hello/v1;hellov1";

message HelloRequest {
  string name = 1;
}

message HelloResponse {
  string message = 1;
  google.protobuf.Timestamp created_at = 2;
}

hello/v1/service.proto

syntax = "proto3";

package hello.v1;

import "hello/v1/hello.proto";
import "google/api/annotations.proto";

service HelloService {
  // Unary RPC
  rpc SayHello(HelloRequest) returns (HelloResponse) {
    option (google.api.http) = {
      post: "/v1/hello"
      body: "*"
    };
  }

  // Server Streaming RPC
  rpc SayManyHellos(HelloRequest) returns (stream HelloResponse);

  // Client Streaming RPC
  rpc SayHelloToEveryone(stream HelloRequest) returns (HelloResponse);

  // Bidirectional Streaming RPC
  rpc SayHelloContinuous(stream HelloRequest) returns (stream HelloResponse);
}

🚀 Advanced Features

Remote Dependencies

Buf bisa langsung use proto dari Buf Schema Registry:

# buf.yaml
deps:
  - buf.build/googleapis/googleapis          # Google APIs
  - buf.build/protocolbuffers/wellknowntypes # Well-known types
  - buf.build/bufbuild/protovalidate         # Validation
  - buf.build/grpc-ecosystem/grpc-gateway    # gRPC Gateway

Breaking Change Detection

# Check breaking changes against main branch
buf breaking --against '.git#branch=main'

# Check against previous version
buf breaking --against 'https://github.com/user/repo.git#tag=v1.0.0'

Custom Templates

Buat template sendiri untuk different outputs:

# buf.gen.server.yaml (only server code)
version: v2
plugins: 
  - remote: buf.build/protocolbuffers/go:v1.36.10
    out: server/protogen
  - remote: buf.build/grpc/go:v1.5.1
    out: server/protogen

# Generate dengan custom template
buf generate --template buf.gen.server.yaml

🎯 Integration dengan Makefile

Buat Makefile untuk automasi workflow:

# Makefile
.PHONY: proto-lint proto-gen proto-clean

proto-lint:
	buf lint
	buf format --diff --exit-code

proto-gen:
	buf generate

proto-breaking:
	buf breaking --against '.git#branch=main'

proto-clean:
	rm -rf protogen/
	rm -rf openapiv2/

proto-deps:
	buf dep update

# Full workflow
proto-all: proto-lint proto-gen proto-breaking

✨ Tips & Best Practices

1. Organized Proto Structure

proto/
├── common/v1/          # Shared types
├── user/v1/            # User service
├── payment/v1/         # Payment service
└── notification/v1/    # Notification service

2. Version Management

Always use versioned packages (v1, v2, etc.)
Use semantic versioning untuk breaking changes
Keep backwards compatibility

3. CI/CD Integration

# .github/workflows/proto.yml
- name: Lint Protobuf
  run: buf lint

- name: Check Breaking Changes  
  run: buf breaking --against origin/main

- name: Generate Code
  run: buf generate

- name: Push Generated Code
  run: |
    git add protogen/
    git commit -m "chore: update generated proto code"

🔗 Resources

Buf Documentation: buf.build/docs
Buf Schema Registry: buf.build
gRPC Go Tutorial: grpc.io/docs/languages/go
Protocol Buffers Guide: protobuf.dev

Penutup 🎉

Buf CLI bikin workflow Protocol Buffer jadi jauh lebih mudah dan modern. Gak perlu lagi pusing sama setup protoc yang ribet, dependency management manual, atau generate code satu-satu.

Dengan Buf, kamu cuma perlu:

Setup buf.yaml dan buf.gen.yaml
Run buf generate
Done! ✨

Perfect untuk project gRPC modern dengan Go! 🚀

Cara Convert Protobuf ke Go Code dengan Buf — Modern Protocol Buffer Tool 🚀