1-1-1 最佳实践

所有 proto 定义都应该在一个文件中包含一个顶级元素和构建目标。

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

  • 一个 proto_library 构建规则
  • 一个源 .proto 文件
  • 一个顶级实体（消息、枚举或扩展）

尽可能减少消息、枚举、扩展和服务的数量，这使得重构更容易。当文件分离时，移动文件比从包含其他消息的文件中提取消息容易得多。

遵循此实践可以通过减少实际中传递依赖项的大小来帮助构建时间和二进制文件大小：当某些代码只需要使用一个枚举时，在 1-1-1 设计下，它可以仅依赖于定义该枚举的 .proto 文件，并避免意外地引入可能仅由同一文件中定义的其他消息使用的大量传递依赖项。

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

proto 模式文件模块化很重要的一个地方是在创建 gRPC 定义时。以下 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);
}

服务定义和每个消息定义都在其自己的文件中，并且您使用 include 来从其他模式文件中访问消息。

在此示例中，Student、StudentID 和 FullName 是可在请求和响应中重复使用的域类型。顶级请求和响应 proto 对每个服务+方法都是唯一的。

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

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