1-1-1 最佳实践

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

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

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

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

遵循此实践可以通过减少实际中传递依赖项的大小来帮助构建时间和二进制文件大小：当某些代码只需要使用一个枚举时，在 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 是可在请求和响应中重用的领域类型。顶级请求和响应 proto 是每个服务和方法唯一的。

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

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