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/03-import-subdir/README-cn.md

@@ -0,0 +1,82 @@
+# 示例 03：导入子目录中的 Proto 文件
+
+本示例演示如何导入子目录中的 proto 文件。
+
+## Proto 定义
+
+两个 proto 文件有**不同**的 `go_package` 值：
+
+- `order.proto` — 定义 `OrderService`，导入 `common/types.proto`。
+
+```protobuf
+option go_package = "example.com/demo/pb";
+```
+
+- `common/types.proto` — 定义可复用的分页和排序消息。
+
+```protobuf
+option go_package = "example.com/demo/pb/common";
+```
+
+`order.proto` 从子目录导入 `common/types.proto`：
+
+```protobuf
+import "common/types.proto";
+```
+
+注意两个文件的 `go_package` **不同**，因此会编译到不同的 Go 包中。
+
+## 生成命令
+
+首先，在输出目录中初始化 `go.mod`：
+
+```bash
+mkdir -p output && cd output && go mod init example.com/demo && cd ..
+```
+
+然后生成代码：
+
+```bash
+goctl rpc protoc order.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
+│   └── ordersvc.yaml
+├── go.mod
+├── internal
+│   ├── config
+│   │   └── config.go
+│   ├── logic
+│   │   ├── getorderlogic.go
+│   │   └── listorderslogic.go
+│   ├── server
+│   │   └── orderserviceserver.go
+│   └── svc
+│       └── servicecontext.go
+├── orderservice
+│   └── orderservice.go
+├── ordersvc.go
+└── pb
+    ├── common
+    │   └── types.pb.go
+    ├── order.pb.go
+    └── order_grpc.pb.go
+```
+
+## 要点说明
+
+- 两个 proto 文件有**不同**的 `go_package` 值，编译到不同的 Go 包中（`pb/` 和 `pb/common/`）。
+- `order.proto` 从子目录导入 `common/types.proto`。
+- 当导入的 proto 文件有不同的 `go_package` 时，goctl 会自动生成跨包导入。
+- `-I .` 告诉 protoc 从当前目录开始搜索，使其能够找到 `common/types.proto`。

tools/goctl/rpc/example/03-import-subdir/README.md

@@ -0,0 +1,82 @@
+# Example 03: Importing Proto from a Subdirectory
+
+This example demonstrates importing a proto file from a subdirectory.
+
+## Proto Definition
+
+Two proto files with **different** `go_package` values:
+
+- `order.proto` — Defines the `OrderService`, imports `common/types.proto`.
+
+```protobuf
+option go_package = "example.com/demo/pb";
+```
+
+- `common/types.proto` — Defines reusable pagination and sorting messages.
+
+```protobuf
+option go_package = "example.com/demo/pb/common";
+```
+
+`order.proto` imports `common/types.proto` from a subdirectory:
+
+```protobuf
+import "common/types.proto";
+```
+
+Note that the two files have **different** `go_package` values, so they compile into separate Go packages.
+
+## 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 order.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
+│   └── ordersvc.yaml
+├── go.mod
+├── internal
+│   ├── config
+│   │   └── config.go
+│   ├── logic
+│   │   ├── getorderlogic.go
+│   │   └── listorderslogic.go
+│   ├── server
+│   │   └── orderserviceserver.go
+│   └── svc
+│       └── servicecontext.go
+├── orderservice
+│   └── orderservice.go
+├── ordersvc.go
+└── pb
+    ├── common
+    │   └── types.pb.go
+    ├── order.pb.go
+    └── order_grpc.pb.go
+```
+
+## Key Points
+
+- Two proto files have **different** `go_package` values, so they compile into separate Go packages (`pb/` and `pb/common/`).
+- `order.proto` imports `common/types.proto` from a subdirectory.
+- When imported protos have a different `go_package`, goctl automatically generates cross-package imports.
+- The `-I .` flag tells protoc to search from the current directory, enabling it to find `common/types.proto`.

tools/goctl/rpc/example/03-import-subdir/common/types.proto

@@ -0,0 +1,15 @@
+syntax = "proto3";
+
+package common;
+
+option go_package = "example.com/demo/pb/common";
+
+message PageInfo {
+  int32 page = 1;
+  int32 size = 2;
+}
+
+message SortInfo {
+  string field = 1;
+  string order = 2;
+}

tools/goctl/rpc/example/03-import-subdir/order.proto

@@ -0,0 +1,35 @@
+syntax = "proto3";
+
+package ordersvc;
+
+option go_package = "example.com/demo/pb";
+
+import "common/types.proto";
+
+message OrderItem {
+  string id    = 1;
+  string name  = 2;
+  double price = 3;
+}
+
+message ListOrdersReq {
+  common.PageInfo page = 1;
+  common.SortInfo sort = 2;
+}
+
+message ListOrdersReply {
+  repeated OrderItem orders = 1;
+}
+
+message GetOrderReq {
+  string id = 1;
+}
+
+message GetOrderReply {
+  OrderItem order = 1;
+}
+
+service OrderService {
+  rpc ListOrders(ListOrdersReq) returns (ListOrdersReply);
+  rpc GetOrder(GetOrderReq) returns (GetOrderReply);
+}