mirror of
https://github.com/zeromicro/go-zero.git
synced 2026-06-22 18:01:57 +08:00
docs: add Korean translations (#5579)
Co-authored-by: kevin <wanjunfeng@gmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Jeonghyeon Kim
@@ -1,5 +1,7 @@
|
||||
# 变更日志
|
||||
|
||||
[English](CHANGELOG.md) | 中文 | [한국어](CHANGELOG-ko.md)
|
||||
|
||||
## 未发布
|
||||
|
||||
### 新功能
|
||||
@@ -40,7 +42,7 @@
|
||||
- `generator/typeref.go` — 新文件，核心类型解析引擎：
|
||||
- `resolveRPCTypeRef()` — 将 proto RPC 类型（简单类型、同包点号类型、跨包点号类型、Google WKT）解析为带正确导入路径的 Go 类型引用。
|
||||
- `resolveCallTypeRef()` — 客户端代码生成变体，支持类型别名。
|
||||
- `googleWKTTable` — 全部 16 种 Google 知名类型到 Go 等价类型的映射表。
|
||||
- `googleWKTTable` — 支持的 Google 知名类型到 Go 等价类型的映射表。
|
||||
- `generator/genserver.go` — `genFunctions()` 调用 `resolveRPCTypeRef()` 解析请求/响应类型并收集额外导入路径。
|
||||
- `generator/genlogic.go` — `genLogicFunction()` 使用 `resolveRPCTypeRef()`；新增 `addLogicImports()` 按需添加主 pb 导入和跨包导入。
|
||||
- `generator/gencall.go` — `genFunction()` 和 `getInterfaceFuncs()` 使用 `resolveCallTypeRef()` 处理类型别名和额外导入；新增 `buildExtraImportLines()` 辅助函数。
|
||||
@@ -67,7 +69,7 @@
|
||||
Google protobuf 知名类型现在可以直接用作 RPC 的请求/响应类型（而不仅仅是消息字段）。
|
||||
|
||||
**涉及文件：**
|
||||
- `generator/typeref.go` — `resolveGoogleWKT()` + `googleWKTTable` 处理所有标准类型。
|
||||
- `generator/typeref.go` — `resolveGoogleWKT()` + `googleWKTTable` 处理支持的标准类型。
|
||||
|
||||
**前后对比：**
|
||||
|
||||
|
||||
119
tools/goctl/rpc/CHANGELOG-ko.md
Normal file
119
tools/goctl/rpc/CHANGELOG-ko.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# 변경 로그
|
||||
|
||||
[English](CHANGELOG.md) | [中文](CHANGELOG-cn.md) | 한국어
|
||||
|
||||
## 릴리스 예정
|
||||
|
||||
### 새로운 기능
|
||||
|
||||
#### 외부 proto import 지원(`--proto_path` / `-I`)
|
||||
|
||||
`-I` / `--proto_path` 플래그로 외부 디렉터리의 proto 파일을 import할 수 있도록 지원을 추가했으며, 전체 전이 의존성 해결을 제공합니다.
|
||||
|
||||
**영향받는 파일:**
|
||||
- `generator/gen.go` — `ZRpcContext`에 `ProtoPaths` 필드를 추가하고, 코드 생성 전에 `ImportedProtos`를 채우는 `resolveImportedProtos()`를 추가했습니다.
|
||||
- `generator/genpb.go` — 전이적으로 import된 proto 파일을 자동 탐색해 `protoc` 명령에 추가하는 `buildProtocCmd()`를 추가하고, protoc 출력 경로에 맞는 상대 경로를 계산하는 `relativeToProtoPath()`를 추가했습니다.
|
||||
- `parser/import.go` — 새 파일(대규모 추가). 재귀적 전이 import 해결을 위한 `ResolveImports()`, import된 proto에서 `go_package` / `package` 메타데이터를 추출하는 `ParseImportedProtos()`, proto `package` 이름으로 O(1) 조회를 제공하는 `BuildProtoPackageMap()`을 구현합니다.
|
||||
- `parser/proto.go` — `Proto` 구조체에 `ImportedProtos []ImportedProto` 필드를 추가했습니다.
|
||||
- `cli/cli.go` — `RPCNew`의 `ProtoPaths`를 `ZRpcContext`로 전달합니다.
|
||||
- `cli/zrpc.go` — `VarStringSliceProtoPath`를 `ZRpcContext.ProtoPaths`로 전달합니다.
|
||||
|
||||
**이전 vs 이후:**
|
||||
|
||||
| | 이전 | 이후 |
|
||||
|---|---|---|
|
||||
| 외부 디렉터리의 proto import | ❌ 지원하지 않음, 모든 타입이 같은 파일에 있어야 함 | ✅ `-I ./ext_protos`로 검색 경로 추가 |
|
||||
| 전이 import(A → B → C) | ❌ 직접 import만 인식 | ✅ 모든 전이 의존성을 재귀적으로 해결 |
|
||||
| import된 proto의 `.pb.go` 생성 | ❌ 수동, 파일마다 protoc를 별도로 실행해야 함 | ✅ 자동, import된 proto를 protoc 명령에 추가 |
|
||||
| proto 검색 경로 | ❌ 원본 파일 디렉터리만 | ✅ protoc와 동일하게 여러 `-I` 경로 지원 |
|
||||
|
||||
**동작:**
|
||||
- proto 파일의 모든 `import` 선언을 전이적으로 순회하며, `google/*` well-known types는 건너뜁니다.
|
||||
- 각 `-I` 디렉터리에서 import된 파일을 검색하며, 사용자 경로에서 찾을 수 없는 시스템 수준 proto는 조용히 건너뜁니다.
|
||||
- 발견한 proto 파일을 `protoc` 명령에 추가해 메인 proto와 함께 `.pb.go` 파일이 생성되도록 합니다.
|
||||
|
||||
---
|
||||
|
||||
#### 패키지 간 타입 해석
|
||||
|
||||
import된 proto의 `go_package`가 메인 proto와 **다른** 경우, goctl은 이제 서버, 로직, 클라이언트 코드에서 올바른 Go import 경로와 한정된 타입 참조를 자동 생성합니다.
|
||||
|
||||
**영향받는 파일:**
|
||||
- `generator/typeref.go` — 새 파일. 핵심 타입 해석 엔진:
|
||||
- `resolveRPCTypeRef()` — proto RPC 타입(단순 타입, 동일 패키지 점 표기 타입, 패키지 간 점 표기 타입, Google WKT)을 올바른 import 경로를 가진 Go 타입 참조로 해석합니다.
|
||||
- `resolveCallTypeRef()` — 타입 alias를 지원하는 클라이언트 코드 생성용 변형입니다.
|
||||
- `googleWKTTable` — 지원되는 Google well-known types를 Go 대응 타입으로 매핑하는 테이블입니다.
|
||||
- `generator/genserver.go` — `genFunctions()`가 이제 요청/응답 타입에 대해 `resolveRPCTypeRef()`를 호출하고 추가 import 경로를 수집합니다.
|
||||
- `generator/genlogic.go` — `genLogicFunction()`이 `resolveRPCTypeRef()`를 사용합니다. main pb import와 패키지 간 import를 조건부로 포함하는 `addLogicImports()`를 추가했습니다.
|
||||
- `generator/gencall.go` — `genFunction()`과 `getInterfaceFuncs()`가 타입 alias와 추가 import를 위해 `resolveCallTypeRef()`를 사용합니다. `buildExtraImportLines()` 헬퍼를 추가했습니다.
|
||||
- `generator/call.tpl` — 패키지 간 import 라인을 위한 `{{.extraImports}}` 플레이스홀더를 추가했습니다.
|
||||
|
||||
**이전 vs 이후:**
|
||||
|
||||
| Proto 타입 | 이전 | 이후 |
|
||||
|---|---|---|
|
||||
| `GetReq`(같은 파일) | `pb.GetReq` | `pb.GetReq`(변경 없음) |
|
||||
| `ext.ExtReq`(같은 `go_package`) | ❌ 오류: "request type must defined in" | ✅ `pb.ExtReq` — 메인 proto의 Go 패키지에 병합 |
|
||||
| `common.TypesReq`(다른 `go_package`) | ❌ 오류: "request type must defined in" | ✅ `common.TypesReq` + 자동 생성 `import "example.com/demo/pb/common"` |
|
||||
| `google.protobuf.Empty` | ❌ 오류: "request type must defined in" | ✅ `emptypb.Empty` + 자동 생성 import |
|
||||
|
||||
**동작:**
|
||||
- 단순 타입(예: `GetReq`)은 추가 import 없이 `pb.GetReq`로 해석됩니다.
|
||||
- 동일 패키지 점 표기 타입(예: `ext.ExtReq`, `ext`가 같은 `go_package`를 가진 경우)은 `pb.ExtReq`로 해석됩니다.
|
||||
- 패키지 간 점 표기 타입(예: `common.TypesReq`, `common`이 다른 `go_package`를 가진 경우)은 올바른 Go import 경로가 자동 추가된 `common.TypesReq`로 해석됩니다.
|
||||
|
||||
---
|
||||
|
||||
#### RPC 파라미터로 Google well-known types 사용
|
||||
|
||||
Google protobuf well-known types를 이제 메시지 필드뿐 아니라 RPC 요청/응답 타입으로도 직접 사용할 수 있습니다.
|
||||
|
||||
**영향받는 파일:**
|
||||
- `generator/typeref.go` — `resolveGoogleWKT()` + `googleWKTTable`이 지원되는 표준 타입을 처리합니다.
|
||||
|
||||
**이전 vs 이후:**
|
||||
|
||||
| Proto 타입 | 이전(RPC 파라미터) | 이후(RPC 파라미터) |
|
||||
|---|---|---|
|
||||
| `google.protobuf.Empty` | ❌ 오류 | ✅ `emptypb.Empty` |
|
||||
| `google.protobuf.Timestamp` | ❌ 오류 | ✅ `timestamppb.Timestamp` |
|
||||
| `google.protobuf.Duration` | ❌ 오류 | ✅ `durationpb.Duration` |
|
||||
| `google.protobuf.Any` | ❌ 오류 | ✅ `anypb.Any` |
|
||||
| `google.protobuf.Struct` | ❌ 오류 | ✅ `structpb.Struct` |
|
||||
| `google.protobuf.FieldMask` | ❌ 오류 | ✅ `fieldmaskpb.FieldMask` |
|
||||
| `google.protobuf.*Value` | ❌ 오류 | ✅ `wrapperspb.*Value` |
|
||||
|
||||
> 참고: 이 타입들은 이전에도 **메시지 필드**로 사용할 수 있었습니다. 이번 변경으로 **RPC 요청/응답 타입**으로도 직접 사용할 수 있습니다.
|
||||
|
||||
**지원 타입:**
|
||||
|
||||
| Proto 타입 | Go 타입 |
|
||||
|---|---|
|
||||
| `google.protobuf.Empty` | `emptypb.Empty` |
|
||||
| `google.protobuf.Timestamp` | `timestamppb.Timestamp` |
|
||||
| `google.protobuf.Duration` | `durationpb.Duration` |
|
||||
| `google.protobuf.Any` | `anypb.Any` |
|
||||
| `google.protobuf.Struct` | `structpb.Struct` |
|
||||
| `google.protobuf.Value` | `structpb.Value` |
|
||||
| `google.protobuf.ListValue` | `structpb.ListValue` |
|
||||
| `google.protobuf.FieldMask` | `fieldmaskpb.FieldMask` |
|
||||
| `google.protobuf.*Value` (wrappers) | `wrapperspb.*Value` |
|
||||
|
||||
---
|
||||
|
||||
### 호환성이 깨지는 변경
|
||||
|
||||
#### RPC 정의에서 점 표기 타입 이름 허용
|
||||
|
||||
이전에는 goctl이 점(.)이 포함된 RPC 요청/응답 타입(예: `base.Req`)을 거부했으며, 모든 타입이 같은 proto 파일에 정의되어 있어야 했습니다. 이 제한이 제거되었습니다.
|
||||
|
||||
**이전 vs 이후:**
|
||||
|
||||
| Proto 정의 | 이전 | 이후 |
|
||||
|---|---|---|
|
||||
| `rpc Fetch(base.Req) returns (base.Reply)` | ❌ 파싱 오류: "request type must defined in xxx.proto" | ✅ 성공적으로 파싱되며, `base.Req`가 import된 proto를 통해 해석됨 |
|
||||
| `rpc Ping(google.protobuf.Empty) returns (Reply)` | ❌ 파싱 오류: "request type must defined in xxx.proto" | ✅ 성공적으로 파싱되며, `emptypb.Empty`로 해석됨 |
|
||||
|
||||
**영향받는 파일:**
|
||||
- `parser/service.go` — 점(.)이 포함된 타입 이름을 `"request type must defined in"` / `"returns type must defined in"` 오류로 거부하던 검증 루프를 제거했습니다.
|
||||
- `parser/parser_test.go` — `TestDefaultProtoParseCaseInvalidRequestType`과 `TestDefaultProtoParseCaseInvalidResponseType`을 이름을 변경하고 업데이트하여 점 표기 타입이 이제 성공적으로 파싱되는지 검증합니다.
|
||||
@@ -1,5 +1,7 @@
|
||||
# Changelog
|
||||
|
||||
English | [中文](CHANGELOG-cn.md) | [한국어](CHANGELOG-ko.md)
|
||||
|
||||
## Unreleased
|
||||
|
||||
### New Features
|
||||
@@ -40,7 +42,7 @@ When an imported proto has a **different** `go_package` from the main proto, goc
|
||||
- `generator/typeref.go` — New file. Core type resolution engine:
|
||||
- `resolveRPCTypeRef()` — Resolves proto RPC types (simple, same-package dotted, cross-package dotted, Google WKT) to Go type references with correct import paths.
|
||||
- `resolveCallTypeRef()` — Variant for client code generation with type alias support.
|
||||
- `googleWKTTable` — Mapping table for all 16 Google well-known types to their Go equivalents.
|
||||
- `googleWKTTable` — Mapping table for supported Google well-known types to their Go equivalents.
|
||||
- `generator/genserver.go` — `genFunctions()` now calls `resolveRPCTypeRef()` for request/response types and collects extra import paths.
|
||||
- `generator/genlogic.go` — `genLogicFunction()` uses `resolveRPCTypeRef()`; added `addLogicImports()` to conditionally include main pb import and cross-package imports.
|
||||
- `generator/gencall.go` — `genFunction()` and `getInterfaceFuncs()` use `resolveCallTypeRef()` for type aliases and extra imports; added `buildExtraImportLines()` helper.
|
||||
@@ -67,7 +69,7 @@ When an imported proto has a **different** `go_package` from the main proto, goc
|
||||
Google protobuf well-known types can now be used directly as RPC request/response types (not just as message fields).
|
||||
|
||||
**Affected files:**
|
||||
- `generator/typeref.go` — `resolveGoogleWKT()` + `googleWKTTable` handles all standard types.
|
||||
- `generator/typeref.go` — `resolveGoogleWKT()` + `googleWKTTable` handles supported standard types.
|
||||
|
||||
**Before vs After:**
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# goctl rpc — RPC 代码生成
|
||||
|
||||
[English](README.md) | 中文
|
||||
[English](README.md) | 中文 | [한국어](README-ko.md)
|
||||
|
||||
goctl rpc 是 `goctl` 脚手架下的 RPC 服务代码生成模块，基于 `.proto` 文件生成完整的 zRPC 服务代码。你只需编写 proto 定义和业务逻辑，其余代码均由工具自动生成。
|
||||
|
||||
@@ -10,7 +10,7 @@ goctl rpc 是 `goctl` 脚手架下的 RPC 服务代码生成模块，基于 `.pr
|
||||
- **外部 Proto 导入**：支持跨目录、跨包的 proto 导入，自动解析传递性依赖
|
||||
- **多服务模式**：单个 proto 文件中定义多个 service，按服务名自动分组
|
||||
- **流式支持**：支持服务端流、客户端流和双向流
|
||||
- **Google 标准类型**：自动识别 `google.protobuf.*` 类型并生成正确的 Go 导入
|
||||
- **Google 标准类型**：自动识别支持的 `google.protobuf.*` 类型并生成正确的 Go 导入
|
||||
- **客户端生成**：自动生成封装好的 RPC 客户端代码
|
||||
|
||||
## 前置条件
|
||||
@@ -311,5 +311,5 @@ goctl 自动识别并正确处理 Google protobuf 标准类型：
|
||||
| 06 | [标准类型](example/06-wellknown-types/) | 消息中使用 Timestamp 等 |
|
||||
| 07 | [外部 Proto（同包）](example/07-external-proto-same-pkg/) | 外部 proto，相同 go_package |
|
||||
| 08 | [外部 Proto（跨包）](example/08-external-proto-diff-pkg/) | 外部 proto，不同 go_package |
|
||||
| 09 | [标准类型作参数](example/09-google-types-as-rpc/) | Empty/Timestamp 作为 RPC 参数 |
|
||||
| 09 | [Google 标准类型作参数](example/09-google-types-as-rpc/) | Empty/Timestamp 作为 RPC 参数 |
|
||||
| 10 | [流式通信](example/10-streaming/) | 服务端/客户端/双向流 |
|
||||
|
||||
315
tools/goctl/rpc/README-ko.md
Normal file
315
tools/goctl/rpc/README-ko.md
Normal file
@@ -0,0 +1,315 @@
|
||||
# goctl rpc — RPC 코드 생성
|
||||
|
||||
[English](README.md) | [中文](README-cn.md) | 한국어
|
||||
|
||||
goctl rpc는 `goctl` 스캐폴딩 도구의 RPC 서비스 코드 생성 모듈입니다. `.proto` 파일에서 완전한 zRPC 서비스를 생성합니다. proto 정의와 비즈니스 로직만 작성하면 나머지 보일러플레이트 코드는 모두 자동으로 생성됩니다.
|
||||
|
||||
## 기능
|
||||
|
||||
- **protoc 호환**: protoc와 완전히 호환되며 모든 protoc 인수를 그대로 전달합니다.
|
||||
- **외부 proto import**: 디렉터리와 패키지를 넘나드는 proto import를 지원하고 전이 의존성을 자동으로 해결합니다.
|
||||
- **다중 서비스**: 하나의 proto 파일에 여러 서비스를 정의하고, 서비스 이름별로 자동 그룹화합니다.
|
||||
- **스트리밍 지원**: 서버 스트리밍, 클라이언트 스트리밍, 양방향 스트리밍을 지원합니다.
|
||||
- **Google well-known types**: 지원되는 `google.protobuf.*` 타입을 자동으로 인식하고 올바른 Go import를 생성합니다.
|
||||
- **클라이언트 생성**: 자동 생성된 RPC 클라이언트 래퍼 코드를 제공합니다.
|
||||
|
||||
## 사전 요구 사항
|
||||
|
||||
```bash
|
||||
# protoc 플러그인 설치
|
||||
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
|
||||
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
|
||||
```
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
### 방법 1: 즉시 서비스 만들기
|
||||
|
||||
```bash
|
||||
goctl rpc new greeter
|
||||
```
|
||||
|
||||
완전한 프로젝트 구조가 생성됩니다.
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
### 방법 2: proto 파일에서 생성하기
|
||||
|
||||
1. proto 템플릿을 생성합니다.
|
||||
|
||||
```bash
|
||||
goctl rpc template -o=user.proto
|
||||
```
|
||||
|
||||
2. 출력 디렉터리를 초기화하고 서비스 코드를 생성합니다.
|
||||
|
||||
```bash
|
||||
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 .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 명령 참조
|
||||
|
||||
### `goctl rpc protoc`
|
||||
|
||||
`.proto` 파일에서 zRPC 서비스 코드를 생성합니다.
|
||||
|
||||
```bash
|
||||
goctl rpc protoc <proto_file> [flags]
|
||||
```
|
||||
|
||||
**예시:**
|
||||
|
||||
```bash
|
||||
# 기본 사용법
|
||||
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 .
|
||||
|
||||
# 다중 서비스 모드
|
||||
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
|
||||
|
||||
# 외부 proto import
|
||||
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
|
||||
|
||||
# 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 .
|
||||
```
|
||||
|
||||
**플래그:**
|
||||
|
||||
| 플래그 | 축약 | 타입 | 기본값 | 설명 |
|
||||
|------|-------|------|---------|-------------|
|
||||
| `--zrpc_out` | | string | **필수** | zRPC 서비스 코드 출력 디렉터리 |
|
||||
| `--go_out` | | string | **필수** | protoc Go 코드 출력 디렉터리 |
|
||||
| `--go-grpc_out` | | string | **필수** | protoc gRPC 코드 출력 디렉터리 |
|
||||
| `--go_opt` | | string | | protoc-gen-go 옵션(예: `module=example.com/demo`) |
|
||||
| `--go-grpc_opt` | | string | | protoc-gen-go-grpc 옵션(예: `module=example.com/demo`) |
|
||||
| `--proto_path` | `-I` | string[] | | proto import 검색 디렉터리(반복 지정 가능) |
|
||||
| `--multiple` | `-m` | bool | `false` | 다중 서비스 모드 |
|
||||
| `--client` | `-c` | bool | `true` | RPC 클라이언트 코드 생성 |
|
||||
| `--style` | | string | `gozero` | 파일 이름 스타일 |
|
||||
| `--module` | | string | | 사용자 지정 Go module 이름 |
|
||||
| `--name-from-filename` | | bool | `false` | 서비스 이름에 `package` 이름 대신 파일 이름 사용 |
|
||||
| `--verbose` | `-v` | bool | `false` | 상세 로그 활성화 |
|
||||
| `--home` | | string | | goctl 템플릿 디렉터리 |
|
||||
| `--remote` | | string | | 원격 템플릿 Git 저장소 URL |
|
||||
| `--branch` | | string | | 원격 템플릿 브랜치 |
|
||||
|
||||
### `goctl rpc new`
|
||||
|
||||
완전한 RPC 서비스 프로젝트를 빠르게 생성합니다.
|
||||
|
||||
```bash
|
||||
goctl rpc new <service_name> [flags]
|
||||
```
|
||||
|
||||
**플래그:**
|
||||
|
||||
| 플래그 | 축약 | 타입 | 기본값 | 설명 |
|
||||
|------|-------|------|---------|-------------|
|
||||
| `--style` | | string | `gozero` | 파일 이름 스타일 |
|
||||
| `--client` | `-c` | bool | `true` | RPC 클라이언트 코드 생성 |
|
||||
| `--module` | | string | | 사용자 지정 Go module 이름 |
|
||||
| `--verbose` | `-v` | bool | `false` | 상세 로그 활성화 |
|
||||
| `--idea` | | bool | `false` | IDE 프로젝트 마커 생성 |
|
||||
| `--name-from-filename` | | bool | `false` | 서비스 이름에 `package` 이름 대신 파일 이름 사용 |
|
||||
| `--home` | | string | | goctl 템플릿 디렉터리 |
|
||||
| `--remote` | | string | | 원격 템플릿 Git 저장소 URL |
|
||||
| `--branch` | | string | | 원격 템플릿 브랜치 |
|
||||
|
||||
### `goctl rpc template`
|
||||
|
||||
proto 파일 템플릿을 생성합니다.
|
||||
|
||||
```bash
|
||||
goctl rpc template -o=<output_file> [flags]
|
||||
```
|
||||
|
||||
**플래그:**
|
||||
|
||||
| 플래그 | 타입 | 설명 |
|
||||
|------|------|-------------|
|
||||
| `-o` | string | 출력 파일 경로(필수) |
|
||||
| `--home` | string | goctl 템플릿 디렉터리 |
|
||||
| `--remote` | string | 원격 템플릿 Git 저장소 URL |
|
||||
| `--branch` | string | 원격 템플릿 브랜치 |
|
||||
|
||||
---
|
||||
|
||||
## 기능 상세
|
||||
|
||||
### 다중 서비스 모드(`--multiple`)
|
||||
|
||||
proto 파일에 여러 `service` 정의가 포함된 경우 `--multiple` 플래그가 필요합니다.
|
||||
|
||||
```protobuf
|
||||
service SearchService {
|
||||
rpc Search(SearchReq) returns (SearchReply);
|
||||
}
|
||||
|
||||
service NotifyService {
|
||||
rpc Notify(NotifyReq) returns (NotifyReply);
|
||||
}
|
||||
```
|
||||
|
||||
**`--multiple` 사용 시 디렉터리 차이:**
|
||||
|
||||
| 기능 | 기본 모드 | `--multiple` 모드 |
|
||||
|---------|-------------|-------------------|
|
||||
| proto당 서비스 수 | 정확히 1개 | 1개 이상 |
|
||||
| 클라이언트 디렉터리 | 서비스 이름 기반 | 고정 `client/` 디렉터리 |
|
||||
| 코드 구성 | 평면 구조 | 서비스 이름별 그룹화 |
|
||||
|
||||
**`--multiple=false`(기본값) 디렉터리 구조:**
|
||||
|
||||
```
|
||||
output/
|
||||
├── greeterclient/
|
||||
│ └── greeter.go
|
||||
├── internal/
|
||||
│ ├── logic/
|
||||
│ │ └── sayhellologic.go
|
||||
│ └── server/
|
||||
│ └── greeterserver.go
|
||||
└── ...
|
||||
```
|
||||
|
||||
**`--multiple=true` 디렉터리 구조:**
|
||||
|
||||
```
|
||||
output/
|
||||
├── client/
|
||||
│ ├── searchservice/
|
||||
│ │ └── searchservice.go
|
||||
│ └── notifyservice/
|
||||
│ └── notifyservice.go
|
||||
├── internal/
|
||||
│ ├── logic/
|
||||
│ │ ├── searchservice/
|
||||
│ │ │ └── searchlogic.go
|
||||
│ │ └── notifyservice/
|
||||
│ │ └── notifylogic.go
|
||||
│ └── server/
|
||||
│ ├── searchservice/
|
||||
│ │ └── searchserviceserver.go
|
||||
│ └── notifyservice/
|
||||
│ └── notifyserviceserver.go
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 외부 proto import(`--proto_path`)
|
||||
|
||||
`-I` / `--proto_path`로 추가 proto 검색 디렉터리를 지정합니다. 지원되는 시나리오는 다음과 같습니다.
|
||||
|
||||
- **같은 디렉터리 import**: `import "types.proto";`
|
||||
- **하위 디렉터리 import**: `import "common/types.proto";`
|
||||
- **외부 디렉터리 import**: 프로젝트 외부에 있는 proto 파일
|
||||
- **전이 import**: A가 B를 import하고 B가 C를 import하는 경우 — goctl이 재귀적으로 해결합니다.
|
||||
- **패키지 간 import**: 서로 다른 `go_package` 값을 가진 파일에 대해 올바른 Go import를 자동으로 생성합니다.
|
||||
|
||||
```bash
|
||||
# 여러 디렉터리에서 proto 파일 검색
|
||||
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
|
||||
```
|
||||
|
||||
### 서비스 이름 지정
|
||||
|
||||
기본적으로 서비스 이름은 proto의 **`package` 이름**에서 파생됩니다(예: `package user;` → 서비스 이름 `user`). 이를 통해 여러 proto 파일이 같은 `package`를 공유할 수 있습니다.
|
||||
|
||||
```
|
||||
protos/
|
||||
├── user_base.proto # package user;
|
||||
├── user_auth.proto # package user;
|
||||
└── user_profile.proto # package user;
|
||||
```
|
||||
|
||||
세 파일은 모두 하나의 `user` 서비스로 생성됩니다.
|
||||
|
||||
서비스 이름에 proto 파일 이름을 사용하려면(레거시 동작) `--name-from-filename` 플래그를 추가하세요.
|
||||
|
||||
### 스트리밍 RPC
|
||||
|
||||
세 가지 gRPC 스트리밍 패턴을 모두 지원합니다.
|
||||
|
||||
```protobuf
|
||||
service StreamService {
|
||||
rpc ServerStream(Req) returns (stream Reply); // 서버 스트리밍
|
||||
rpc ClientStream(stream Req) returns (Reply); // 클라이언트 스트리밍
|
||||
rpc BidiStream(stream Req) returns (stream Reply); // 양방향 스트리밍
|
||||
}
|
||||
```
|
||||
|
||||
### Google well-known types
|
||||
|
||||
goctl은 지원되는 Google protobuf well-known types를 자동으로 인식하고 처리합니다.
|
||||
|
||||
| Proto 타입 | Go 타입 |
|
||||
|-----------|---------|
|
||||
| `google.protobuf.Empty` | `emptypb.Empty` |
|
||||
| `google.protobuf.Timestamp` | `timestamppb.Timestamp` |
|
||||
| `google.protobuf.Duration` | `durationpb.Duration` |
|
||||
| `google.protobuf.Any` | `anypb.Any` |
|
||||
| `google.protobuf.Struct` | `structpb.Struct` |
|
||||
| `google.protobuf.FieldMask` | `fieldmaskpb.FieldMask` |
|
||||
| `google.protobuf.*Value` | `wrapperspb.*Value` |
|
||||
|
||||
이 타입들은 RPC 파라미터 타입으로 직접 사용할 수 있으며, goctl이 올바른 import를 자동으로 생성합니다.
|
||||
|
||||
---
|
||||
|
||||
## 예제
|
||||
|
||||
모든 생성 시나리오를 다루는 10개의 완전한 예제는 [example/](example/) 디렉터리를 참고하세요.
|
||||
|
||||
| # | 예제 | 시나리오 |
|
||||
|---|---------|----------|
|
||||
| 01 | [기본 서비스](example/01-basic/) | 단일 서비스, import 없음 |
|
||||
| 02 | [동일 디렉터리 import](example/02-import-sibling/) | 같은 디렉터리에서 import |
|
||||
| 03 | [하위 디렉터리 import](example/03-import-subdir/) | 하위 디렉터리에서 import |
|
||||
| 04 | [전이 import](example/04-transitive-import/) | A → B → C 의존성 체인 |
|
||||
| 05 | [다중 서비스](example/05-multiple-services/) | `--multiple` 모드 |
|
||||
| 06 | [Google well-known types](example/06-wellknown-types/) | 메시지에서 Timestamp 등 사용 |
|
||||
| 07 | [외부 proto(동일 패키지)](example/07-external-proto-same-pkg/) | 외부 proto, 같은 go_package |
|
||||
| 08 | [외부 proto(다른 패키지)](example/08-external-proto-diff-pkg/) | 외부 proto, 다른 go_package |
|
||||
| 09 | [Google well-known types를 파라미터로 사용](example/09-google-types-as-rpc/) | Empty/Timestamp를 RPC 파라미터로 사용 |
|
||||
| 10 | [스트리밍](example/10-streaming/) | 서버/클라이언트/양방향 스트리밍 |
|
||||
@@ -1,6 +1,6 @@
|
||||
# goctl rpc — RPC Code Generation
|
||||
|
||||
English | [中文](README-cn.md)
|
||||
English | [中文](README-cn.md) | [한국어](README-ko.md)
|
||||
|
||||
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.
|
||||
|
||||
@@ -10,7 +10,7 @@ goctl rpc is the RPC service code generation module of the `goctl` scaffold. It
|
||||
- **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
|
||||
- **Google well-known types**: Automatic recognition of supported `google.protobuf.*` types with correct Go imports
|
||||
- **Client generation**: Auto-generated RPC client wrapper code
|
||||
|
||||
## Prerequisites
|
||||
@@ -311,5 +311,5 @@ See the [example/](example/) directory for 10 complete examples covering all gen
|
||||
| 06 | [Well-known types](example/06-wellknown-types/) | Timestamp etc. in messages |
|
||||
| 07 | [External proto (same pkg)](example/07-external-proto-same-pkg/) | External proto, same go_package |
|
||||
| 08 | [External proto (diff pkg)](example/08-external-proto-diff-pkg/) | External proto, different go_package |
|
||||
| 09 | [Google types as params](example/09-google-types-as-rpc/) | Empty/Timestamp as RPC parameters |
|
||||
| 09 | [Google well-known types as params](example/09-google-types-as-rpc/) | Empty/Timestamp as RPC parameters |
|
||||
| 10 | [Streaming](example/10-streaming/) | Server/client/bidirectional streaming |
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 示例 01：基础 RPC 服务
|
||||
|
||||
[English](README.md) | 中文 | [한국어](README-ko.md)
|
||||
|
||||
这是使用 goctl 生成 RPC 服务的最简单示例。
|
||||
|
||||
## Proto 定义
|
||||
|
||||
102
tools/goctl/rpc/example/01-basic/README-ko.md
Normal file
102
tools/goctl/rpc/example/01-basic/README-ko.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# 예제 01: 기본 RPC 서비스
|
||||
|
||||
[English](README.md) | [中文](README-cn.md) | 한국어
|
||||
|
||||
이 예제는 goctl로 RPC 서비스를 생성하는 가장 간단한 예제입니다.
|
||||
|
||||
## proto 정의
|
||||
|
||||
외부 import 없이 하나의 서비스와 하나의 RPC 메서드를 가진 `greeter.proto` 파일 하나를 사용합니다.
|
||||
|
||||
`go_package`는 전체 모듈 경로를 사용합니다.
|
||||
|
||||
```protobuf
|
||||
option go_package = "example.com/demo/greeter";
|
||||
```
|
||||
|
||||
## 생성 명령
|
||||
|
||||
### 방법 1: `goctl rpc new`로 빠르게 시작
|
||||
|
||||
```bash
|
||||
# 한 번의 명령으로 완전한 RPC 프로젝트 생성
|
||||
goctl rpc new greeter
|
||||
```
|
||||
|
||||
이 명령은 proto 파일과 서비스 코드를 함께 생성합니다.
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
### 방법 2: 기존 proto에서 생성
|
||||
|
||||
먼저 출력 디렉터리에 `go.mod`를 초기화합니다.
|
||||
|
||||
```bash
|
||||
mkdir -p output && cd output && go mod init example.com/demo && cd ..
|
||||
```
|
||||
|
||||
그런 다음 코드를 생성합니다.
|
||||
|
||||
```bash
|
||||
goctl rpc protoc greeter.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
|
||||
│ └── greeter.yaml
|
||||
├── go.mod
|
||||
├── greeter
|
||||
│ ├── greeter.pb.go
|
||||
│ └── greeter_grpc.pb.go
|
||||
├── greeter.go
|
||||
├── greeterclient
|
||||
│ └── greeter.go
|
||||
└── internal
|
||||
├── config
|
||||
│ └── config.go
|
||||
├── logic
|
||||
│ └── sayhellologic.go
|
||||
├── server
|
||||
│ └── greeterserver.go
|
||||
└── svc
|
||||
└── servicecontext.go
|
||||
```
|
||||
|
||||
## 핵심 사항
|
||||
|
||||
- 가장 단순한 시나리오입니다. proto 파일 하나, 서비스 하나, RPC 메서드 하나를 사용합니다.
|
||||
- `go_package`는 상대 경로가 아닌 전체 모듈 경로(`example.com/demo/greeter`)를 사용합니다.
|
||||
- `--module` 플래그는 goctl에 Go 모듈 이름을 알려줍니다. `--go_opt=module=...`과 `--go-grpc_opt=module=...`은 protoc에 출력 경로에서 모듈 접두사를 제거하라고 알려줍니다.
|
||||
- `--zrpc_out` 플래그는 goctl이 생성하는 서비스 코드의 출력 위치를 지정합니다.
|
||||
- `--go_out`과 `--go-grpc_out` 플래그는 protoc가 생성하는 코드의 출력 위치를 지정합니다.
|
||||
- 비즈니스 로직을 구현하려면 logic 파일(`internal/logic/sayhellologic.go`)을 수정하세요.
|
||||
@@ -1,5 +1,7 @@
|
||||
# Example 01: Basic RPC Service
|
||||
|
||||
English | [中文](README-cn.md) | [한국어](README-ko.md)
|
||||
|
||||
This is the simplest example of generating an RPC service with goctl.
|
||||
|
||||
## Proto Definition
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 示例 02：导入同级 Proto 文件
|
||||
|
||||
[English](README.md) | 中文 | [한국어](README-ko.md)
|
||||
|
||||
本示例演示如何导入同一目录下的 proto 文件。
|
||||
|
||||
## Proto 定义
|
||||
|
||||
79
tools/goctl/rpc/example/02-import-sibling/README-ko.md
Normal file
79
tools/goctl/rpc/example/02-import-sibling/README-ko.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# 예제 02: 같은 디렉터리의 proto 파일 import
|
||||
|
||||
[English](README.md) | [中文](README-cn.md) | 한국어
|
||||
|
||||
이 예제는 같은 디렉터리에 있는 proto 파일을 import하는 방법을 보여줍니다.
|
||||
|
||||
## proto 정의
|
||||
|
||||
같은 디렉터리의 두 proto 파일이 동일한 `go_package`를 공유합니다.
|
||||
|
||||
- `types.proto` — 공유 메시지 타입(`User`)을 정의합니다.
|
||||
- `user.proto` — RPC 서비스를 정의하고 `types.proto`를 import합니다.
|
||||
|
||||
두 파일은 전체 모듈 경로를 가진 동일한 `go_package`를 사용합니다.
|
||||
|
||||
```protobuf
|
||||
option go_package = "example.com/demo/pb";
|
||||
```
|
||||
|
||||
`user.proto`는 다음과 같이 `types.proto`를 import합니다.
|
||||
|
||||
```protobuf
|
||||
import "types.proto";
|
||||
```
|
||||
|
||||
## 생성 명령
|
||||
|
||||
먼저 출력 디렉터리에 `go.mod`를 초기화합니다.
|
||||
|
||||
```bash
|
||||
mkdir -p output && cd output && go mod init example.com/demo && cd ..
|
||||
```
|
||||
|
||||
그런 다음 코드를 생성합니다.
|
||||
|
||||
```bash
|
||||
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 .
|
||||
```
|
||||
|
||||
생성되는 디렉터리 구조:
|
||||
|
||||
```
|
||||
output/
|
||||
├── etc
|
||||
│ └── usersvc.yaml
|
||||
├── go.mod
|
||||
├── internal
|
||||
│ ├── config
|
||||
│ │ └── config.go
|
||||
│ ├── logic
|
||||
│ │ ├── createuserlogic.go
|
||||
│ │ └── getuserlogic.go
|
||||
│ ├── server
|
||||
│ │ └── userserviceserver.go
|
||||
│ └── svc
|
||||
│ └── servicecontext.go
|
||||
├── pb
|
||||
│ ├── types.pb.go
|
||||
│ ├── user.pb.go
|
||||
│ └── user_grpc.pb.go
|
||||
├── userservice
|
||||
│ └── userservice.go
|
||||
└── usersvc.go
|
||||
```
|
||||
|
||||
## 핵심 사항
|
||||
|
||||
- 두 proto 파일(`user.proto`와 `types.proto`)은 동일한 `go_package = "example.com/demo/pb"`를 공유하며 하나의 Go 패키지로 컴파일됩니다.
|
||||
- `user.proto`는 `import "types.proto"`로 `types.proto`를 import합니다.
|
||||
- 여러 proto 파일이 동일한 `go_package`를 공유하면 하나의 Go 패키지로 컴파일됩니다.
|
||||
- `service` 정의를 포함한 proto 파일만 `goctl rpc protoc`에 전달하면 됩니다.
|
||||
- import된 proto는 protoc가 자동으로 컴파일하고 goctl이 해결합니다.
|
||||
@@ -1,5 +1,7 @@
|
||||
# Example 02: Importing a Sibling Proto File
|
||||
|
||||
English | [中文](README-cn.md) | [한국어](README-ko.md)
|
||||
|
||||
This example demonstrates importing a proto file from the same directory.
|
||||
|
||||
## Proto Definition
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 示例 03：导入子目录中的 Proto 文件
|
||||
|
||||
[English](README.md) | 中文 | [한국어](README-ko.md)
|
||||
|
||||
本示例演示如何导入子目录中的 proto 文件。
|
||||
|
||||
## Proto 定义
|
||||
|
||||
84
tools/goctl/rpc/example/03-import-subdir/README-ko.md
Normal file
84
tools/goctl/rpc/example/03-import-subdir/README-ko.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# 예제 03: 하위 디렉터리의 proto import
|
||||
|
||||
[English](README.md) | [中文](README-cn.md) | 한국어
|
||||
|
||||
이 예제는 하위 디렉터리에 있는 proto 파일을 import하는 방법을 보여줍니다.
|
||||
|
||||
## proto 정의
|
||||
|
||||
두 proto 파일은 **서로 다른** `go_package` 값을 사용합니다.
|
||||
|
||||
- `order.proto` — `OrderService`를 정의하고 `common/types.proto`를 import합니다.
|
||||
|
||||
```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`를 import합니다.
|
||||
|
||||
```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`를 import합니다.
|
||||
- import된 proto의 `go_package`가 다르면 goctl은 패키지 간 import를 자동으로 생성합니다.
|
||||
- `-I .` 플래그는 protoc에 현재 디렉터리부터 검색하라고 알려주어 `common/types.proto`를 찾을 수 있게 합니다.
|
||||
@@ -1,5 +1,7 @@
|
||||
# Example 03: Importing Proto from a Subdirectory
|
||||
|
||||
English | [中文](README-cn.md) | [한국어](README-ko.md)
|
||||
|
||||
This example demonstrates importing a proto file from a subdirectory.
|
||||
|
||||
## Proto Definition
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 示例 04：传递性导入
|
||||
|
||||
[English](README.md) | 中文 | [한국어](README-ko.md)
|
||||
|
||||
本示例演示 proto 的传递性导入，即 A 导入 B，B 导入 C。
|
||||
|
||||
## Proto 定义
|
||||
@@ -65,7 +67,7 @@ output/
|
||||
|
||||
## 要点说明
|
||||
|
||||
- 三个 proto 文件（`base.proto` → `middleware.proto` → `main.proto`）形成传递导入链。
|
||||
- 三个 proto 文件（`main.proto` → `middleware.proto` → `base.proto`）形成传递导入链。
|
||||
- goctl 自动递归解析所有传递导入。
|
||||
- 三个文件共享相同的 `go_package = "example.com/demo/pb"`。
|
||||
- 只需指定入口 proto 文件，goctl 和 protoc 会自动处理其余部分。
|
||||
|
||||
74
tools/goctl/rpc/example/04-transitive-import/README-ko.md
Normal file
74
tools/goctl/rpc/example/04-transitive-import/README-ko.md
Normal file
@@ -0,0 +1,74 @@
|
||||
# 예제 04: 전이 import
|
||||
|
||||
[English](README.md) | [中文](README-cn.md) | 한국어
|
||||
|
||||
이 예제는 A가 B를 import하고 B가 C를 import하는 전이 proto import를 보여줍니다.
|
||||
|
||||
## proto 정의
|
||||
|
||||
세 proto 파일이 전이 import 체인을 이루며, 모두 동일한 `go_package`를 공유합니다.
|
||||
|
||||
```protobuf
|
||||
option go_package = "example.com/demo/pb";
|
||||
```
|
||||
|
||||
- `base.proto` — 계층 C: 기본 타입(`BaseResp`)을 정의합니다.
|
||||
- `middleware.proto` — 계층 B: `base.proto`를 import하고 `RequestMeta`를 정의합니다.
|
||||
- `main.proto` — 계층 A: `middleware.proto`를 import하고 `PingService`(진입점)를 정의합니다.
|
||||
|
||||
import 체인: `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 파일(`main.proto` → `middleware.proto` → `base.proto`)이 전이 import 체인을 이룹니다.
|
||||
- goctl은 모든 전이 import를 자동으로 재귀 해결합니다.
|
||||
- 세 파일 모두 동일한 `go_package = "example.com/demo/pb"`를 공유합니다.
|
||||
- 진입 proto 파일만 지정하면 됩니다. 나머지는 goctl과 protoc가 처리합니다.
|
||||
- 순환 import는 감지되며 오류가 발생합니다(protoc 동작과 동일).
|
||||
@@ -1,5 +1,7 @@
|
||||
# Example 04: Transitive Imports
|
||||
|
||||
English | [中文](README-cn.md) | [한국어](README-ko.md)
|
||||
|
||||
This example demonstrates transitive proto imports, where A imports B and B imports C.
|
||||
|
||||
## Proto Definition
|
||||
@@ -65,7 +67,7 @@ output/
|
||||
|
||||
## Key Points
|
||||
|
||||
- Three proto files (`base.proto` → `middleware.proto` → `main.proto`) form a transitive import chain.
|
||||
- Three proto files (`main.proto` → `middleware.proto` → `base.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.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 示例 05：多服务模式（`--multiple`）
|
||||
|
||||
[English](README.md) | 中文 | [한국어](README-ko.md)
|
||||
|
||||
本示例演示从一个 proto 文件生成多个 RPC 服务。
|
||||
|
||||
## Proto 定义
|
||||
|
||||
82
tools/goctl/rpc/example/05-multiple-services/README-ko.md
Normal file
82
tools/goctl/rpc/example/05-multiple-services/README-ko.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# 예제 05: 다중 서비스(`--multiple`)
|
||||
|
||||
[English](README.md) | [中文](README-cn.md) | 한국어
|
||||
|
||||
이 예제는 하나의 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`를 공유합니다.
|
||||
@@ -1,5 +1,7 @@
|
||||
# Example 05: Multiple Services (`--multiple`)
|
||||
|
||||
English | [中文](README-cn.md) | [한국어](README-ko.md)
|
||||
|
||||
This example demonstrates generating multiple RPC services from a single proto file.
|
||||
|
||||
## Proto Definition
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# 示例 06：知名类型
|
||||
|
||||
本示例演示如何使用 Google protobuf 知名类型（`Timestamp`、`Duration`、`Any`）作为消息字段。
|
||||
[English](README.md) | 中文 | [한국어](README-ko.md)
|
||||
|
||||
本示例演示如何使用 Google protobuf 知名类型（`Timestamp`）作为消息字段。
|
||||
|
||||
## Proto 定义
|
||||
|
||||
@@ -60,6 +62,6 @@ output/
|
||||
|
||||
## 要点说明
|
||||
|
||||
- 使用 Google 知名类型（`google.protobuf.Timestamp`、`google.protobuf.Duration`、`google.protobuf.Any`）作为消息字段。
|
||||
- goctl 自动将知名类型映射到 Go 导入包（`timestamppb`、`durationpb`、`anypb` 等）。
|
||||
- 使用 Google 知名类型 `google.protobuf.Timestamp` 作为消息字段。
|
||||
- goctl 自动将知名类型映射到 Go 导入包；在本示例中，`Timestamp` 会映射到 `timestamppb`。
|
||||
- 如果 protoc 已正确安装，知名类型无需额外的 `--proto_path`。
|
||||
|
||||
67
tools/goctl/rpc/example/06-wellknown-types/README-ko.md
Normal file
67
tools/goctl/rpc/example/06-wellknown-types/README-ko.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# 예제 06: Google well-known types
|
||||
|
||||
[English](README.md) | [中文](README-cn.md) | 한국어
|
||||
|
||||
이 예제는 Google protobuf well-known type(`Timestamp`)을 메시지 필드로 사용하는 방법을 보여줍니다.
|
||||
|
||||
## proto 정의
|
||||
|
||||
`events.proto`는 `google.protobuf.Timestamp`를 메시지 필드 타입으로 사용합니다.
|
||||
|
||||
`go_package`는 전체 모듈 경로를 사용합니다.
|
||||
|
||||
```protobuf
|
||||
option go_package = "example.com/demo/pb";
|
||||
```
|
||||
|
||||
## 생성 명령
|
||||
|
||||
먼저 출력 디렉터리에 `go.mod`를 초기화합니다.
|
||||
|
||||
```bash
|
||||
mkdir -p output && cd output && go mod init example.com/demo && cd ..
|
||||
```
|
||||
|
||||
그런 다음 코드를 생성합니다.
|
||||
|
||||
```bash
|
||||
goctl rpc protoc events.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
|
||||
│ └── eventsvc.yaml
|
||||
├── eventservice
|
||||
│ └── eventservice.go
|
||||
├── eventsvc.go
|
||||
├── go.mod
|
||||
├── internal
|
||||
│ ├── config
|
||||
│ │ └── config.go
|
||||
│ ├── logic
|
||||
│ │ ├── createeventlogic.go
|
||||
│ │ └── listeventslogic.go
|
||||
│ ├── server
|
||||
│ │ └── eventserviceserver.go
|
||||
│ └── svc
|
||||
│ └── servicecontext.go
|
||||
└── pb
|
||||
├── events.pb.go
|
||||
└── events_grpc.pb.go
|
||||
```
|
||||
|
||||
## 핵심 사항
|
||||
|
||||
- Google well-known type인 `google.protobuf.Timestamp`를 메시지 필드로 사용합니다.
|
||||
- goctl은 well-known types를 Go import로 자동 매핑합니다. 이 예제에서는 `Timestamp`가 `timestamppb`로 매핑됩니다.
|
||||
- protoc가 올바르게 설치되어 있다면 well-known types에는 추가 `--proto_path`가 필요하지 않습니다.
|
||||
@@ -1,6 +1,8 @@
|
||||
# Example 06: Well-Known Types
|
||||
|
||||
This example demonstrates using Google protobuf well-known types (`Timestamp`, `Duration`, `Any`) as message fields.
|
||||
English | [中文](README-cn.md) | [한국어](README-ko.md)
|
||||
|
||||
This example demonstrates using a Google protobuf well-known type (`Timestamp`) as a message field.
|
||||
|
||||
## Proto Definition
|
||||
|
||||
@@ -60,6 +62,6 @@ output/
|
||||
|
||||
## Key Points
|
||||
|
||||
- Uses Google well-known types (`google.protobuf.Timestamp`, `google.protobuf.Duration`, `google.protobuf.Any`) as message fields.
|
||||
- goctl automatically maps well-known types to Go imports (`timestamppb`, `durationpb`, `anypb`, etc.).
|
||||
- Uses the Google well-known type `google.protobuf.Timestamp` as a message field.
|
||||
- goctl automatically maps well-known types to Go imports; in this example, `Timestamp` maps to `timestamppb`.
|
||||
- No extra `--proto_path` needed for well-known types if protoc is properly installed.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 示例 07：外部 Proto — 相同 `go_package`
|
||||
|
||||
[English](README.md) | 中文 | [한국어](README-ko.md)
|
||||
|
||||
本示例演示从外部目录导入 proto 文件，且两个文件共享**相同**的 `go_package`。
|
||||
|
||||
## Proto 定义
|
||||
@@ -18,7 +20,8 @@ option go_package = "example.com/demo/pb";
|
||||
│ └── ext.proto # 外部 proto（go_package = "example.com/demo/pb"）
|
||||
├── service.proto # 服务定义（go_package = "example.com/demo/pb"）
|
||||
├── README.md
|
||||
└── README-cn.md
|
||||
├── README-cn.md
|
||||
└── README-ko.md
|
||||
```
|
||||
|
||||
- `ext.proto` 位于独立目录（`ext_protos/`），但与 `service.proto` 有相同的 `go_package`。
|
||||
|
||||
@@ -0,0 +1,80 @@
|
||||
# 예제 07: 외부 proto — 동일한 `go_package`
|
||||
|
||||
[English](README.md) | [中文](README-cn.md) | 한국어
|
||||
|
||||
이 예제는 두 파일이 **동일한** `go_package`를 공유하는 외부 디렉터리의 proto 파일을 import하는 방법을 보여줍니다.
|
||||
|
||||
## proto 정의
|
||||
|
||||
`service.proto`와 `ext.proto`는 모두 동일한 `go_package`를 사용합니다.
|
||||
|
||||
```protobuf
|
||||
option go_package = "example.com/demo/pb";
|
||||
```
|
||||
|
||||
소스 레이아웃:
|
||||
|
||||
```
|
||||
07-external-proto-same-pkg/
|
||||
├── ext_protos
|
||||
│ └── ext.proto # 외부 proto (go_package = "example.com/demo/pb")
|
||||
├── service.proto # 서비스 정의 (go_package = "example.com/demo/pb")
|
||||
├── README.md
|
||||
├── README-cn.md
|
||||
└── README-ko.md
|
||||
```
|
||||
|
||||
- `ext.proto`는 별도 디렉터리(`ext_protos/`)에 있지만 `service.proto`와 동일한 `go_package`를 가집니다.
|
||||
- `service.proto`는 `ext.proto`를 import하고 `ext.ExtReq` / `ext.ExtReply`를 RPC 타입으로 사용합니다.
|
||||
|
||||
## 생성 명령
|
||||
|
||||
먼저 출력 디렉터리에 `go.mod`를 초기화합니다.
|
||||
|
||||
```bash
|
||||
mkdir -p output && cd output && go mod init example.com/demo && cd ..
|
||||
```
|
||||
|
||||
그런 다음 코드를 생성합니다(`-I ./ext_protos`에 주목하세요).
|
||||
|
||||
```bash
|
||||
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 ./ext_protos
|
||||
```
|
||||
|
||||
생성되는 디렉터리 구조:
|
||||
|
||||
```
|
||||
output/
|
||||
├── etc
|
||||
│ └── svc.yaml
|
||||
├── go.mod
|
||||
├── internal
|
||||
│ ├── config
|
||||
│ │ └── config.go
|
||||
│ ├── logic
|
||||
│ │ └── querylogic.go
|
||||
│ ├── server
|
||||
│ │ └── queryserviceserver.go
|
||||
│ └── svc
|
||||
│ └── servicecontext.go
|
||||
├── pb
|
||||
│ ├── ext.pb.go
|
||||
│ ├── service.pb.go
|
||||
│ └── service_grpc.pb.go
|
||||
├── queryservice
|
||||
│ └── queryservice.go
|
||||
└── svc.go
|
||||
```
|
||||
|
||||
## 핵심 사항
|
||||
|
||||
- `ext.proto`는 별도 디렉터리(`ext_protos/`)에 있지만 `service.proto`와 동일한 `go_package`를 가집니다.
|
||||
- 외부 디렉터리를 proto 검색 경로에 추가하려면 `-I ./ext_protos`를 사용합니다.
|
||||
- 외부 proto가 **동일한** `go_package`를 가지면 모든 타입이 하나의 Go 패키지로 병합되므로 패키지 간 import가 필요하지 않습니다.
|
||||
@@ -1,5 +1,7 @@
|
||||
# Example 07: External Proto — Same `go_package`
|
||||
|
||||
English | [中文](README-cn.md) | [한국어](README-ko.md)
|
||||
|
||||
This example demonstrates importing proto files from an external directory where both files share the **same** `go_package`.
|
||||
|
||||
## Proto Definition
|
||||
@@ -18,7 +20,8 @@ Source layout:
|
||||
│ └── ext.proto # External proto (go_package = "example.com/demo/pb")
|
||||
├── service.proto # Service definition (go_package = "example.com/demo/pb")
|
||||
├── README.md
|
||||
└── README-cn.md
|
||||
├── README-cn.md
|
||||
└── README-ko.md
|
||||
```
|
||||
|
||||
- `ext.proto` lives in a separate directory (`ext_protos/`), but has the same `go_package` as `service.proto`.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 示例 08：外部 Proto — 不同 `go_package`
|
||||
|
||||
[English](README.md) | 中文 | [한국어](README-ko.md)
|
||||
|
||||
本示例演示从外部目录导入 proto 文件，且文件具有**不同**的 `go_package` 值，需要在生成的 Go 代码中进行跨包导入。
|
||||
|
||||
## Proto 定义
|
||||
@@ -18,7 +20,8 @@ proto 文件使用不同的 `go_package` 值：
|
||||
│ └── types.proto # 外部 proto（go_package = "example.com/demo/pb/common"）
|
||||
├── service.proto # 服务定义（go_package = "example.com/demo/pb"）
|
||||
├── README.md
|
||||
└── README-cn.md
|
||||
├── README-cn.md
|
||||
└── README-ko.md
|
||||
```
|
||||
|
||||
- `types.proto` 的 `go_package = "example.com/demo/pb/common"` — **不同**的 Go 包。
|
||||
|
||||
@@ -0,0 +1,81 @@
|
||||
# 예제 08: 외부 proto — 다른 `go_package`
|
||||
|
||||
[English](README.md) | [中文](README-cn.md) | 한국어
|
||||
|
||||
이 예제는 파일들이 **서로 다른** `go_package` 값을 가져 생성된 Go 코드에 패키지 간 import가 필요한 외부 디렉터리의 proto 파일을 import하는 방법을 보여줍니다.
|
||||
|
||||
## proto 정의
|
||||
|
||||
proto 파일들은 서로 다른 `go_package` 값을 사용합니다.
|
||||
|
||||
- `service.proto`: `go_package = "example.com/demo/pb"`
|
||||
- `ext_protos/common/types.proto`: `go_package = "example.com/demo/pb/common"`
|
||||
|
||||
소스 레이아웃:
|
||||
|
||||
```
|
||||
08-external-proto-diff-pkg/
|
||||
├── ext_protos
|
||||
│ └── common
|
||||
│ └── types.proto # 외부 proto (go_package = "example.com/demo/pb/common")
|
||||
├── service.proto # 서비스 정의 (go_package = "example.com/demo/pb")
|
||||
├── README.md
|
||||
├── README-cn.md
|
||||
└── README-ko.md
|
||||
```
|
||||
|
||||
- `types.proto`는 `go_package = "example.com/demo/pb/common"`을 가지며, 이는 **다른** Go 패키지입니다.
|
||||
- `service.proto`는 `common.ExtReq` / `common.ExtReply`를 RPC 파라미터 타입으로 직접 사용합니다.
|
||||
|
||||
## 생성 명령
|
||||
|
||||
먼저 출력 디렉터리에 `go.mod`를 초기화합니다.
|
||||
|
||||
```bash
|
||||
mkdir -p output && cd output && go mod init example.com/demo && cd ..
|
||||
```
|
||||
|
||||
그런 다음 코드를 생성합니다(`-I ./ext_protos`에 주목하세요).
|
||||
|
||||
```bash
|
||||
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 ./ext_protos
|
||||
```
|
||||
|
||||
생성되는 디렉터리 구조:
|
||||
|
||||
```
|
||||
output/
|
||||
├── dataservice
|
||||
│ └── dataservice.go
|
||||
├── etc
|
||||
│ └── svc.yaml
|
||||
├── go.mod
|
||||
├── internal
|
||||
│ ├── config
|
||||
│ │ └── config.go
|
||||
│ ├── logic
|
||||
│ │ └── fetchlogic.go
|
||||
│ ├── server
|
||||
│ │ └── dataserviceserver.go
|
||||
│ └── svc
|
||||
│ └── servicecontext.go
|
||||
├── pb
|
||||
│ ├── common
|
||||
│ │ └── types.pb.go
|
||||
│ ├── service.pb.go
|
||||
│ └── service_grpc.pb.go
|
||||
└── svc.go
|
||||
```
|
||||
|
||||
## 핵심 사항
|
||||
|
||||
- 외부 proto가 **다른** `go_package`를 가지면 goctl은 패키지 간 Go import를 자동으로 생성합니다.
|
||||
- goctl은 import된 proto의 `go_package` 옵션을 파싱하여 proto `package` 이름(예: `common`)을 올바른 Go import 경로로 해결합니다.
|
||||
- `service.proto`는 `common.ExtReq` / `common.ExtReply`를 RPC 파라미터 타입으로 직접 사용합니다.
|
||||
@@ -1,5 +1,7 @@
|
||||
# Example 08: External Proto — Different `go_package`
|
||||
|
||||
English | [中文](README-cn.md) | [한국어](README-ko.md)
|
||||
|
||||
This example demonstrates importing proto files from an external directory where the files have **different** `go_package` values, requiring cross-package imports in the generated Go code.
|
||||
|
||||
## Proto Definition
|
||||
@@ -18,7 +20,8 @@ Source layout:
|
||||
│ └── types.proto # External proto (go_package = "example.com/demo/pb/common")
|
||||
├── service.proto # Service definition (go_package = "example.com/demo/pb")
|
||||
├── README.md
|
||||
└── README-cn.md
|
||||
├── README-cn.md
|
||||
└── README-ko.md
|
||||
```
|
||||
|
||||
- `types.proto` has `go_package = "example.com/demo/pb/common"` — a **different** Go package.
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
# 示例 09：Google 类型作为 RPC 参数
|
||||
# 示例 09：Google 知名类型作为 RPC 参数
|
||||
|
||||
[English](README.md) | 中文 | [한국어](README-ko.md)
|
||||
|
||||
本示例演示将 Google protobuf 知名类型**直接**用作 RPC 请求或响应类型（而不仅仅是消息字段）。
|
||||
|
||||
|
||||
67
tools/goctl/rpc/example/09-google-types-as-rpc/README-ko.md
Normal file
67
tools/goctl/rpc/example/09-google-types-as-rpc/README-ko.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# 예제 09: RPC 파라미터로 Google well-known types 사용
|
||||
|
||||
[English](README.md) | [中文](README-cn.md) | 한국어
|
||||
|
||||
이 예제는 Google protobuf well-known types를 메시지 필드뿐 아니라 RPC 요청 또는 응답 타입으로 **직접** 사용하는 방법을 보여줍니다.
|
||||
|
||||
## proto 정의
|
||||
|
||||
`service.proto`는 `google.protobuf.Empty`와 `google.protobuf.Timestamp`를 RPC 요청/응답 타입으로 직접 사용합니다.
|
||||
|
||||
`go_package`는 전체 모듈 경로를 사용합니다.
|
||||
|
||||
```protobuf
|
||||
option go_package = "example.com/demo/pb";
|
||||
```
|
||||
|
||||
## 생성 명령
|
||||
|
||||
먼저 출력 디렉터리에 `go.mod`를 초기화합니다.
|
||||
|
||||
```bash
|
||||
mkdir -p output && cd output && go mod init example.com/demo && cd ..
|
||||
```
|
||||
|
||||
그런 다음 코드를 생성합니다.
|
||||
|
||||
```bash
|
||||
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 .
|
||||
```
|
||||
|
||||
생성되는 디렉터리 구조:
|
||||
|
||||
```
|
||||
output/
|
||||
├── etc
|
||||
│ └── healthsvc.yaml
|
||||
├── go.mod
|
||||
├── healthservice
|
||||
│ └── healthservice.go
|
||||
├── healthsvc.go
|
||||
├── internal
|
||||
│ ├── config
|
||||
│ │ └── config.go
|
||||
│ ├── logic
|
||||
│ │ ├── gettimelogic.go
|
||||
│ │ └── pinglogic.go
|
||||
│ ├── server
|
||||
│ │ └── healthserviceserver.go
|
||||
│ └── svc
|
||||
│ └── servicecontext.go
|
||||
└── pb
|
||||
├── service.pb.go
|
||||
└── service_grpc.pb.go
|
||||
```
|
||||
|
||||
## 핵심 사항
|
||||
|
||||
- Google well-known types(`google.protobuf.Empty`, `google.protobuf.Timestamp`)를 메시지 필드뿐 아니라 RPC 요청/응답 타입으로 직접 사용합니다.
|
||||
- goctl은 이를 Go 타입(`emptypb.Empty`, `timestamppb.Timestamp`)으로 올바르게 매핑하고 적절한 import를 생성합니다.
|
||||
- well-known types를 메시지 필드로 사용하는 예제 06과는 다릅니다.
|
||||
@@ -1,4 +1,6 @@
|
||||
# Example 09: Google Types as RPC Parameters
|
||||
# Example 09: Google Well-Known Types as RPC Parameters
|
||||
|
||||
English | [中文](README-cn.md) | [한국어](README-ko.md)
|
||||
|
||||
This example demonstrates using Google protobuf well-known types **directly** as RPC request or response types (not just as message fields).
|
||||
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 示例 10：流式 RPC
|
||||
|
||||
[English](README.md) | 中文 | [한국어](README-ko.md)
|
||||
|
||||
本示例演示 gRPC 的三种流式通信模式：服务端流、客户端流和双向流。
|
||||
|
||||
## Proto 定义
|
||||
@@ -63,4 +65,4 @@ output/
|
||||
|
||||
- 支持三种流式模式：服务端流（响应带 `stream`）、客户端流（请求带 `stream`）和双向流（两端都带 `stream`）。
|
||||
- goctl 为每个流式 RPC 方法生成独立的逻辑文件。
|
||||
- 流式客户端代码不会自动生成，需直接使用 gRPC 客户端。
|
||||
- goctl 会生成流式客户端包装方法；请使用返回的 gRPC stream 发送和接收消息。
|
||||
|
||||
68
tools/goctl/rpc/example/10-streaming/README-ko.md
Normal file
68
tools/goctl/rpc/example/10-streaming/README-ko.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# 예제 10: 스트리밍 RPC
|
||||
|
||||
[English](README.md) | [中文](README-cn.md) | 한국어
|
||||
|
||||
이 예제는 서버 스트리밍, 클라이언트 스트리밍, 양방향 스트리밍이라는 세 가지 gRPC 스트리밍 패턴을 모두 보여줍니다.
|
||||
|
||||
## proto 정의
|
||||
|
||||
`stream.proto`는 각 스트리밍 패턴을 보여주는 세 개의 RPC 메서드를 정의합니다.
|
||||
|
||||
`go_package`는 전체 모듈 경로를 사용합니다.
|
||||
|
||||
```protobuf
|
||||
option go_package = "example.com/demo/pb";
|
||||
```
|
||||
|
||||
## 생성 명령
|
||||
|
||||
먼저 출력 디렉터리에 `go.mod`를 초기화합니다.
|
||||
|
||||
```bash
|
||||
mkdir -p output && cd output && go mod init example.com/demo && cd ..
|
||||
```
|
||||
|
||||
그런 다음 코드를 생성합니다.
|
||||
|
||||
```bash
|
||||
goctl rpc protoc stream.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
|
||||
│ └── streamsvc.yaml
|
||||
├── go.mod
|
||||
├── internal
|
||||
│ ├── config
|
||||
│ │ └── config.go
|
||||
│ ├── logic
|
||||
│ │ ├── bidistreamlogic.go
|
||||
│ │ ├── clientstreamlogic.go
|
||||
│ │ └── serverstreamlogic.go
|
||||
│ ├── server
|
||||
│ │ └── streamserviceserver.go
|
||||
│ └── svc
|
||||
│ └── servicecontext.go
|
||||
├── pb
|
||||
│ ├── stream.pb.go
|
||||
│ └── stream_grpc.pb.go
|
||||
├── streamservice
|
||||
│ └── streamservice.go
|
||||
└── streamsvc.go
|
||||
```
|
||||
|
||||
## 핵심 사항
|
||||
|
||||
- 세 가지 스트리밍 패턴을 지원합니다. 서버 스트리밍(응답에 `stream`), 클라이언트 스트리밍(요청에 `stream`), 양방향 스트리밍(양쪽 모두 `stream`).
|
||||
- goctl은 각 스트리밍 RPC 메서드마다 별도의 logic 파일을 생성합니다.
|
||||
- goctl은 스트리밍 클라이언트 래퍼 메서드를 생성합니다. 반환된 gRPC stream을 사용해 메시지를 송수신하세요.
|
||||
@@ -1,5 +1,7 @@
|
||||
# Example 10: Streaming RPC
|
||||
|
||||
English | [中文](README-cn.md) | [한국어](README-ko.md)
|
||||
|
||||
This example demonstrates all three gRPC streaming patterns: server streaming, client streaming, and bidirectional streaming.
|
||||
|
||||
## Proto Definition
|
||||
@@ -63,4 +65,4 @@ output/
|
||||
|
||||
- Supports three streaming patterns: server streaming (`stream` on response), client streaming (`stream` on request), and bidirectional streaming (`stream` on both).
|
||||
- goctl generates separate logic files for each streaming RPC method.
|
||||
- Streaming client code is not auto-generated; use the gRPC client directly.
|
||||
- goctl generates streaming client wrapper methods; use the returned gRPC stream to send and receive messages.
|
||||
|
||||
47
tools/goctl/rpc/example/README-cn.md
Normal file
47
tools/goctl/rpc/example/README-cn.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# RPC 示例
|
||||
|
||||
[English](README.md) | 中文 | [한국어](README-ko.md)
|
||||
|
||||
本目录包含所有 `goctl rpc` 代码生成场景的完整示例。
|
||||
|
||||
每个示例包含：
|
||||
- `.proto` 源文件
|
||||
- `README.md`（英文）、`README-cn.md`（中文）和 `README-ko.md`（한국어）文档
|
||||
|
||||
## 示例列表
|
||||
|
||||
| # | 目录 | 场景 | 关键标志 |
|
||||
|---|------|------|---------|
|
||||
| 01 | [01-basic](01-basic/) | 基础单服务，无导入 | — |
|
||||
| 02 | [02-import-sibling](02-import-sibling/) | 导入同级 proto 文件 | `--proto_path=.` |
|
||||
| 03 | [03-import-subdir](03-import-subdir/) | 导入子目录中的 proto | `--proto_path=.` |
|
||||
| 04 | [04-transitive-import](04-transitive-import/) | 传递性导入（A → B → C） | `--proto_path=.` |
|
||||
| 05 | [05-multiple-services](05-multiple-services/) | 单 proto 多服务 | `--multiple` |
|
||||
| 06 | [06-wellknown-types](06-wellknown-types/) | 消息中使用 Google 标准类型 | — |
|
||||
| 07 | [07-external-proto-same-pkg](07-external-proto-same-pkg/) | 外部 proto，相同 `go_package` | `-I ./ext_protos` |
|
||||
| 08 | [08-external-proto-diff-pkg](08-external-proto-diff-pkg/) | 外部 proto，不同 `go_package` | `-I ./ext_protos` |
|
||||
| 09 | [09-google-types-as-rpc](09-google-types-as-rpc/) | Google 标准类型作为 RPC 参数 | — |
|
||||
| 10 | [10-streaming](10-streaming/) | 服务端/客户端/双向流 | — |
|
||||
|
||||
## 前置条件
|
||||
|
||||
- [Go](https://go.dev/) 1.22+
|
||||
- [protoc](https://github.com/protocolbuffers/protobuf/releases)（Protocol Buffers 编译器）
|
||||
- [protoc-gen-go](https://pkg.go.dev/google.golang.org/protobuf/cmd/protoc-gen-go) 和 [protoc-gen-go-grpc](https://pkg.go.dev/google.golang.org/grpc/cmd/protoc-gen-go-grpc)
|
||||
- [goctl](https://github.com/zeromicro/go-zero/tree/master/tools/goctl)
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
# 安装 protoc 插件
|
||||
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
|
||||
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
|
||||
|
||||
# 试试基础示例
|
||||
cd 01-basic
|
||||
mkdir -p output && cd output && go mod init example.com/demo && cd ..
|
||||
goctl rpc protoc greeter.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 .
|
||||
```
|
||||
47
tools/goctl/rpc/example/README-ko.md
Normal file
47
tools/goctl/rpc/example/README-ko.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# RPC 예제
|
||||
|
||||
[English](README.md) | [中文](README-cn.md) | 한국어
|
||||
|
||||
이 디렉터리에는 모든 `goctl rpc` 코드 생성 시나리오에 대한 완전한 예제가 포함되어 있습니다.
|
||||
|
||||
각 예제에는 다음이 포함됩니다.
|
||||
- `.proto` 소스 파일
|
||||
- `README.md`(영어), `README-cn.md`(중국어), `README-ko.md`(한국어) 문서
|
||||
|
||||
## 예제
|
||||
|
||||
| # | 디렉터리 | 시나리오 | 주요 플래그 |
|
||||
|---|-----------|----------|-----------|
|
||||
| 01 | [01-basic](01-basic/) | 기본 단일 서비스, import 없음 | — |
|
||||
| 02 | [02-import-sibling](02-import-sibling/) | 같은 디렉터리의 proto 파일 import | `--proto_path=.` |
|
||||
| 03 | [03-import-subdir](03-import-subdir/) | 하위 디렉터리의 proto import | `--proto_path=.` |
|
||||
| 04 | [04-transitive-import](04-transitive-import/) | 전이 import(A → B → C) | `--proto_path=.` |
|
||||
| 05 | [05-multiple-services](05-multiple-services/) | 하나의 proto에 여러 서비스 | `--multiple` |
|
||||
| 06 | [06-wellknown-types](06-wellknown-types/) | 메시지에서 Google well-known types 사용 | — |
|
||||
| 07 | [07-external-proto-same-pkg](07-external-proto-same-pkg/) | 외부 proto, 동일한 `go_package` | `-I ./ext_protos` |
|
||||
| 08 | [08-external-proto-diff-pkg](08-external-proto-diff-pkg/) | 외부 proto, 다른 `go_package` | `-I ./ext_protos` |
|
||||
| 09 | [09-google-types-as-rpc](09-google-types-as-rpc/) | RPC 파라미터로 Google well-known types 사용 | — |
|
||||
| 10 | [10-streaming](10-streaming/) | 서버/클라이언트/양방향 스트리밍 | — |
|
||||
|
||||
## 사전 요구 사항
|
||||
|
||||
- [Go](https://go.dev/) 1.22+
|
||||
- [protoc](https://github.com/protocolbuffers/protobuf/releases) (Protocol Buffers 컴파일러)
|
||||
- [protoc-gen-go](https://pkg.go.dev/google.golang.org/protobuf/cmd/protoc-gen-go) 및 [protoc-gen-go-grpc](https://pkg.go.dev/google.golang.org/grpc/cmd/protoc-gen-go-grpc)
|
||||
- [goctl](https://github.com/zeromicro/go-zero/tree/master/tools/goctl)
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
```bash
|
||||
# protoc 플러그인 설치
|
||||
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
|
||||
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
|
||||
|
||||
# 기본 예제 실행
|
||||
cd 01-basic
|
||||
mkdir -p output && cd output && go mod init example.com/demo && cd ..
|
||||
goctl rpc protoc greeter.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 .
|
||||
```
|
||||
@@ -1,10 +1,12 @@
|
||||
# RPC Examples
|
||||
|
||||
English | [中文](README-cn.md) | [한국어](README-ko.md)
|
||||
|
||||
This directory contains complete examples for all `goctl rpc` code generation scenarios.
|
||||
|
||||
Each example includes:
|
||||
- `.proto` source files
|
||||
- `README.md` (English) and `README-cn.md` (中文) documentation
|
||||
- `README.md` (English), `README-cn.md` (中文), and `README-ko.md` (한국어) documentation
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -15,10 +17,10 @@ Each example includes:
|
||||
| 03 | [03-import-subdir](03-import-subdir/) | Import proto from subdirectory | `--proto_path=.` |
|
||||
| 04 | [04-transitive-import](04-transitive-import/) | Transitive imports (A → B → C) | `--proto_path=.` |
|
||||
| 05 | [05-multiple-services](05-multiple-services/) | Multiple services in one proto | `--multiple` |
|
||||
| 06 | [06-wellknown-types](06-wellknown-types/) | Google well-known types in messages | `--proto_path=$PROTOC_INCLUDE` |
|
||||
| 06 | [06-wellknown-types](06-wellknown-types/) | Google well-known types in messages | — |
|
||||
| 07 | [07-external-proto-same-pkg](07-external-proto-same-pkg/) | External proto, same `go_package` | `-I ./ext_protos` |
|
||||
| 08 | [08-external-proto-diff-pkg](08-external-proto-diff-pkg/) | External proto, different `go_package` | `-I ./ext_protos` |
|
||||
| 09 | [09-google-types-as-rpc](09-google-types-as-rpc/) | Google types as RPC parameters | `--proto_path=$PROTOC_INCLUDE` |
|
||||
| 09 | [09-google-types-as-rpc](09-google-types-as-rpc/) | Google well-known types as RPC parameters | — |
|
||||
| 10 | [10-streaming](10-streaming/) | Server/client/bidirectional streaming | — |
|
||||
|
||||
## Prerequisites
|
||||
@@ -43,51 +45,3 @@ goctl rpc protoc greeter.proto \
|
||||
--go_opt=module=example.com/demo --go-grpc_opt=module=example.com/demo \
|
||||
--module=example.com/demo -I .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# RPC 示例
|
||||
|
||||
本目录包含所有 `goctl rpc` 代码生成场景的完整示例。
|
||||
|
||||
每个示例包含：
|
||||
- `.proto` 源文件
|
||||
- `README.md`（英文）和 `README-cn.md`（中文）文档
|
||||
|
||||
## 示例列表
|
||||
|
||||
| # | 目录 | 场景 | 关键标志 |
|
||||
|---|------|------|---------|
|
||||
| 01 | [01-basic](01-basic/) | 基础单服务，无导入 | — |
|
||||
| 02 | [02-import-sibling](02-import-sibling/) | 导入同级 proto 文件 | `--proto_path=.` |
|
||||
| 03 | [03-import-subdir](03-import-subdir/) | 导入子目录中的 proto | `--proto_path=.` |
|
||||
| 04 | [04-transitive-import](04-transitive-import/) | 传递性导入（A → B → C） | `--proto_path=.` |
|
||||
| 05 | [05-multiple-services](05-multiple-services/) | 单 proto 多服务 | `--multiple` |
|
||||
| 06 | [06-wellknown-types](06-wellknown-types/) | 消息中使用 Google 标准类型 | `--proto_path=$PROTOC_INCLUDE` |
|
||||
| 07 | [07-external-proto-same-pkg](07-external-proto-same-pkg/) | 外部 proto，相同 `go_package` | `-I ./ext_protos` |
|
||||
| 08 | [08-external-proto-diff-pkg](08-external-proto-diff-pkg/) | 外部 proto，不同 `go_package` | `-I ./ext_protos` |
|
||||
| 09 | [09-google-types-as-rpc](09-google-types-as-rpc/) | Google 类型作为 RPC 参数 | `--proto_path=$PROTOC_INCLUDE` |
|
||||
| 10 | [10-streaming](10-streaming/) | 服务端/客户端/双向流 | — |
|
||||
|
||||
## 前置条件
|
||||
|
||||
- [Go](https://go.dev/) 1.22+
|
||||
- [protoc](https://github.com/protocolbuffers/protobuf/releases)（Protocol Buffers 编译器）
|
||||
- [protoc-gen-go](https://pkg.go.dev/google.golang.org/protobuf/cmd/protoc-gen-go) 和 [protoc-gen-go-grpc](https://pkg.go.dev/google.golang.org/grpc/cmd/protoc-gen-go-grpc)
|
||||
- [goctl](https://github.com/zeromicro/go-zero/tree/master/tools/goctl)
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
# 安装 protoc 插件
|
||||
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
|
||||
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
|
||||
|
||||
# 试试基础示例
|
||||
cd 01-basic
|
||||
mkdir -p output && cd output && go mod init example.com/demo && cd ..
|
||||
goctl rpc protoc greeter.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 .
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user