rpc

goctl rpc — RPC Code Generation

English | 中文

goctl rpc is the RPC service code generation module of the goctl scaffold. It generates a complete zRPC service from .proto files. You only need to write the proto definition and business logic — all boilerplate code is generated automatically.

Features

• protoc compatible: Fully compatible with protoc, all protoc arguments are passed through
• External proto imports: Cross-directory and cross-package proto imports with automatic transitive dependency resolution
• Multiple services: Define multiple services in a single proto file, auto-grouped by service name
• Streaming support: Server streaming, client streaming, and bidirectional streaming
• Google well-known types: Automatic recognition of google.protobuf.* types with correct Go imports
• Client generation: Auto-generated RPC client wrapper code

Prerequisites

# Install protoc plugins
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Quick Start

Method 1: Create a Service Instantly

goctl rpc new greeter

Generates a complete project structure:

greeter/
├── etc/
│   └── greeter.yaml
├── greeter/
│   ├── greeter.pb.go
│   └── greeter_grpc.pb.go
├── greeter.go
├── greeter.proto
├── greeterclient/
│   └── greeter.go
└── internal/
    ├── config/
    │   └── config.go
    ├── logic/
    │   └── pinglogic.go
    ├── server/
    │   └── greeterserver.go
    └── svc/
        └── servicecontext.go

Method 2: Generate from a Proto File

1. Generate a proto template:

goctl rpc template -o=user.proto

1. Initialize the output directory and generate service code:

mkdir -p output && cd output && go mod init example.com/demo && cd ..
goctl rpc protoc user.proto \
  --go_out=output --go-grpc_out=output --zrpc_out=output \
  --go_opt=module=example.com/demo --go-grpc_opt=module=example.com/demo \
  --module=example.com/demo -I .

Command Reference

goctl rpc protoc

Generate zRPC service code from a .proto file.

goctl rpc protoc <proto_file> [flags]

Examples:

# Basic usage
goctl rpc protoc user.proto \
  --go_out=output --go-grpc_out=output --zrpc_out=output \
  --go_opt=module=example.com/demo --go-grpc_opt=module=example.com/demo \
  --module=example.com/demo -I .

# Multiple services mode
goctl rpc protoc multi.proto \
  --go_out=output --go-grpc_out=output --zrpc_out=output \
  --go_opt=module=example.com/demo --go-grpc_opt=module=example.com/demo \
  --module=example.com/demo -I . -m

# Import external protos
goctl rpc protoc service.proto \
  --go_out=output --go-grpc_out=output --zrpc_out=output \
  --go_opt=module=example.com/demo --go-grpc_opt=module=example.com/demo \
  --module=example.com/demo -I . -I ./shared_protos

# Use Google well-known types
goctl rpc protoc service.proto \
  --go_out=output --go-grpc_out=output --zrpc_out=output \
  --go_opt=module=example.com/demo --go-grpc_opt=module=example.com/demo \
  --module=example.com/demo -I .

Flags:

goctl rpc new

Quickly create a complete RPC service project.

goctl rpc new <service_name> [flags]

Flags:

goctl rpc template

Generate a proto file template.

goctl rpc template -o=<output_file> [flags]

Flags:

Feature Details

Multiple Services Mode (--multiple)

When a proto file contains multiple service definitions, the --multiple flag is required.

service SearchService {
  rpc Search(SearchReq) returns (SearchReply);
}

service NotifyService {
  rpc Notify(NotifyReq) returns (NotifyReply);
}

Directory differences with --multiple:

--multiple=false (default) directory structure:

output/
├── greeterclient/
│   └── greeter.go
├── internal/
│   ├── logic/
│   │   └── sayhellologic.go
│   └── server/
│       └── greeterserver.go
└── ...

--multiple=true directory structure:

output/
├── client/
│   ├── searchservice/
│   │   └── searchservice.go
│   └── notifyservice/
│       └── notifyservice.go
├── internal/
│   ├── logic/
│   │   ├── searchservice/
│   │   │   └── searchlogic.go
│   │   └── notifyservice/
│   │       └── notifylogic.go
│   └── server/
│       ├── searchservice/
│       │   └── searchserviceserver.go
│       └── notifyservice/
│           └── notifyserviceserver.go
└── ...

External Proto Imports (--proto_path)

Use -I / --proto_path to specify additional proto search directories. Supported scenarios:

• Same-directory import: import "types.proto";
• Subdirectory import: import "common/types.proto";
• External directory import: Proto files outside the project
• Transitive imports: A imports B, B imports C — goctl resolves recursively
• Cross-package imports: Different go_package values generate correct Go imports automatically

# Search multiple directories for proto files
goctl rpc protoc service.proto \
  --go_out=output --go-grpc_out=output --zrpc_out=output \
  --go_opt=module=example.com/demo --go-grpc_opt=module=example.com/demo \
  --module=example.com/demo \
  -I . -I ./shared_protos -I /path/to/external_protos

Service Naming

By default, the service name is derived from the proto package name (e.g., package user; → service name user). This allows multiple proto files to share the same package:

protos/
├── user_base.proto      # package user;
├── user_auth.proto      # package user;
└── user_profile.proto   # package user;

All three files generate into a single user service.

To use the proto filename for naming (legacy behavior), add the --name-from-filename flag.

Streaming RPC

All three gRPC streaming patterns are supported:

service StreamService {
  rpc ServerStream(Req) returns (stream Reply);       // Server streaming
  rpc ClientStream(stream Req) returns (Reply);       // Client streaming
  rpc BidiStream(stream Req) returns (stream Reply);  // Bidirectional streaming
}

Google Well-Known Types

goctl automatically recognizes and handles Google protobuf well-known types:

These types can be used directly as RPC parameter types — goctl generates the correct imports automatically.

Examples

See the example/ directory for 10 complete examples covering all generation scenarios.