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);
}

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

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

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

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