当前位置: 首页 > article >正文

【C/C++】入门grpc的idl

文章目录

  • grpc idl 简单介绍
    • 1. 文件结构组织规范
      • 文件命名
      • 包结构:
      • 推荐:一个文件只定义一个 service,如果 service 很复杂,可拆分多个 proto 文件。
    • 2. 消息定义规范
      • 命名风格
      • 字段编号:
      • 示例:
    • 3. 服务与 RPC 设计规范
      • 命名规范
      • 请求和响应推荐
      • 示例
    • 4. 枚举与默认值
    • 5. 可扩展性设计建议
    • 6. 错误处理推荐(跨语言)
    • 7. 注释和文档生成
    • 8. gRPC REST 网关支持(可选)
    • 9. 通用封装结构推荐(可选)
    • 10. 目录结构推荐(大型项目)
    • 总结:Checklist(编码规范)

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:如 UserRequestUserResponseUserService
  • 字段使用 snake_case:如 user_idemail_address

字段编号:

  • 使用 1 ~ 15 编号范围保留给高频使用字段(性能更高)。
  • 不要修改已发布字段的编号。

示例:

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

3. 服务与 RPC 设计规范

命名规范

  • Service 命名应体现业务领域,如 UserServiceAuthService
  • 方法名使用 PascalCase,如 GetUserCreateUser

请求和响应推荐

  • 请求消息以 XxxRequest 结尾,响应以 XxxResponse 结尾。

示例

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

4. 枚举与默认值

  • 枚举的第一个值必须为 0,通常命名为 ENUM_UNSPECIFIEDUNKNOWN
  • 避免使用 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 注解
通用结构可封装统一响应、分页等结构
http://www.lryc.cn/news/2399578.html

相关文章:

  • 【Java实用工具类】手撸SqlBuilder工具类,优雅拼接动态SQL,MyBatisPlus同款风格!
  • 宇树科技更名“股份有限公司”深度解析:机器人企业IPO前奏与资本化路径
  • Inno Setup 安装向导各个页面详解
  • 转战web3远程工作的英语学习的路线规划
  • OPENCV重点结构体Mat的讲解
  • Java 创建线程池的几种方式
  • 【趣味Html】第11课:动态闪烁发光粒子五角星
  • AnyIO Event:异步编程中的同步利器
  • CFTel:一种基于云雾自动化的鲁棒且可扩展的远程机器人架构
  • Educational Codeforces Round 179 (Rated for Div. 2)
  • 完成一个可交互的k8s管理平台的页面开发
  • 多线程编程技术解析及示例:pthread_cond_timedwait、pthread_mutex_lock 和 pthread_mutex_trylock
  • vue实现点击单选或者多选模式
  • Windows系统工具:WinToolsPlus 之 SQL Server 日志清理
  • 在Windows11上安装 Ubuntu WSL
  • 嵌入式Linux之RK3568
  • Elasticsearch的插件(Plugin)系统介绍
  • 提取 PDF 文件中的文字以及图片中的文字
  • JavaScript性能优化实战技术
  • LeetCode 热题 100 739. 每日温度
  • 网页前端开发(基础进阶3--Vue)
  • tryhackme——Abusing Windows Internals(进程注入)
  • 【游戏科学】游戏开发中数学算法的核心与应用
  • 【Day44】
  • 基于 Alpine 定制单功能用途(kiosk)电脑
  • 知识图谱系统功能实现,技术解决方案,附源码
  • 第12节 Node.js 函数
  • 洛谷P12610 ——[CCC 2025 Junior] Donut Shop
  • 1. 数据库基础
  • 英伟达288GB HBM4+50P算力