|
1 | 1 | # Proto Generation Guide |
2 | 2 |
|
3 | | -This document explains how to generate gRPC code from protobuf files for the Croupier Go SDK. |
| 3 | +Croupier 内部 RPC 不使用 gRPC（[传输层决策](../../docs/architecture/transport-no-grpc.md)）：Server ↔ Agent ↔ SDK 走自研 TCP transport（length-prefix framing）+ protobuf 消息。本文档说明 Go SDK 的 protobuf 代码生成流程。 |
4 | 4 |
|
5 | | -## Overview |
| 5 | +## 生成方式（buf，与主仓库一致） |
6 | 6 |
|
7 | | -The Go SDK can operate in two modes: |
8 | | -1. **Mock mode** - Uses mock gRPC implementation (default, no dependencies required) |
9 | | -2. **Real gRPC mode** - Uses generated gRPC code (requires proto generation) |
| 7 | +统一使用 buf 远程插件生成，**只生成 protobuf 消息代码，不生成 gRPC 代码**： |
10 | 8 |
|
11 | | -## Quick Start |
12 | | - |
13 | | -### Option 1: Use Mock Mode (Easiest) |
14 | | - |
15 | | -No setup required! The SDK automatically uses mock gRPC implementation: |
16 | | - |
17 | | -```bash |
18 | | -go run examples/basic/main.go |
19 | | -``` |
20 | | - |
21 | | -### Option 2: Use Real gRPC |
22 | | - |
23 | | -#### Step 1: Install Dependencies |
24 | | - |
25 | | -**macOS:** |
26 | | -```bash |
27 | | -brew install protobuf |
28 | | -go install google.golang.org/protobuf/cmd/protoc-gen-go@latest |
29 | | -go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest |
30 | | -``` |
31 | | - |
32 | | -**Ubuntu/Debian:** |
33 | | -```bash |
34 | | -sudo apt-get install protobuf-compiler |
35 | | -go install google.golang.org/protobuf/cmd/protoc-gen-go@latest |
36 | | -go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest |
37 | | -``` |
38 | | - |
39 | | -**Other systems:** |
40 | | -Download protoc from [GitHub releases](https://github.com/protocolbuffers/protobuf/releases) |
41 | | - |
42 | | -#### Step 2: Generate gRPC Code |
43 | | - |
44 | | -```bash |
45 | | -# Using the convenient script |
46 | | -./generate_proto.sh |
47 | | - |
48 | | -# Or using Makefile |
49 | | -make proto |
50 | | - |
51 | | -# Or directly with Go |
52 | | -go run scripts/generate_proto.go |
53 | | -``` |
54 | | - |
55 | | -#### Step 3: Build with Real gRPC |
56 | | - |
57 | | -```bash |
58 | | -# Using Makefile |
59 | | -make build-with-grpc |
60 | | - |
61 | | -# Or with go build |
62 | | -go build -tags=croupier_real_grpc ./... |
63 | | - |
64 | | -# Run examples |
65 | | -make example |
66 | | -``` |
67 | | - |
68 | | -## Advanced Usage |
69 | | - |
70 | | -### Custom Proto Branch |
71 | | - |
72 | | -To generate from a different branch: |
73 | | - |
74 | | -```bash |
75 | | -./generate_proto.sh --branch develop |
76 | | -# or |
77 | | -CROUPIER_PROTO_BRANCH=develop ./generate_proto.sh |
78 | | -``` |
79 | | - |
80 | | -### Skip Proto Generation |
81 | | - |
82 | | -If you have previously generated proto files and want to skip regeneration: |
83 | | - |
84 | | -```bash |
85 | | -./generate_proto.sh --skip |
86 | | -# or |
87 | | -CROUPIER_SKIP_PROTO_GEN=1 ./generate_proto.sh |
88 | | -``` |
89 | | - |
90 | | -### Verbose Output |
91 | | - |
92 | | -For detailed output during generation: |
93 | | - |
94 | | -```bash |
95 | | -./generate_proto.sh --verbose |
96 | | -``` |
97 | | - |
98 | | -## Using the Makefile |
99 | | - |
100 | | -The Makefile provides convenient targets: |
101 | | - |
102 | | -```bash |
103 | | -# Build with mock gRPC (default) |
104 | | -make build |
105 | | - |
106 | | -# Build with real gRPC (generates proto first) |
107 | | -make build-with-grpc |
108 | | - |
109 | | -# Only generate proto files |
110 | | -make proto |
111 | | - |
112 | | -# Check if dependencies are installed |
113 | | -make check-deps |
114 | | - |
115 | | -# Install dependencies automatically |
116 | | -make install-deps |
117 | | - |
118 | | -# Run tests |
119 | | -make test |
120 | | - |
121 | | -# Run comprehensive example |
122 | | -make example |
123 | | - |
124 | | -# Clean generated files |
125 | | -make clean |
126 | | - |
127 | | -# Show build information |
128 | | -make info |
129 | | -``` |
130 | | - |
131 | | -## Environment Variables |
132 | | - |
133 | | -- `CROUPIER_SKIP_PROTO_GEN`: Set to 1 to skip proto generation |
134 | | -- `CROUPIER_PROTO_BRANCH`: Specify proto branch (default: main) |
135 | | -- `CROUPIER_CI_BUILD`: Set to 1 to enable CI mode (strict error checking) |
136 | | - |
137 | | -## Build Tags |
138 | | - |
139 | | -The generated gRPC code is protected by the build tag `croupier_real_grpc`. This means: |
140 | | - |
141 | | -- Without the tag: Mock implementation is used |
142 | | -- With the tag: Real gRPC implementation is used |
143 | | - |
144 | | -Example: |
145 | 9 | ```bash |
146 | | -# Mock implementation |
147 | | -go build ./... |
148 | | - |
149 | | -# Real gRPC implementation |
150 | | -go build -tags=croupier_real_grpc ./... |
151 | | -``` |
| 10 | +# 在仓库根目录 |
| 11 | +make proto # 主仓库 pkg/pb（transport/agent/SDK 契约消息） |
| 12 | +make pack # pack artifacts（protoc-gen-croupier） |
152 | 13 |
|
153 | | -## Directory Structure |
154 | | - |
155 | | -``` |
156 | | -. |
157 | | -├── downloaded_proto/ # Downloaded proto files (temporary) |
158 | | -├── proto/ # Generated Go code |
159 | | -│ ├── build_tags.go # Build tag indicator |
160 | | -│ ├── croupier/ # Generated packages |
161 | | -│ └── google/ # Generated Google APIs |
162 | | -├── scripts/ |
163 | | -│ └── generate_proto.go # Proto generation script |
164 | | -└── generate_proto.sh # Convenience wrapper script |
| 14 | +# Go SDK 单独生成（sdks/go/pkg/pb） |
| 15 | +cd sdks/go && make proto |
165 | 16 | ``` |
166 | 17 |
|
167 | | -## Troubleshooting |
| 18 | +`sdks/go/buf.gen.yaml` 固定插件版本（与主仓库 CI 一致）： |
168 | 19 |
|
169 | | -### protoc not found |
170 | | - |
171 | | -Install protoc: |
172 | | -```bash |
173 | | -# macOS |
174 | | -brew install protobuf |
175 | | - |
176 | | -# Ubuntu |
177 | | -sudo apt-get install protobuf-compiler |
178 | | -``` |
179 | | - |
180 | | -### Go protoc plugins not found |
181 | | - |
182 | | -Install the plugins: |
183 | | -```bash |
184 | | -go install google.golang.org/protobuf/cmd/protoc-gen-go@latest |
185 | | -go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest |
186 | | -``` |
187 | | - |
188 | | -Make sure `$GOPATH/bin` is in your `$PATH`. |
189 | | - |
190 | | -### proto download failed |
191 | | - |
192 | | -Check your internet connection and branch name: |
193 | | -```bash |
194 | | -./generate_proto.sh --branch main --verbose |
195 | | -``` |
196 | | - |
197 | | -### Generated code conflicts |
198 | | - |
199 | | -Clean and regenerate: |
200 | | -```bash |
201 | | -make clean |
202 | | -make proto |
203 | | -``` |
204 | | - |
205 | | -## CI Integration |
206 | | - |
207 | | -In CI environments, set `CROUPIER_CI_BUILD=1` to enable strict error checking: |
208 | | - |
209 | | -```yaml |
210 | | -- name: Generate proto |
211 | | - run: | |
212 | | - export CROUPIER_CI_BUILD=1 |
213 | | - make proto |
214 | | - make build-with-grpc |
215 | | -``` |
| 20 | +- `buf.build/protocolbuffers/go:v1.36.11` —— protobuf 消息代码 |
216 | 21 |
|
217 | | -## Difference Between Mock and Real gRPC |
| 22 | +## 约束 |
218 | 23 |
|
219 | | -| Feature | Mock Mode | Real gRPC Mode | |
220 | | -|---------|-----------|---------------| |
221 | | -| Dependencies | None | protoc, Go plugins | |
222 | | -| Network calls | Simulated | Real gRPC | |
223 | | -| Performance | Faster | Slower (real calls) | |
224 | | -| Testing | Good for unit tests | Integration tests | |
225 | | -| Production use | No | Yes | |
| 24 | +- **不要引入 `protoc-gen-go-grpc` / `buf.build/grpc/*` 插件**——历史上配置过但从未产生被使用的产物，已移除。 |
| 25 | +- 本地 `protoc` 版本与 buf 远程插件不匹配会生成不兼容代码，一律走 buf。 |
| 26 | +- 生成的代码在 `sdks/go/pkg/pb/`（git 跟踪），只有 proto 契约变更时才需要重新生成。 |
226 | 27 |
|
227 | | -## Best Practices |
| 28 | +## 历史说明 |
228 | 29 |
|
229 | | -1. **Development**: Use mock mode for faster iteration |
230 | | -2. **Testing**: Use mock mode for unit tests |
231 | | -3. **Integration**: Use real gRPC for integration tests |
232 | | -4. **Production**: Always use real gRPC |
233 | | -5. **CI**: Enable strict mode with `CROUPIER_CI_BUILD=1` |
| 30 | +早期 SDK 文档描述过 "Mock gRPC mode / Real gRPC mode" 双模式与 `generate_proto.sh` 脚本——该模型已随 gRPC 移除而废弃，脚本已删除。 |
0 commit comments