feat(goctl/rpc): support external proto imports with cross-package ty… (#5472)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tools/goctl/rpc/example/05-multiple-services/README-cn.md

@@ -0,0 +1,80 @@
+# 示例 05：多服务模式（`--multiple`）
+
+本示例演示从一个 proto 文件生成多个 RPC 服务。
+
+## Proto 定义
+
+两个 proto 文件共享相同的 `go_package`：
+
+```protobuf
+option go_package = "example.com/demo/pb";
+```
+
+- `shared.proto` — 定义共享消息类型（`Meta`）。
+- `multi.proto` — 定义了**两个**服务：`SearchService` 和 `NotifyService`。
+
+当 proto 文件包含多个 `service` 块时，必须使用 `-m`（或 `--multiple`）标志。
+
+## 生成命令
+
+首先，在输出目录中初始化 `go.mod`：
+
+```bash
+mkdir -p output && cd output && go mod init example.com/demo && cd ..
+```
+
+然后使用 `-m` 标志生成代码：
+
+```bash
+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
+```
+
+生成的目录结构：
+
+```
+output/
+├── client
+│   ├── notifyservice
+│   │   └── notifyservice.go
+│   └── searchservice
+│       └── searchservice.go
+├── etc
+│   └── multisvc.yaml
+├── go.mod
+├── internal
+│   ├── config
+│   │   └── config.go
+│   ├── logic
+│   │   ├── notifyservice
+│   │   │   └── notifylogic.go
+│   │   └── searchservice
+│   │       └── searchlogic.go
+│   ├── server
+│   │   ├── notifyservice
+│   │   │   └── notifyserviceserver.go
+│   │   └── searchservice
+│   │       └── searchserviceserver.go
+│   └── svc
+│       └── servicecontext.go
+├── multisvc.go
+└── pb
+    ├── multi.pb.go
+    ├── multi_grpc.pb.go
+    └── shared.pb.go
+```
+
+## 要点说明
+
+- `-m`（或 `--multiple`）标志启用多服务模式。
+- 多服务模式下，`client/` 包含按服务名分组的子目录；`logic/` 和 `server/` 也按服务名分组。
+- 两个服务共享一个入口文件（`multisvc.go`）和配置。
+- 不使用 `--multiple` 时，goctl 只允许每个 proto 文件有一个 `service` 块。
+- 所有服务共享同一个 `config.go` 和 `servicecontext.go`。

tools/goctl/rpc/example/05-multiple-services/README.md

@@ -0,0 +1,80 @@
+# Example 05: Multiple Services (`--multiple`)
+
+This example demonstrates generating multiple RPC services from a single proto file.
+
+## Proto Definition
+
+Two proto files share the same `go_package`:
+
+```protobuf
+option go_package = "example.com/demo/pb";
+```
+
+- `shared.proto` — Defines shared message types (`Meta`).
+- `multi.proto` — Defines **two** services: `SearchService` and `NotifyService`.
+
+The `-m` (or `--multiple`) flag is required when a proto file contains more than one `service` block.
+
+## Generation Commands
+
+First, initialize the output directory with a `go.mod`:
+
+```bash
+mkdir -p output && cd output && go mod init example.com/demo && cd ..
+```
+
+Then generate the code with the `-m` flag:
+
+```bash
+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
+```
+
+Generated directory structure:
+
+```
+output/
+├── client
+│   ├── notifyservice
+│   │   └── notifyservice.go
+│   └── searchservice
+│       └── searchservice.go
+├── etc
+│   └── multisvc.yaml
+├── go.mod
+├── internal
+│   ├── config
+│   │   └── config.go
+│   ├── logic
+│   │   ├── notifyservice
+│   │   │   └── notifylogic.go
+│   │   └── searchservice
+│   │       └── searchlogic.go
+│   ├── server
+│   │   ├── notifyservice
+│   │   │   └── notifyserviceserver.go
+│   │   └── searchservice
+│   │       └── searchserviceserver.go
+│   └── svc
+│       └── servicecontext.go
+├── multisvc.go
+└── pb
+    ├── multi.pb.go
+    ├── multi_grpc.pb.go
+    └── shared.pb.go
+```
+
+## Key Points
+
+- The `-m` (or `--multiple`) flag enables multiple-service mode.
+- In multiple mode, `client/` contains per-service subdirectories; `logic/` and `server/` are also grouped by service name.
+- Both services share a single entry point (`multisvc.go`) and config.
+- Without `--multiple`, goctl only allows one `service` block per proto file.
+- All services share the same `config.go` and `servicecontext.go`.

tools/goctl/rpc/example/05-multiple-services/multi.proto

@@ -0,0 +1,33 @@
+syntax = "proto3";
+
+package multisvc;
+
+option go_package = "example.com/demo/pb";
+
+import "shared.proto";
+
+message SearchReq {
+  shared.Meta meta    = 1;
+  string      keyword = 2;
+}
+
+message SearchReply {
+  repeated string items = 1;
+}
+
+message NotifyReq {
+  shared.Meta meta    = 1;
+  string      message = 2;
+}
+
+message NotifyReply {
+  bool ok = 1;
+}
+
+service SearchService {
+  rpc Search(SearchReq) returns (SearchReply);
+}
+
+service NotifyService {
+  rpc Notify(NotifyReq) returns (NotifyReply);
+}

tools/goctl/rpc/example/05-multiple-services/shared.proto

@@ -0,0 +1,10 @@
+syntax = "proto3";
+
+package shared;
+
+option go_package = "example.com/demo/pb";
+
+message Meta {
+  string trace_id = 1;
+  string version  = 2;
+}