1-1-1 最佳实践[译]

分类：proto| 发布时间：2025-01-11 20:32:00

所有 proto 定义都应该有一个顶级元素并为每个文件构建目标。

正文

1-1-1 最佳实践是让每个 proto_library 和 .proto 文件尽可能小，理想情况是：

一个 proto_library 构建规则
一个 .proto 源文件
一个顶级实体 (message, enum, or extension)

尽可能减少 message、enum、extension 和 services 的数量，使重构更容易。移动已经拆分的文件比从将 messages 从一个文件中拆分出来容易得多。

遵循这种做法可以帮助你在实践中通过减少传递依赖项的大小缩短编译时间和减少二进制大小：当某些代码只需要使用一个枚举时，在 1-1-1 设计下，它可以仅依赖于定义该枚举的 .proto 文件，并避免偶然引入可能仅由同一文件中定义的另一条消息使用的大量传递依赖项。

在某些情况下，1-1-1 理想情况是不可能的（循环依赖项），不是理想的（概念上极度耦合的消息通过共置而具有可读性优势），或者某些缺点不适用（当 .proto 文件没有导入时，则不存在关于传递依赖项大小的技术问题）。与任何最佳实践一样，要明智地判断何时偏离指南。

在创建 gRPC 定义时，proto 文件的模块化非常重要。以下一组 proto 文件显示了模块化结构。

student_id.proto

edition = "2023";

package my.package;

message StudentID {
  string value = 1;
}

full_name.proto

edition = "2023";

package my.package;

message FullName {
  string family_name = 1;
  string given_name = 2;
}

student.proto

edition = "2023";

package my.package;

import "student_id.proto";
import "full_name.proto";

message Student {
  StudentId id = 1;
  FullName name = 2;
}

create_student_request.proto

edition = "2023";

package my.package;

import "full_name.proto";

message CreateStudentRequest {
  FullName name = 1;
}

create_student_response.proto

edition = "2023";

package my.package;

import "student.proto";

message CreateStudentResponse {
  Student student = 1;
}

get_student_request.proto

edition = "2023";

package my.package;

import "student_id.proto";

message GetStudentRequest {
  StudentID id = 1;
}

get_student_response.proto

edition = "2023";

package my.package;

import "student.proto";

message GetStudentResponse {
  Student student = 1;
}

student_service.proto

edition = "2023";

package my.package;

import "create_student_request.proto";
import "create_student_response.proto";
import "get_student_request.proto";
import "get_student_response.proto";

service StudentService {
  rpc CreateStudent(CreateStudentRequest) returns (CreateStudentResponse);
  rpc GetStudent(GetStudentRequest) returns (GetStudentResponse);
}

服务定义和每条消息定义都位于各自的文件中，您可以使用包含来访问来自其他架构文件的消息。

在此示例中，Student、StudentID 和 FullName 是可在请求和响应中重复使用的域类型。顶级请求和响应 protos 对于每个 services+method 都是唯一的。

如果您稍后需要将 middle_name 字段添加到 FullName message，则无需使用该新字段更新每个单独的顶级消息。同样，如果您需要使用更多信息更新 Student，则所有请求和响应都会得到更新。此外，StudentID 可能会更新为多部分 ID。

最后，即使将 StudentID 等简单类型包装为 message 也意味着您已创建具有语义和合并文档的类型。对于像 FullName 这样的东西，您需要小心记录此 PII 的位置；这是不在多个顶级消息中重复这些字段的另一个优点。您可以在一个地方将这些字段标记为敏感字段并将其排除在日志记录之外。

凌云的博客

行胜于言