grpc idl 簡單介紹

在 gRPC 中，IDL（接口定義語言）是通過 Protocol Buffers（.proto 文件） 來定義的。為了保證你的 gRPC 接口具有清晰、可維護、可擴展、跨語言兼容等特性，編寫 .proto 文件時應遵循一系列編碼規范和最佳實踐。

下面是 gRPC/Protobuf .proto 文件的編碼指導，包括命名規范、結構組織、字段使用建議、版本控制等：

---

1. 文件結構組織規范

文件命名

• 使用 小寫 + 下劃線 命名：如 user_service.proto。
• 文件名應能體現模塊或服務名稱。

包結構：

syntax = "proto3";package myapp.user;  // 多層命名空間，避免沖突option go_package = "github.com/yourorg/yourproject/gen/userpb";  // Go 等語言需要指定導入路徑

推薦：一個文件只定義一個 service，如果 service 很復雜，可拆分多個 proto 文件。

---

2. 消息定義規范

命名風格

• 消息/服務/枚舉使用 PascalCase：如 UserRequest、UserResponse、UserService。
• 字段使用 snake_case：如 user_id、email_address。

字段編號：

• 使用 1 ~ 15 編號范圍保留給高頻使用字段（性能更高）。
• 不要修改已發布字段的編號。

示例：

message UserRequest {int64 user_id = 1;string email = 2;
}

---

3. 服務與 RPC 設計規范

命名規范

• Service 命名應體現業務領域，如 UserService、AuthService。
• 方法名使用 PascalCase，如 GetUser、CreateUser。

請求和響應推薦

• 請求消息以 XxxRequest 結尾，響應以 XxxResponse 結尾。

示例

service UserService {rpc GetUser (UserRequest) returns (UserResponse);rpc CreateUser (CreateUserRequest) returns (CreateUserResponse);
}

---

4. 枚舉與默認值

• 枚舉的第一個值必須為 0，通常命名為 ENUM_UNSPECIFIED 或 UNKNOWN。
• 避免使用 magic numbers。

enum UserStatus {USER_STATUS_UNSPECIFIED = 0;USER_ACTIVE = 1;USER_INACTIVE = 2;
}

---

5. 可擴展性設計建議

• 不要刪除字段編號，即使字段廢棄了，也應保留編號（可加注釋標記 deprecated）。
• 留空編號以備將來使用。
• 使用 reserved 關鍵字保留字段名或編號，防止沖突：

message User {reserved 3, 4;          // 保留編號reserved "old_field";   // 保留字段名
}

---

6. 錯誤處理推薦（跨語言）

gRPC 使用 Status 返回錯誤，建議定義自定義錯誤碼：

import "google/rpc/status.proto";
import "google/rpc/code.proto";service AuthService {rpc Login(LoginRequest) returns (LoginResponse) {option (google.api.http) = {post: "/v1/login"body: "*"};}
}

建議返回 google.rpc.Status 作為 error detail，方便統一錯誤處理。

---

7. 注釋和文檔生成

• 使用 // 或 / ... */ 注釋消息、字段、方法，支持 protoc-gen-doc 等工具自動生成文檔。
• 注釋寫清楚單位、約束、默認值、特殊說明。

// 用戶注冊請求
message RegisterRequest {// 用戶郵箱地址（必須為合法格式）string email = 1;
}

---

8. gRPC REST 網關支持（可選）

如你使用 gRPC Gateway（用于提供 REST 接口），應加上 google.api.http 的 option：

import "google/api/annotations.proto";service UserService {rpc GetUser (GetUserRequest) returns (User) {option (google.api.http) = {get: "/v1/users/{user_id}"};}
}

---

9. 通用封裝結構推薦（可選）

定義通用結構，便于擴展或統一返回格式：

message BaseResponse {int32 code = 1;string message = 2;
}message PageRequest {int32 page = 1;int32 size = 2;
}message PageResponse {int32 total = 1;
}

---

10. 目錄結構推薦（大型項目）

proto/
├── user/
│   ├── user.proto
│   └── user_service.proto
├── common/
│   ├── error.proto
│   ├── pagination.proto

---

總結：Checklist（編碼規范）

類別	規范建議
命名	PascalCase（類型），snake_case（字段）
字段編號	不重用，保留廢棄編號
擴展性	使用 reserved，保留字段空間
服務設計	明確語義，方法命名動詞開頭
注釋	字段、消息、方法寫清楚注釋
錯誤處理	建議接入 google.rpc.Status
REST 支持	使用 google.api.http 注解
通用結構	可封裝統一響應、分頁等結構