[teamai] Push 87 resource(s) from XingfenD

2026-09-10 16:10:45 +08:00
parent 425c9c078a
commit 65c04def51
1314 changed files with 211681 additions and 0 deletions
@@ -0,0 +1,150 @@
+# Protobuf & Code Generation Reference
+
+## Directory Layout
+
+Organize proto files by domain with versioned directories. Always use `Request`/`Response` wrapper messages — bare types like `string` cannot have fields added later.
+
+```
+proto/
+├── user/v1/
+│   ├── user.proto          # Messages
+│   └── user_service.proto  # Service RPCs
+├── order/v1/
+│   ├── order.proto
+│   └── order_service.proto
+└── shared/v1/
+    └── common.proto        # Pagination, timestamps, shared enums
+```
+
+## Proto File Conventions
+
+```protobuf
+syntax = "proto3";
+package mycompany.user.v1;
+option go_package = "github.com/mycompany/myservice/gen/user/v1;userv1";
+
+service UserService {
+  rpc GetUser(GetUserRequest) returns (GetUserResponse);
+  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
+  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
+  rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);
+  rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse);
+}
+
+message GetUserRequest {
+  string user_id = 1;
+}
+
+message GetUserResponse {
+  User user = 1;
+}
+
+message ListUsersRequest {
+  int32 page_size = 1;
+  string page_token = 2;
+}
+
+message ListUsersResponse {
+  repeated User users = 1;
+  string next_page_token = 2;
+}
+```
+
+### `go_package` conventions
+
+- Format: `"import/path;alias"` — the alias becomes the Go package name
+- Convention: lowercase version suffix (e.g. `userv1`, `orderv1`)
+- Generate into a `gen/` directory to keep generated code separate from hand-written code
+
+## Code Generation with `protoc`
+
+```bash
+# Basic generation
+protoc --go_out=gen --go_opt=paths=source_relative \
+       --go-grpc_out=gen --go-grpc_opt=paths=source_relative \
+       proto/user/v1/*.proto
+
+# With validation (using buf-validate)
+protoc --go_out=gen --go_opt=paths=source_relative \
+       --go-grpc_out=gen --go-grpc_opt=paths=source_relative \
+       --validate_out="lang=go:gen" \
+       proto/user/v1/*.proto
+
+# Include external imports
+protoc -I proto -I third_party \
+       --go_out=gen --go_opt=paths=source_relative \
+       --go-grpc_out=gen --go-grpc_opt=paths=source_relative \
+       proto/user/v1/*.proto
+```
+
+### Common `protoc` flags
+
+| Flag                             | Purpose                                 |
+| -------------------------------- | --------------------------------------- |
+| `--go_out=DIR`                   | Output directory for message types      |
+| `--go-grpc_out=DIR`              | Output directory for service stubs      |
+| `--go_opt=paths=source_relative` | Place output relative to proto source   |
+| `-I DIR`                         | Add import path for proto dependencies  |
+| `--descriptor_set_out=FILE`      | Emit binary descriptor (for reflection) |
+
+## Code Generation with `buf`
+
+`buf` is the recommended modern alternative to raw `protoc`. It manages dependencies, lints protos, and generates code from a single config.
+
+### `buf.gen.yaml`
+
+```yaml
+version: v2
+plugins:
+  - remote: buf.build/protocolbuffers/go
+    out: gen
+    opt: paths=source_relative
+  - remote: buf.build/grpc/go
+    out: gen
+    opt: paths=source_relative
+```
+
+### `buf.yaml`
+
+```yaml
+version: v2
+modules:
+  - path: proto
+lint:
+  use:
+    - STANDARD
+breaking:
+  use:
+    - FILE
+```
+
+### Common `buf` commands
+
+```bash
+buf generate              # Generate code from buf.gen.yaml
+buf lint                  # Lint proto files
+buf breaking --against '.git#branch=main'  # Check backward compatibility
+buf dep update            # Update dependencies
+buf build                 # Validate proto files compile
+```
+
+## Generated Code Patterns
+
+After generation, import and use the generated code:
+
+```go
+import (
+    userv1 "github.com/mycompany/myservice/gen/user/v1"
+)
+
+// Server: implement the interface
+type userServer struct {
+    userv1.UnimplementedUserServiceServer
+}
+
+// Client: use the generated client
+client := userv1.NewUserServiceClient(conn)
+resp, err := client.GetUser(ctx, &userv1.GetUserRequest{UserId: "123"})
+```
+
+Always embed `Unimplemented*Server` (not `Unsafe*Server`) — it provides forward compatibility when new RPCs are added to the proto definition.