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/04-transitive-import/README-cn.md

@@ -0,0 +1,72 @@
+# 示例 04：传递性导入
+
+本示例演示 proto 的传递性导入，即 A 导入 B，B 导入 C。
+
+## Proto 定义
+
+三个 proto 文件形成传递导入链，共享相同的 `go_package`：
+
+```protobuf
+option go_package = "example.com/demo/pb";
+```
+
+- `base.proto` — C 层：定义基础类型（`BaseResp`）。
+- `middleware.proto` — B 层：导入 `base.proto`，定义 `RequestMeta`。
+- `main.proto` — A 层：导入 `middleware.proto`，定义 `PingService`（入口文件）。
+
+导入链：`main.proto` → `middleware.proto` → `base.proto`
+
+## 生成命令
+
+首先，在输出目录中初始化 `go.mod`：
+
+```bash
+mkdir -p output && cd output && go mod init example.com/demo && cd ..
+```
+
+然后生成代码：
+
+```bash
+goctl rpc protoc main.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 .
+```
+
+生成的目录结构：
+
+```
+output/
+├── etc
+│   └── pingsvc.yaml
+├── go.mod
+├── internal
+│   ├── config
+│   │   └── config.go
+│   ├── logic
+│   │   └── pinglogic.go
+│   ├── server
+│   │   └── pingserviceserver.go
+│   └── svc
+│       └── servicecontext.go
+├── pb
+│   ├── base.pb.go
+│   ├── main.pb.go
+│   ├── main_grpc.pb.go
+│   └── middleware.pb.go
+├── pingservice
+│   └── pingservice.go
+└── pingsvc.go
+```
+
+## 要点说明
+
+- 三个 proto 文件（`base.proto` → `middleware.proto` → `main.proto`）形成传递导入链。
+- goctl 自动递归解析所有传递导入。
+- 三个文件共享相同的 `go_package = "example.com/demo/pb"`。
+- 只需指定入口 proto 文件，goctl 和 protoc 会自动处理其余部分。
+- 循环导入会被检测并报错（与 protoc 行为一致）。

tools/goctl/rpc/example/04-transitive-import/README.md

@@ -0,0 +1,72 @@
+# Example 04: Transitive Imports
+
+This example demonstrates transitive proto imports, where A imports B and B imports C.
+
+## Proto Definition
+
+Three proto files form a transitive import chain, all sharing the same `go_package`:
+
+```protobuf
+option go_package = "example.com/demo/pb";
+```
+
+- `base.proto` — Layer C: defines base types (`BaseResp`).
+- `middleware.proto` — Layer B: imports `base.proto`, defines `RequestMeta`.
+- `main.proto` — Layer A: imports `middleware.proto`, defines the `PingService` (entry point).
+
+Import chain: `main.proto` → `middleware.proto` → `base.proto`
+
+## 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:
+
+```bash
+goctl rpc protoc main.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 .
+```
+
+Generated directory structure:
+
+```
+output/
+├── etc
+│   └── pingsvc.yaml
+├── go.mod
+├── internal
+│   ├── config
+│   │   └── config.go
+│   ├── logic
+│   │   └── pinglogic.go
+│   ├── server
+│   │   └── pingserviceserver.go
+│   └── svc
+│       └── servicecontext.go
+├── pb
+│   ├── base.pb.go
+│   ├── main.pb.go
+│   ├── main_grpc.pb.go
+│   └── middleware.pb.go
+├── pingservice
+│   └── pingservice.go
+└── pingsvc.go
+```
+
+## Key Points
+
+- Three proto files (`base.proto` → `middleware.proto` → `main.proto`) form a transitive import chain.
+- goctl recursively resolves all transitive imports automatically.
+- All three files share the same `go_package = "example.com/demo/pb"`.
+- You only need to specify the entry proto file — goctl and protoc handle the rest.
+- Circular imports are detected and will cause an error (same as protoc behavior).

tools/goctl/rpc/example/04-transitive-import/base.proto

@@ -0,0 +1,10 @@
+syntax = "proto3";
+
+package base;
+
+option go_package = "example.com/demo/pb";
+
+message BaseResp {
+  int32  code = 1;
+  string msg  = 2;
+}

tools/goctl/rpc/example/04-transitive-import/main.proto

@@ -0,0 +1,19 @@
+syntax = "proto3";
+
+package pingsvc;
+
+option go_package = "example.com/demo/pb";
+
+import "middleware.proto";
+
+message PingReq {
+  middleware.RequestMeta meta = 1;
+}
+
+message PingReply {
+  string pong = 1;
+}
+
+service PingService {
+  rpc Ping(PingReq) returns (PingReply);
+}

tools/goctl/rpc/example/04-transitive-import/middleware.proto

@@ -0,0 +1,12 @@
+syntax = "proto3";
+
+package middleware;
+
+option go_package = "example.com/demo/pb";
+
+import "base.proto";
+
+message RequestMeta {
+  string        trace_id = 1;
+  base.BaseResp base     = 2;
+}