diff --git a/core/logx/readme-cn.md b/core/logx/readme-cn.md index 4f3d21c27d35..fb9165c037ea 100644 --- a/core/logx/readme-cn.md +++ b/core/logx/readme-cn.md @@ -2,7 +2,7 @@ # logx -[English](readme.md) | 简体中文 +[English](readme.md) | 简体中文 | [한국어](readme-ko.md) ## logx 配置 diff --git a/core/logx/readme-ko.md b/core/logx/readme-ko.md new file mode 100644 index 000000000000..bb4ea2f5901d --- /dev/null +++ b/core/logx/readme-ko.md @@ -0,0 +1,205 @@ + + +# logx + +[English](readme.md) | [简体中文](readme-cn.md) | 한국어 + +## logx 설정 + +```go +type LogConf struct { + ServiceName string `json:",optional"` + Mode string `json:",default=console,options=[console,file,volume]"` + Encoding string `json:",default=json,options=[json,plain]"` + TimeFormat string `json:",optional"` + Path string `json:",default=logs"` + Level string `json:",default=info,options=[info,error,severe]"` + Compress bool `json:",optional"` + KeepDays int `json:",optional"` + StackCooldownMillis int `json:",default=100"` + MaxBackups int `json:",default=0"` + MaxSize int `json:",default=0"` + Rotation string `json:",default=daily,options=[daily,size]"` +} +``` + +- `ServiceName`: 서비스 이름을 설정합니다. 선택 사항입니다. `volume` 모드에서는 이 이름이 로그 파일 생성에 사용됩니다. `rest/zrpc` 서비스에서는 이름이 `rest` 또는 `zrpc`의 이름으로 자동 설정됩니다. +- `Mode`: 로그 출력 모드입니다. 기본값은 `console`입니다. + - `console` 모드는 로그를 `stdout/stderr`에 씁니다. + - `file` 모드는 `Path`로 지정한 파일에 로그를 씁니다. + - `volume` 모드는 docker에서 사용하며, 마운트된 볼륨에 로그를 씁니다. +- `Encoding`: 로그 인코딩 방식을 나타냅니다. 기본값은 `json`입니다. + - `json` 모드는 로그를 json 형식으로 씁니다. + - `plain` 모드는 터미널 색상이 활성화된 일반 텍스트로 로그를 씁니다. +- `TimeFormat`: 시간 형식을 사용자 지정합니다. 선택 사항입니다. 기본값은 `2006-01-02T15:04:05.000Z07:00`입니다. +- `Path`: 로그 경로를 설정합니다. 기본값은 `logs`입니다. +- `Level`: 로그를 필터링할 로깅 레벨입니다. 기본값은 `info`입니다. + - `info`: 모든 로그가 기록됩니다. + - `error`: `info` 로그가 억제됩니다. + - `severe`: `info`와 `error` 로그가 억제되고 `severe` 로그만 기록됩니다. +- `Compress`: 로그 파일 압축 여부입니다. `file` 모드에서만 동작합니다. +- `KeepDays`: 로그 파일을 보관할 일수입니다. 지정한 일수가 지나면 오래된 파일이 자동으로 삭제됩니다. `console` 모드에는 영향을 주지 않습니다. +- `StackCooldownMillis`: 스택 트레이스를 다시 기록하기까지의 밀리초입니다. 스택 트레이스 로그 폭주를 방지하는 데 사용됩니다. +- `MaxBackups`: 보관할 백업 로그 파일 개수입니다. 0은 모든 파일을 영구 보관한다는 의미입니다. `Rotation`이 `size`일 때만 적용됩니다. 참고: `KeepDays` 옵션의 우선순위가 더 높습니다. `MaxBackups`가 0이더라도 `KeepDays` 제한에 도달하면 로그 파일은 삭제됩니다. +- `MaxSize`: 현재 기록 중인 로그 파일이 차지할 수 있는 최대 공간입니다. 0은 제한 없음을 의미합니다. 단위는 `MB`입니다. `Rotation`이 `size`일 때만 적용됩니다. +- `Rotation`: 로그 로테이션 규칙의 유형입니다. 기본값은 `daily`입니다. + - `daily`: 날짜 단위로 로그를 회전합니다. + - `size`: 로그 크기 단위로 로그를 회전합니다. + +## 로깅 메서드 + +```go +type Logger interface { + // Error logs a message at error level. + Error(...any) + // Errorf logs a message at error level. + Errorf(string, ...any) + // Errorv logs a message at error level. + Errorv(any) + // Errorw logs a message at error level. + Errorw(string, ...LogField) + // Info logs a message at info level. + Info(...any) + // Infof logs a message at info level. + Infof(string, ...any) + // Infov logs a message at info level. + Infov(any) + // Infow logs a message at info level. + Infow(string, ...LogField) + // Slow logs a message at slow level. + Slow(...any) + // Slowf logs a message at slow level. + Slowf(string, ...any) + // Slowv logs a message at slow level. + Slowv(any) + // Sloww logs a message at slow level. + Sloww(string, ...LogField) + // WithContext returns a new logger with the given context. + WithContext(context.Context) Logger + // WithDuration returns a new logger with the given duration. + WithDuration(time.Duration) Logger +} +``` + +- `Error`, `Info`, `Slow`: `fmt.Sprint(…)`처럼 모든 종류의 메시지를 로그에 씁니다. +- `Errorf`, `Infof`, `Slowf`: 지정한 형식으로 메시지를 로그에 씁니다. +- `Errorv`, `Infov`, `Slowv`: 모든 종류의 메시지를 json 마샬링으로 인코딩해 로그에 씁니다. +- `Errorw`, `Infow`, `Sloww`: 지정한 `key:value` 필드와 함께 문자열 메시지를 씁니다. +- `WithContext`: 지정한 ctx를 로그 메시지에 주입합니다. 일반적으로 `trace-id`와 `span-id`를 기록하는 데 사용됩니다. +- `WithDuration`: 경과 시간을 `duration` 키로 로그 메시지에 씁니다. + +## 타사 로깅 라이브러리와 통합 + +- zap + - 구현: [https://github.com/zeromicro/zero-contrib/blob/main/logx/zapx/zap.go](https://github.com/zeromicro/zero-contrib/blob/main/logx/zapx/zap.go) + - 사용 예시: [https://github.com/zeromicro/zero-examples/blob/main/logx/zaplog/main.go](https://github.com/zeromicro/zero-examples/blob/main/logx/zaplog/main.go) +- logrus + - 구현: [https://github.com/zeromicro/zero-contrib/blob/main/logx/logrusx/logrus.go](https://github.com/zeromicro/zero-contrib/blob/main/logx/logrusx/logrus.go) + - 사용 예시: [https://github.com/zeromicro/zero-examples/blob/main/logx/logrus/main.go](https://github.com/zeromicro/zero-examples/blob/main/logx/logrus/main.go) + +더 많은 라이브러리는 직접 구현한 뒤 [https://github.com/zeromicro/zero-contrib](https://github.com/zeromicro/zero-contrib)에 PR을 보내주세요. + +## 특정 저장소에 로그 쓰기 + +`logx`는 로그를 원하는 저장소에 쓸 수 있도록 사용자 지정할 수 있는 두 인터페이스를 정의합니다. + +- `logx.NewWriter(w io.Writer)` +- `logx.SetWriter(writer logx.Writer)` + +예를 들어 로그를 콘솔이나 파일 대신 kafka에 쓰고 싶다면 아래처럼 할 수 있습니다. + +```go +type KafkaWriter struct { + Pusher *kq.Pusher +} + +func NewKafkaWriter(pusher *kq.Pusher) *KafkaWriter { + return &KafkaWriter{ + Pusher: pusher, + } +} + +func (w *KafkaWriter) Write(p []byte) (n int, err error) { + // writing log with newlines, trim them. + if err := w.Pusher.Push(strings.TrimSpace(string(p))); err != nil { + return 0, err + } + + return len(p), nil +} + +func main() { + pusher := kq.NewPusher([]string{"localhost:9092"}, "go-zero") + defer pusher.Close() + + writer := logx.NewWriter(NewKafkaWriter(pusher)) + logx.SetWriter(writer) + + // more code +} +``` + +전체 코드: [https://github.com/zeromicro/zero-examples/blob/main/logx/tokafka/main.go](https://github.com/zeromicro/zero-examples/blob/main/logx/tokafka/main.go) + +## 민감한 필드 필터링 + +`password` 필드가 로그에 기록되지 않도록 하려면 아래처럼 할 수 있습니다. + +```go +type ( + Message struct { + Name string + Password string + Message string + } + + SensitiveLogger struct { + logx.Writer + } +) + +func NewSensitiveLogger(writer logx.Writer) *SensitiveLogger { + return &SensitiveLogger{ + Writer: writer, + } +} + +func (l *SensitiveLogger) Info(msg any, fields ...logx.LogField) { + if m, ok := msg.(Message); ok { + l.Writer.Info(Message{ + Name: m.Name, + Password: "******", + Message: m.Message, + }, fields...) + } else { + l.Writer.Info(msg, fields...) + } +} + +func main() { + // setup logx to make sure originalWriter not nil, + // the injected writer is only for filtering, like a middleware. + + originalWriter := logx.Reset() + writer := NewSensitiveLogger(originalWriter) + logx.SetWriter(writer) + + logx.Infov(Message{ + Name: "foo", + Password: "shouldNotAppear", + Message: "bar", + }) + + // more code +} +``` + +전체 코드: [https://github.com/zeromicro/zero-examples/blob/main/logx/filterfields/main.go](https://github.com/zeromicro/zero-examples/blob/main/logx/filterfields/main.go) + +## 더 많은 예제 + +[https://github.com/zeromicro/zero-examples/tree/main/logx](https://github.com/zeromicro/zero-examples/tree/main/logx) + +## 별을 눌러주세요! ⭐ + +이 프로젝트가 마음에 들거나 학습 또는 자체 솔루션을 시작하는 데 사용 중이라면 star를 눌러주세요. 감사합니다! diff --git a/core/logx/readme.md b/core/logx/readme.md index 1d303ea0bd5d..8dad5fca867d 100644 --- a/core/logx/readme.md +++ b/core/logx/readme.md @@ -2,7 +2,7 @@ # logx -English | [简体中文](readme-cn.md) +English | [简体中文](readme-cn.md) | [한국어](readme-ko.md) ## logx configurations diff --git a/core/mr/readme-cn.md b/core/mr/readme-cn.md index 7aaf300629f3..938858722df1 100644 --- a/core/mr/readme-cn.md +++ b/core/mr/readme-cn.md @@ -1,10 +1,10 @@ # mapreduce -[English](readme.md) | 简体中文 +[English](readme.md) | 简体中文 | [한국어](readme-ko.md) ## 为什么需要 MapReduce -在实际的业务场景中我们常常需要从不同的 rpc 服务中获取相应属性来组装成复杂对象。 +在实际的业务场景中我们常常需要从不同的 RPC 服务中获取相应属性来组装成复杂对象。 比如要查询商品详情： @@ -13,9 +13,9 @@ 3. 价格服务-查询价格属性 4. 营销服务-查询营销属性 -如果是串行调用的话响应时间会随着 rpc 调用次数呈线性增长，所以我们要优化性能一般会将串行改并行。 +如果是串行调用的话响应时间会随着 RPC 调用次数呈线性增长，所以我们要优化性能一般会将串行改并行。 -简单的场景下使用 `WaitGroup` 也能够满足需求，但是如果我们需要对 rpc 调用返回的数据进行校验、数据加工转换、数据汇总呢？继续使用 `WaitGroup` 就有点力不从心了，go 的官方库中并没有这种工具（java 中提供了 CompleteFuture），我们依据 MapReduce 架构思想实现了进程内的数据批处理 MapReduce 并发工具类。 +简单的场景下使用 `WaitGroup` 也能够满足需求，但是如果我们需要对 RPC 调用返回的数据进行校验、数据加工转换、数据汇总呢？继续使用 `WaitGroup` 就有点力不从心了，go 的官方库中并没有这种工具（java 中提供了 CompletableFuture），我们依据 MapReduce 架构思想实现了进程内的数据批处理 MapReduce 并发工具类。 ## 设计思路 diff --git a/core/mr/readme-ko.md b/core/mr/readme-ko.md new file mode 100644 index 000000000000..16d08e93574d --- /dev/null +++ b/core/mr/readme-ko.md @@ -0,0 +1,89 @@ + + +# mapreduce + +[English](readme.md) | [简体中文](readme-cn.md) | 한국어 + +## MapReduce가 필요한 이유 + +실제 비즈니스 시나리오에서는 서로 다른 RPC 서비스에서 속성을 가져와 복잡한 객체를 조립해야 하는 경우가 많습니다. + +예를 들어 상품 상세 정보를 조회한다고 해봅시다. + +1. 상품 서비스 - 상품 속성 조회 +2. 재고 서비스 - 재고 속성 조회 +3. 가격 서비스 - 가격 속성 조회 +4. 마케팅 서비스 - 마케팅 속성 조회 + +직렬 호출이라면 RPC 호출 횟수에 따라 응답 시간이 선형적으로 증가하므로, 일반적으로 응답 시간을 최적화하기 위해 직렬 호출을 병렬 호출로 바꿉니다. + +단순한 시나리오에서는 `WaitGroup`만으로도 요구 사항을 충족할 수 있습니다. 하지만 RPC 호출이 반환한 데이터를 검증하거나, 데이터를 처리하거나, 데이터를 집계해야 한다면 어떻게 해야 할까요? Go 표준 라이브러리에는 이런 도구가 없습니다(Java에는 CompletableFuture가 제공됩니다). 그래서 우리는 MapReduce 아키텍처를 기반으로 프로세스 내부 데이터 배치 처리를 위한 MapReduce 동시성 도구를 구현했습니다. + +## 설계 아이디어 + +동시성 도구가 필요한 비즈니스 시나리오를 작성자의 관점에서 정리해봅시다. + +1. 상품 상세 조회: 여러 서비스를 동시에 호출해 상품 속성을 조합하고, 호출 오류가 발생하면 즉시 종료할 수 있어야 합니다. +2. 상품 상세 페이지에서 사용자 쿠폰 자동 추천: 쿠폰을 동시에 검증하고, 검증에 실패한 쿠폰은 자동으로 제외하며, 나머지를 모두 반환할 수 있어야 합니다. + +위 시나리오는 모두 입력 데이터를 처리한 뒤 정제된 데이터를 출력하는 과정입니다. 데이터 처리에는 아주 고전적인 비동기 패턴인 생산자-소비자 패턴이 있습니다. 따라서 데이터 배치 처리의 생명 주기를 추상화하면 대략 세 단계로 나눌 수 있습니다. + + + +1. 데이터 생성(generator) +2. 데이터 처리(mapper) +3. 데이터 집계(reducer) + +데이터 생성은 필수 단계이고, 데이터 처리와 데이터 집계는 선택 단계입니다. 데이터 생성과 처리는 동시 호출을 지원하며, 데이터 집계는 기본적으로 순수 메모리 작업이므로 단일 고루틴으로 처리할 수 있습니다. + +서로 다른 데이터 처리 단계가 서로 다른 고루틴에서 수행되므로, 고루틴 간 통신을 위해 채널을 사용하는 것이 자연스럽습니다. + + + +언제든 프로세스를 종료하려면 어떻게 해야 할까요? + +간단합니다. 고루틴에서 채널 또는 전달된 context의 완료 신호를 감시하면 됩니다. + +## 간단한 예시 + +동시성을 시뮬레이션하며 제곱합을 계산합니다. + +```go +package main + +import ( + "fmt" + "log" + + "github.com/zeromicro/go-zero/core/mr" +) + +func main() { + val, err := mr.MapReduce(func(source chan<- int) { + // generator + for i := 0; i < 10; i++ { + source <- i + } + }, func(i int, writer mr.Writer[int], cancel func(error)) { + // mapper + writer.Write(i * i) + }, func(pipe <-chan int, writer mr.Writer[int], cancel func(error)) { + // reducer + var sum int + for i := range pipe { + sum += i + } + writer.Write(sum) + }) + if err != nil { + log.Fatal(err) + } + fmt.Println("result:", val) +} +``` + +더 많은 예제: [https://github.com/zeromicro/zero-examples/tree/main/mapreduce](https://github.com/zeromicro/zero-examples/tree/main/mapreduce) + +## 별을 눌러주세요! ⭐ + +이 프로젝트가 마음에 들거나 학습 또는 자체 솔루션을 시작하는 데 사용 중이라면 star를 눌러주세요. 감사합니다! diff --git a/core/mr/readme.md b/core/mr/readme.md index 3bb916b530d4..378c5c28e2b2 100644 --- a/core/mr/readme.md +++ b/core/mr/readme.md @@ -2,11 +2,11 @@ # mapreduce -English | [简体中文](readme-cn.md) +English | [简体中文](readme-cn.md) | [한국어](readme-ko.md) ## Why MapReduce is needed -In practical business scenarios we often need to get the corresponding properties from different rpc services to assemble complex objects. +In practical business scenarios we often need to get the corresponding properties from different RPC services to assemble complex objects. For example, to query product details. @@ -15,9 +15,9 @@ For example, to query product details. 3. price service - query price attributes 4. marketing service - query marketing properties -If it is a serial call, the response time will increase linearly with the number of rpc calls, so we will generally change serial to parallel to optimize response time. +If it is a serial call, the response time will increase linearly with the number of RPC calls, so we will generally change serial to parallel to optimize response time. -Simple scenarios using `WaitGroup` can also meet the needs, but what if we need to check the data returned by the rpc call, data processing, data aggregation? The official go library does not have such a tool (CompleteFuture is provided in java), so we implemented an in-process data batching MapReduce concurrent tool based on the MapReduce architecture. +Simple scenarios using `WaitGroup` can also meet the needs, but what if we need to check the data returned by the RPC call, data processing, data aggregation? The official go library does not have such a tool (CompletableFuture is provided in java), so we implemented an in-process data batching MapReduce concurrent tool based on the MapReduce architecture. ## Design ideas diff --git a/readme-cn.md b/readme-cn.md index 7d40bd242b2a..67389d401837 100644 --- a/readme-cn.md +++ b/readme-cn.md @@ -4,7 +4,7 @@ ***缩短从需求到上线的距离*** -[English](readme.md) | 简体中文 +[English](readme.md) | 简体中文 | [한국어](readme-ko.md) [![Go Report Card](https://goreportcard.com/badge/github.com/zeromicro/go-zero)](https://goreportcard.com/report/github.com/zeromicro/go-zero) [![goproxy](https://goproxy.cn/stats/github.com/zeromicro/go-zero/badges/download-count.svg)](https://goproxy.cn/stats/github.com/zeromicro/go-zero/badges/download-count.svg) diff --git a/readme-ko.md b/readme-ko.md new file mode 100644 index 000000000000..1a0e392aa104 --- /dev/null +++ b/readme-ko.md @@ -0,0 +1,278 @@ +# go-zero +

+ +

+ +go-zero는 다양한 엔지니어링 모범 사례가 내장된 웹 및 RPC 프레임워크입니다. 회복 탄력성 설계로 트래픽이 많은 서비스의 안정성을 보장하기 위해 만들어졌으며, 수년 동안 수천만 사용자를 보유한 사이트에서 운영되어 왔습니다. + +
+ +[![codecov](https://codecov.io/gh/zeromicro/go-zero/branch/master/graph/badge.svg)](https://codecov.io/gh/zeromicro/go-zero) +[![Go Report Card](https://goreportcard.com/badge/github.com/zeromicro/go-zero)](https://goreportcard.com/report/github.com/zeromicro/go-zero) +[![Release](https://img.shields.io/github/v/release/zeromicro/go-zero.svg?style=flat-square)](https://github.com/zeromicro/go-zero) +[![Go Reference](https://pkg.go.dev/badge/github.com/zeromicro/go-zero.svg)](https://pkg.go.dev/github.com/zeromicro/go-zero) +[![Awesome Go](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/avelino/awesome-go) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Discord](https://img.shields.io/discord/794530774463414292?label=chat&logo=discord)](https://discord.gg/4JQvC5A4Fe) + +
+ + +## 🤷‍ go-zero란? +[English](readme.md) | [简体中文](readme-cn.md) | 한국어 + +zeromicro%2Fgo-zero | Trendshift +go-zero - A web & rpc framework written in Go. | Product Hunt + + +go-zero는 [CNCF Landscape](https://landscape.cncf.io/?selected=go-zero)에 등재된, 다양한 엔지니어링 모범 사례가 내장된 웹 및 RPC 프레임워크입니다. 회복 탄력성 설계로 트래픽이 많은 서비스의 안정성을 보장하기 위해 만들어졌으며, 수년 동안 수천만 사용자를 보유한 사이트에서 운영되어 왔습니다. + +go-zero에는 간단한 API 설명 문법과 `goctl`이라는 코드 생성 도구가 포함되어 있습니다. `goctl`을 사용하면 .api 파일에서 Go, iOS, Android, Kotlin, Dart, TypeScript, JavaScript 코드를 생성할 수 있습니다. + +#### go-zero의 장점: + +* 수천만 일간 활성 사용자를 처리하는 서비스의 안정성을 높입니다. +* 체인형 타임아웃 제어, 동시성 제어, 속도 제한, 적응형 서킷 브레이커, 적응형 로드 셰딩이 내장되어 있으며, 별도 설정 없이도 사용할 수 있습니다. +* 내장 미들웨어를 기존 프레임워크에 통합할 수 있습니다. +* 간단한 API 문법과 한 번의 명령으로 여러 언어 코드를 생성할 수 있습니다. +* 클라이언트 요청 파라미터를 자동으로 검증합니다. +* 다양한 내장 마이크로서비스 관리 도구와 동시성 도구를 제공합니다. + +Architecture + +## go-zero의 배경 + +2018년 초, 우리는 Java+MongoDB 기반 모놀리식 아키텍처에서 마이크로서비스로 전환하면서 다음을 선택했습니다. + +* **Golang** - 높은 성능, 간결한 문법, 뛰어난 배포 경험, 낮은 리소스 사용량 +* **자체 설계한 마이크로서비스 프레임워크** - 더 나은 문제 격리, 더 쉬운 기능 확장, 더 빠른 이슈 해결 + +## go-zero의 설계 고려 사항 + +go-zero는 다음 핵심 설계 원칙을 따릅니다. + +* **단순성** - 단순하게 유지하는 것을 제1원칙으로 삼습니다. +* **고가용성** - 높은 동시성 상황에서도 안정적으로 동작합니다. +* **회복 탄력성** - 적응형 보호를 갖춘 장애 지향 프로그래밍을 지향합니다. +* **개발자 친화성** - 복잡성을 캡슐화하고 한 가지 일을 하는 한 가지 방법을 제공합니다. +* **확장 용이성** - 성장을 위한 유연한 아키텍처를 제공합니다. + +## go-zero의 구현과 기능 + +go-zero는 엔지니어링 모범 사례를 통합합니다. + +* **코드 생성** - 보일러플레이트를 최소화하는 강력한 도구 +* **간단한 API** - 깔끔한 인터페이스와 net/http 완전 호환 +* **고성능** - 속도와 효율성을 위한 최적화 +* **회복 탄력성** - 내장 서킷 브레이커, 속도 제한, 로드 셰딩, 타임아웃 제어 +* **서비스 메시** - 서비스 디스커버리, 부하 분산, 호출 추적 +* **개발자 도구** - 자동 파라미터 검증, 캐시 관리, 메트릭과 모니터링 + +![Resilience](https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/resilience-en.png) + +## go-zero 아키텍처 + +image + +## 설치 + +프로젝트에서 다음 명령을 실행하세요. + +```shell +go get -u github.com/zeromicro/go-zero +``` + +## AI 네이티브 개발 + +go-zero 팀은 Claude, GitHub Copilot, Cursor가 프레임워크 규칙을 따르는 코드를 생성할 수 있도록 AI 도구를 제공합니다. + +### 세 가지 핵심 프로젝트 + +**[ai-context](https://github.com/zeromicro/ai-context)** - AI 어시스턴트를 위한 워크플로 가이드 + +**[zero-skills](https://github.com/zeromicro/zero-skills)** - 예제가 포함된 패턴 라이브러리 + +**[mcp-zero](https://github.com/zeromicro/mcp-zero)** - Model Context Protocol을 통한 코드 생성 도구 + +### 빠른 설정 + +#### GitHub Copilot +```bash +git submodule add https://github.com/zeromicro/ai-context.git .github/ai-context +ln -s ai-context/00-instructions.md .github/copilot-instructions.md # macOS/Linux +# Windows: mklink .github\copilot-instructions.md .github\ai-context\00-instructions.md +git submodule update --remote .github/ai-context # 업데이트 +``` + +#### Cursor +```bash +git submodule add https://github.com/zeromicro/ai-context.git .cursorrules +git submodule update --remote .cursorrules # 업데이트 +``` + +#### Windsurf +```bash +git submodule add https://github.com/zeromicro/ai-context.git .windsurfrules +git submodule update --remote .windsurfrules # 업데이트 +``` + +#### Claude Desktop +```bash +git clone https://github.com/zeromicro/mcp-zero.git && cd mcp-zero && go build +# 설정: ~/Library/Application Support/Claude/claude_desktop_config.json +# 또는: claude mcp add --transport stdio mcp-zero --env GOCTL_PATH=/path/to/goctl -- /path/to/mcp-zero +``` + +### 동작 방식 + +AI 어시스턴트는 다음 도구를 함께 사용합니다. +1. **ai-context** - 워크플로 안내 +2. **zero-skills** - 구현 패턴 +3. **mcp-zero** - 실시간 코드 생성 + +**예시**: REST API 생성 → AI가 **ai-context**에서 워크플로를 읽음 → **mcp-zero**를 호출해 코드 생성 → **zero-skills**에서 패턴 참조 → 프로덕션 준비가 된 코드 생성 ✅ + +## 빠른 시작 + +1. 전체 예제: + + [마이크로서비스 시스템 빠른 개발](https://github.com/zeromicro/zero-doc/blob/main/doc/shorturl-en.md) + + [마이크로서비스 시스템 빠른 개발 - 다중 RPC](https://github.com/zeromicro/zero-doc/blob/main/docs/zero/bookstore-en.md) + +2. goctl 설치 + + ```shell + # Go 사용 + go install github.com/zeromicro/go-zero/tools/goctl@latest + + # Mac 사용 + brew install goctl + + # 모든 플랫폼에서 docker 사용 + docker pull kevinwan/goctl + # goctl 실행 + docker run --rm -it -v `pwd`:/app kevinwan/goctl --help + ``` + + goctl이 실행 가능하고 $PATH에 포함되어 있는지 확인하세요. + +3. API 파일(greet.api) 생성: + + ```go + type ( + Request { + Name string `path:"name,options=[you,me]"` // 파라미터는 자동으로 검증됩니다. + } + + Response { + Message string `json:"message"` + } + ) + + service greet-api { + @handler GreetHandler + get /greet/from/:name(Request) returns (Response) + } + ``` + + .api 템플릿 생성: + + ```shell + goctl api -o greet.api + ``` + +4. Go 서버 코드 생성 + + ```shell + goctl api go -api greet.api -dir greet + ``` + + 생성되는 구조: + + ```Plain Text + ├── greet + │   ├── etc + │   │   └── greet-api.yaml // 설정 파일 + │   ├── greet.go // main 파일 + │   └── internal + │   ├── config + │   │   └── config.go // 설정 정의 + │   ├── handler + │   │   ├── greethandler.go // get/put/post/delete 라우트가 여기에 정의됩니다. + │   │   └── routes.go // 라우트 목록 + │   ├── logic + │   │   └── greetlogic.go // 요청 로직을 여기에 작성할 수 있습니다. + │   ├── svc + │   │   └── servicecontext.go // 서비스 컨텍스트, mysql/redis를 여기에 전달할 수 있습니다. + │   └── types + │   └── types.go // 요청/응답이 여기에 정의됩니다. + └── greet.api // api 설명 파일 + ``` + + 서비스 실행: + + ```shell + cd greet + go mod tidy + go run greet.go -f etc/greet-api.yaml + ``` + + 기본 포트: 8888(etc/greet-api.yaml에서 변경 가능) + + curl로 테스트: + + ```shell + curl -i http://localhost:8888/greet/from/you + ``` + + 응답: + + ```http + HTTP/1.1 200 OK + Date: Sun, 30 Aug 2020 15:32:35 GMT + Content-Length: 0 + ``` + +5. 비즈니스 로직 작성 + + * servicecontext.go를 통해 의존성(mysql, redis 등)을 전달합니다. + * .api 정의에 따라 logic 패키지에 로직 코드를 추가합니다. + +6. 여러 언어의 클라이언트 코드 생성 + + ```shell + goctl api java -api greet.api -dir greet + goctl api dart -api greet.api -dir greet + ... + ``` + +## 벤치마크 + +![benchmark](https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/benchmark.png) + +[테스트 코드 보기](https://github.com/smallnest/go-web-framework-benchmark) + +## 문서 + +* [문서](https://go-zero.dev/) +* [마이크로서비스 시스템 빠른 개발](https://github.com/zeromicro/zero-doc/blob/main/doc/shorturl-en.md) +* [마이크로서비스 시스템 빠른 개발 - 다중 RPC](https://github.com/zeromicro/zero-doc/blob/main/docs/zero/bookstore-en.md) +* [예제](https://github.com/zeromicro/zero-examples) + +## 채팅 그룹 + +다음 링크에서 채팅에 참여하세요: https://discord.gg/4JQvC5A4Fe + +## Cloud Native Landscape + +

+    + +

+ +go-zero는 [CNCF Cloud Native Landscape](https://landscape.cncf.io/?selected=go-zero)에 등재되었습니다. + +## 별을 눌러주세요! ⭐ + +이 프로젝트가 마음에 들거나 학습 또는 자체 솔루션을 시작하는 데 사용 중이라면, 새 릴리스 업데이트를 받을 수 있도록 star를 눌러주세요. 여러분의 지원은 큰 힘이 됩니다! diff --git a/readme.md b/readme.md index e774629706c5..106beed5c9ee 100644 --- a/readme.md +++ b/readme.md @@ -19,7 +19,7 @@ go-zero is a web and rpc framework with lots of builtin engineering practices. I ## 🤷‍ What is go-zero? -English | [简体中文](readme-cn.md) +English | [简体中文](readme-cn.md) | [한국어](readme-ko.md) zeromicro%2Fgo-zero | Trendshift go-zero - A web & rpc framework written in Go. | Product Hunt diff --git a/tools/goctl/readme-cn.md b/tools/goctl/readme-cn.md index 001289ca7437..ce1e5bdf9726 100644 --- a/tools/goctl/readme-cn.md +++ b/tools/goctl/readme-cn.md @@ -1,5 +1,5 @@ # goctl -[English](readme.md) | 简体中文 +[English](readme.md) | 简体中文 | [한국어](readme-ko.md) goctl 使用见文档 https://go-zero.dev/docs/tutorials/cli/overview diff --git a/tools/goctl/readme-ko.md b/tools/goctl/readme-ko.md new file mode 100644 index 000000000000..82b3cbf7cf7d --- /dev/null +++ b/tools/goctl/readme-ko.md @@ -0,0 +1,5 @@ +# goctl + +[English](readme.md) | [简体中文](readme-cn.md) | 한국어 + +다음 문서에서 확인하세요: https://go-zero.dev/docs/tutorials/cli/overview diff --git a/tools/goctl/readme.md b/tools/goctl/readme.md index dd6b5b48abf5..f4e228fc196a 100644 --- a/tools/goctl/readme.md +++ b/tools/goctl/readme.md @@ -1,5 +1,5 @@ # goctl -English | [简体中文](readme-cn.md) +English | [简体中文](readme-cn.md) | [한국어](readme-ko.md) Read document at https://go-zero.dev/docs/tutorials/cli/overview diff --git a/tools/goctl/rpc/CHANGELOG-cn.md b/tools/goctl/rpc/CHANGELOG-cn.md index eb4229efa335..427c9b552873 100644 --- a/tools/goctl/rpc/CHANGELOG-cn.md +++ b/tools/goctl/rpc/CHANGELOG-cn.md @@ -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` 处理支持的标准类型。 **前后对比：** diff --git a/tools/goctl/rpc/CHANGELOG-ko.md b/tools/goctl/rpc/CHANGELOG-ko.md new file mode 100644 index 000000000000..f38cf2adfc20 --- /dev/null +++ b/tools/goctl/rpc/CHANGELOG-ko.md @@ -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`을 이름을 변경하고 업데이트하여 점 표기 타입이 이제 성공적으로 파싱되는지 검증합니다. diff --git a/tools/goctl/rpc/CHANGELOG.md b/tools/goctl/rpc/CHANGELOG.md index dd4ddd379d73..24f6c859019b 100644 --- a/tools/goctl/rpc/CHANGELOG.md +++ b/tools/goctl/rpc/CHANGELOG.md @@ -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:** diff --git a/tools/goctl/rpc/README-cn.md b/tools/goctl/rpc/README-cn.md index cf534ec081a3..4bbdc08e33a8 100644 --- a/tools/goctl/rpc/README-cn.md +++ b/tools/goctl/rpc/README-cn.md @@ -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/) | 服务端/客户端/双向流 | diff --git a/tools/goctl/rpc/README-ko.md b/tools/goctl/rpc/README-ko.md new file mode 100644 index 000000000000..d68c68d45d27 --- /dev/null +++ b/tools/goctl/rpc/README-ko.md @@ -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 [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 [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= [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/) | 서버/클라이언트/양방향 스트리밍 | diff --git a/tools/goctl/rpc/README.md b/tools/goctl/rpc/README.md index 4a1f655e9199..bf30ca5393e5 100644 --- a/tools/goctl/rpc/README.md +++ b/tools/goctl/rpc/README.md @@ -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 | diff --git a/tools/goctl/rpc/example/01-basic/README-cn.md b/tools/goctl/rpc/example/01-basic/README-cn.md index 6de478ef30b2..a494ab086332 100644 --- a/tools/goctl/rpc/example/01-basic/README-cn.md +++ b/tools/goctl/rpc/example/01-basic/README-cn.md @@ -1,5 +1,7 @@ # 示例 01：基础 RPC 服务 +[English](README.md) | 中文 | [한국어](README-ko.md) + 这是使用 goctl 生成 RPC 服务的最简单示例。 ## Proto 定义 diff --git a/tools/goctl/rpc/example/01-basic/README-ko.md b/tools/goctl/rpc/example/01-basic/README-ko.md new file mode 100644 index 000000000000..1fa984a5a4ea --- /dev/null +++ b/tools/goctl/rpc/example/01-basic/README-ko.md @@ -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`)을 수정하세요. diff --git a/tools/goctl/rpc/example/01-basic/README.md b/tools/goctl/rpc/example/01-basic/README.md index a0067f897954..fe488692a259 100644 --- a/tools/goctl/rpc/example/01-basic/README.md +++ b/tools/goctl/rpc/example/01-basic/README.md @@ -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 diff --git a/tools/goctl/rpc/example/02-import-sibling/README-cn.md b/tools/goctl/rpc/example/02-import-sibling/README-cn.md index c08369d2ccd6..11daebe6cd57 100644 --- a/tools/goctl/rpc/example/02-import-sibling/README-cn.md +++ b/tools/goctl/rpc/example/02-import-sibling/README-cn.md @@ -1,5 +1,7 @@ # 示例 02：导入同级 Proto 文件 +[English](README.md) | 中文 | [한국어](README-ko.md) + 本示例演示如何导入同一目录下的 proto 文件。 ## Proto 定义 diff --git a/tools/goctl/rpc/example/02-import-sibling/README-ko.md b/tools/goctl/rpc/example/02-import-sibling/README-ko.md new file mode 100644 index 000000000000..ca5ac6b363bd --- /dev/null +++ b/tools/goctl/rpc/example/02-import-sibling/README-ko.md @@ -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이 해결합니다. diff --git a/tools/goctl/rpc/example/02-import-sibling/README.md b/tools/goctl/rpc/example/02-import-sibling/README.md index 743dca8c8ed5..853c8b9ec79a 100644 --- a/tools/goctl/rpc/example/02-import-sibling/README.md +++ b/tools/goctl/rpc/example/02-import-sibling/README.md @@ -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 diff --git a/tools/goctl/rpc/example/03-import-subdir/README-cn.md b/tools/goctl/rpc/example/03-import-subdir/README-cn.md index 8190873c06b9..504985bcb437 100644 --- a/tools/goctl/rpc/example/03-import-subdir/README-cn.md +++ b/tools/goctl/rpc/example/03-import-subdir/README-cn.md @@ -1,5 +1,7 @@ # 示例 03：导入子目录中的 Proto 文件 +[English](README.md) | 中文 | [한국어](README-ko.md) + 本示例演示如何导入子目录中的 proto 文件。 ## Proto 定义 diff --git a/tools/goctl/rpc/example/03-import-subdir/README-ko.md b/tools/goctl/rpc/example/03-import-subdir/README-ko.md new file mode 100644 index 000000000000..e3487120bf49 --- /dev/null +++ b/tools/goctl/rpc/example/03-import-subdir/README-ko.md @@ -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`를 찾을 수 있게 합니다. diff --git a/tools/goctl/rpc/example/03-import-subdir/README.md b/tools/goctl/rpc/example/03-import-subdir/README.md index 038cb3b1eaac..b3b9368307c2 100644 --- a/tools/goctl/rpc/example/03-import-subdir/README.md +++ b/tools/goctl/rpc/example/03-import-subdir/README.md @@ -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 diff --git a/tools/goctl/rpc/example/04-transitive-import/README-cn.md b/tools/goctl/rpc/example/04-transitive-import/README-cn.md index 8f7c1b42913d..e62d4afd5b67 100644 --- a/tools/goctl/rpc/example/04-transitive-import/README-cn.md +++ b/tools/goctl/rpc/example/04-transitive-import/README-cn.md @@ -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 会自动处理其余部分。 diff --git a/tools/goctl/rpc/example/04-transitive-import/README-ko.md b/tools/goctl/rpc/example/04-transitive-import/README-ko.md new file mode 100644 index 000000000000..a275af643d22 --- /dev/null +++ b/tools/goctl/rpc/example/04-transitive-import/README-ko.md @@ -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 동작과 동일). diff --git a/tools/goctl/rpc/example/04-transitive-import/README.md b/tools/goctl/rpc/example/04-transitive-import/README.md index 8f88d2381866..7cbf1f548b3e 100644 --- a/tools/goctl/rpc/example/04-transitive-import/README.md +++ b/tools/goctl/rpc/example/04-transitive-import/README.md @@ -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. diff --git a/tools/goctl/rpc/example/05-multiple-services/README-cn.md b/tools/goctl/rpc/example/05-multiple-services/README-cn.md index 2c9c7791cd45..19166037ab24 100644 --- a/tools/goctl/rpc/example/05-multiple-services/README-cn.md +++ b/tools/goctl/rpc/example/05-multiple-services/README-cn.md @@ -1,5 +1,7 @@ # 示例 05：多服务模式（`--multiple`） +[English](README.md) | 中文 | [한국어](README-ko.md) + 本示例演示从一个 proto 文件生成多个 RPC 服务。 ## Proto 定义 diff --git a/tools/goctl/rpc/example/05-multiple-services/README-ko.md b/tools/goctl/rpc/example/05-multiple-services/README-ko.md new file mode 100644 index 000000000000..6ea2aec34dc6 --- /dev/null +++ b/tools/goctl/rpc/example/05-multiple-services/README-ko.md @@ -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`를 공유합니다. diff --git a/tools/goctl/rpc/example/05-multiple-services/README.md b/tools/goctl/rpc/example/05-multiple-services/README.md index 13b610700cc1..457718c69f2d 100644 --- a/tools/goctl/rpc/example/05-multiple-services/README.md +++ b/tools/goctl/rpc/example/05-multiple-services/README.md @@ -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 diff --git a/tools/goctl/rpc/example/06-wellknown-types/README-cn.md b/tools/goctl/rpc/example/06-wellknown-types/README-cn.md index e3d75b25c503..b538b20de7fe 100644 --- a/tools/goctl/rpc/example/06-wellknown-types/README-cn.md +++ b/tools/goctl/rpc/example/06-wellknown-types/README-cn.md @@ -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`。 diff --git a/tools/goctl/rpc/example/06-wellknown-types/README-ko.md b/tools/goctl/rpc/example/06-wellknown-types/README-ko.md new file mode 100644 index 000000000000..ddd9025c3ae5 --- /dev/null +++ b/tools/goctl/rpc/example/06-wellknown-types/README-ko.md @@ -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`가 필요하지 않습니다. diff --git a/tools/goctl/rpc/example/06-wellknown-types/README.md b/tools/goctl/rpc/example/06-wellknown-types/README.md index 5a4591d2ad58..694c7feac667 100644 --- a/tools/goctl/rpc/example/06-wellknown-types/README.md +++ b/tools/goctl/rpc/example/06-wellknown-types/README.md @@ -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. diff --git a/tools/goctl/rpc/example/07-external-proto-same-pkg/README-cn.md b/tools/goctl/rpc/example/07-external-proto-same-pkg/README-cn.md index af7f360fc328..a6b4564e34c8 100644 --- a/tools/goctl/rpc/example/07-external-proto-same-pkg/README-cn.md +++ b/tools/goctl/rpc/example/07-external-proto-same-pkg/README-cn.md @@ -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`。 diff --git a/tools/goctl/rpc/example/07-external-proto-same-pkg/README-ko.md b/tools/goctl/rpc/example/07-external-proto-same-pkg/README-ko.md new file mode 100644 index 000000000000..26264b944179 --- /dev/null +++ b/tools/goctl/rpc/example/07-external-proto-same-pkg/README-ko.md @@ -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가 필요하지 않습니다. diff --git a/tools/goctl/rpc/example/07-external-proto-same-pkg/README.md b/tools/goctl/rpc/example/07-external-proto-same-pkg/README.md index 83fa396d6888..92e0c26cc31c 100644 --- a/tools/goctl/rpc/example/07-external-proto-same-pkg/README.md +++ b/tools/goctl/rpc/example/07-external-proto-same-pkg/README.md @@ -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`. diff --git a/tools/goctl/rpc/example/08-external-proto-diff-pkg/README-cn.md b/tools/goctl/rpc/example/08-external-proto-diff-pkg/README-cn.md index 5c04a464f92a..29a60564868b 100644 --- a/tools/goctl/rpc/example/08-external-proto-diff-pkg/README-cn.md +++ b/tools/goctl/rpc/example/08-external-proto-diff-pkg/README-cn.md @@ -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 包。 diff --git a/tools/goctl/rpc/example/08-external-proto-diff-pkg/README-ko.md b/tools/goctl/rpc/example/08-external-proto-diff-pkg/README-ko.md new file mode 100644 index 000000000000..554a1834dc7d --- /dev/null +++ b/tools/goctl/rpc/example/08-external-proto-diff-pkg/README-ko.md @@ -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 파라미터 타입으로 직접 사용합니다. diff --git a/tools/goctl/rpc/example/08-external-proto-diff-pkg/README.md b/tools/goctl/rpc/example/08-external-proto-diff-pkg/README.md index 5ff23959602f..fc425893ed16 100644 --- a/tools/goctl/rpc/example/08-external-proto-diff-pkg/README.md +++ b/tools/goctl/rpc/example/08-external-proto-diff-pkg/README.md @@ -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. diff --git a/tools/goctl/rpc/example/09-google-types-as-rpc/README-cn.md b/tools/goctl/rpc/example/09-google-types-as-rpc/README-cn.md index 40ae635afa7d..e846b2a3cb77 100644 --- a/tools/goctl/rpc/example/09-google-types-as-rpc/README-cn.md +++ b/tools/goctl/rpc/example/09-google-types-as-rpc/README-cn.md @@ -1,4 +1,6 @@ -# 示例 09：Google 类型作为 RPC 参数 +# 示例 09：Google 知名类型作为 RPC 参数 + +[English](README.md) | 中文 | [한국어](README-ko.md) 本示例演示将 Google protobuf 知名类型**直接**用作 RPC 请求或响应类型（而不仅仅是消息字段）。 diff --git a/tools/goctl/rpc/example/09-google-types-as-rpc/README-ko.md b/tools/goctl/rpc/example/09-google-types-as-rpc/README-ko.md new file mode 100644 index 000000000000..d0724d3c108b --- /dev/null +++ b/tools/goctl/rpc/example/09-google-types-as-rpc/README-ko.md @@ -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과는 다릅니다. diff --git a/tools/goctl/rpc/example/09-google-types-as-rpc/README.md b/tools/goctl/rpc/example/09-google-types-as-rpc/README.md index 08b55d82daeb..cafba258dc77 100644 --- a/tools/goctl/rpc/example/09-google-types-as-rpc/README.md +++ b/tools/goctl/rpc/example/09-google-types-as-rpc/README.md @@ -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). diff --git a/tools/goctl/rpc/example/10-streaming/README-cn.md b/tools/goctl/rpc/example/10-streaming/README-cn.md index 59ae95096602..053d2f870e7c 100644 --- a/tools/goctl/rpc/example/10-streaming/README-cn.md +++ b/tools/goctl/rpc/example/10-streaming/README-cn.md @@ -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 发送和接收消息。 diff --git a/tools/goctl/rpc/example/10-streaming/README-ko.md b/tools/goctl/rpc/example/10-streaming/README-ko.md new file mode 100644 index 000000000000..855513b8dfa3 --- /dev/null +++ b/tools/goctl/rpc/example/10-streaming/README-ko.md @@ -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을 사용해 메시지를 송수신하세요. diff --git a/tools/goctl/rpc/example/10-streaming/README.md b/tools/goctl/rpc/example/10-streaming/README.md index 477cdd2afbec..d4cc1c67aaf4 100644 --- a/tools/goctl/rpc/example/10-streaming/README.md +++ b/tools/goctl/rpc/example/10-streaming/README.md @@ -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. diff --git a/tools/goctl/rpc/example/README-ko.md b/tools/goctl/rpc/example/README-ko.md new file mode 100644 index 000000000000..f89359536171 --- /dev/null +++ b/tools/goctl/rpc/example/README-ko.md @@ -0,0 +1,47 @@ +# RPC 예제 + +[English / 中文](README.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 . +``` diff --git a/tools/goctl/rpc/example/README.md b/tools/goctl/rpc/example/README.md index ece7b08759d2..160c062ce831 100644 --- a/tools/goctl/rpc/example/README.md +++ b/tools/goctl/rpc/example/README.md @@ -1,10 +1,12 @@ # RPC Examples +English / 中文 | [한국어](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 @@ -52,7 +54,7 @@ goctl rpc protoc greeter.proto \ 每个示例包含： - `.proto` 源文件 -- `README.md`（英文）和 `README-cn.md`（中文）文档 +- `README.md`（英文）、`README-cn.md`（中文）和 `README-ko.md`（한국어）文档 ## 示例列表 @@ -63,10 +65,10 @@ goctl rpc protoc greeter.proto \ | 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` | +| 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 参数 | `--proto_path=$PROTOC_INCLUDE` | +| 09 | [09-google-types-as-rpc](09-google-types-as-rpc/) | Google 标准类型作为 RPC 参数 | — | | 10 | [10-streaming](10-streaming/) | 服务端/客户端/双向流 | — | ## 前置条件