csharp-grpclisted

# gRPC 服務開發規範 ## Proto 檔案管理（Crucial） ### 目錄結構 ```text src/ ├── Protos/ │ ├── order_service.proto │ └── product_service.proto ├── Services/ │ ├── OrderGrpcService.cs │ └── ProductGrpcService.cs ``` - Proto 檔案集中於 `Protos/` 目錄。 - 檔名使用 snake_case（`order_service.proto`），與 Protobuf 社群慣例一致。 - 每個 `.proto` 檔案對應���個邏輯上的服務domain。 ### Proto 檔案規範 ```protobuf syntax = "proto3"; option csharp_namespace = "MyApp.Grpc"; package myapp.v1; service OrderService { rpc GetOrder (GetOrderRequest) returns (GetOrderResponse); rpc ListOrders (ListOrdersRequest) returns (ListOrdersResponse); rpc CreateOrder (CreateOrderRequest) returns (CreateOrderResponse); } message GetOrderRequest { int32 id = 1; } message GetOrderResponse { int32 id = 1; string customer_name = 2; google.protobuf.Timestamp created_at = 3; repeated OrderItemMessage items = 4; } message OrderItemMessage { int32 product_id = 1; int32 quantity = 2; double unit_price = 3; } ``` - **必須**指定 `csharp_namespace`，避免產生的 C# 程式碼落入預設命名空間。 - **必須**指定 `package`，含版本號（如 `myapp.v1`）。 - 欄位命名使用 snake_case（Protobuf 慣例，Code Generator 會轉為 PascalCase）。 - Request / Response 訊息以 RPC 方法名稱為前綴，避免命名衝突。 ### 版本管理 - API 變更時，新增欄位不破壞相容性（proto3 預設行為）。 - 移除或變更欄位語意時，使用 `reserved` 保留舊欄位號。 - 重大變更建立新的 package 版本（如 `myapp.v2`）。 ## 專案設定 ```xml <ItemGroup> <Protobuf Include="Protos\*.proto" GrpcServices="Server" /> </ItemGroup> ``` | 屬性值 | 用途 | | --- | --- | | `Server` | 僅產生伺服器端基底類別 | | `Client` | 僅產生用戶端 Stub | | `Both` | 同時產生（同