Netflix API 设计实践: 使用FieldMask
The following article is from emc的随笔 Author emc
背景
在 Netflix，我们大量使用 gRPC 来进行后端到后端的通信。当我们处理请求时，了解调用者感兴趣的字段以及他们忽略的字段通常是有益的。某些响应字段的计算成本可能很高，某些字段可能需要远程调用其他服务。远程调用从来都不是免费的；它们会带来额外的延迟，增加出错的可能性，并消耗网络带宽。我们如何了解不需要为调用者在响应中提供哪些字段，从而避免进行不必要的计算并减少调用？使用GragpQL的时候，可以通过字段选择器来完成。在 JSON:API 标准中，一种类似的技术称为稀疏字段集。在设计 gRPC API 时，我们如何实现类似的功能？我们在 Netflix Studio Engineering 中使用的解决方案是 protobuf FieldMask
Protobuf FieldMask
Protocol Buffers，或简称 protobuf，是一种数据序列化机制。默认情况下，gRPC 使用 protobuf 作为其 IDL（接口定义语言）和数据序列化协议。
FieldMask 是一个 protobuf 消息。当消息出现在 RPC 请求中时，有许多实用程序和约定来说明如何使用此消息。FieldMask 消息包含一个名为 paths 的字段，用于指定应该由读取操作返回或由更新操作修改的字段。
message FieldMask {
// The set of field mask paths.
repeated string paths = 1;
}
Example: Netflix Studio Production
假设有一个制作服务管理工作室内容制作（在电影和电视行业，制作一词是指制作电影的过程，而不是运行软件的环境）。
// Contains Production-related information
message Production {
string id = 1;
string title = 2;
ProductionFormat format = 3;
repeated ProductionScript scripts = 4;
ProductionSchedule schedule = 5;
// ... more fields
}
service ProductionService {
// returns Production by ID
rpc GetProduction (GetProductionRequest) returns (GetProductionResponse);
}
message GetProductionRequest {
string production_id = 1;
}
message GetProductionResponse {
Production production = 1;
}
GetProduction 通过其唯一 ID 返回生产消息。一个作品包含多个字段，例如：标题、格式、时间表日期、脚本（也称为剧本）、预算、剧集等，我们使用这个简单的示例，并在请求制作时专注于过滤掉时间表日期和脚本。
获取产品细节
假设我们想要使用 GetProduction API 获取特定作品的制作信息，例如“La Casa De Papel”。虽然作品有许多字段，但其中一些字段是从其他服务返回的，例如来自 Schedule 服务的 schedule 或来自脚本服务的脚本。
每次调用 GetProduction 时，即使客户端忽略响应中的调度和脚本字段，生产服务也会对调度和脚本服务进行 RPC。上文提到，远程调用不是免费的。如果服务知道哪些字段对调用者很重要，它可以就进行昂贵的调用、启动资源密集型计算和/或调用数据库做出明智的决定。在这个例子中，如果调用者只需要制作标题和制作格式，制作服务可以避免远程调用 Schedule 和 Script 服务。
此外，请求大量字段会使响应负载变得庞大。这可能会成为某些应用程序的问题，例如，在网络带宽有限的移动设备上。在这些情况下，消费者最好只请求他们需要的字段。
解决这些问题的一种简单方法是添加额外的请求参数，例如 includeSchedule 和 includeScripts：
// Request with one-off "include" fields, not recommended
message GetProductionRequest {
string production_id = 1;
bool include_format = 2;
bool include_schedule = 3;
bool include_scripts = 4;
}
这种方法需要为每个昂贵的响应字段添加一个自定义 includeXXX 字段，并且不适用于嵌套字段。它还增加了请求的复杂性，最终使维护和支持更具挑战性
在请求体中添加FieldMask
API 设计人员可以将 field_mask 字段添加到请求消息中，而不是创建一次性的“包含”字段：
import "google/protobuf/field_mask.proto";
message GetProductionRequest {
string production_id = 1;
google.protobuf.FieldMask field_mask = 2;
}
消费者可以为他们期望在响应中接收的字段设置路径。如果消费者只对产品标题和格式感兴趣，他们可以使用路径“标题”和“格式”设置 FieldMask：
FieldMask fieldMask = FieldMask.newBuilder()
.addPaths("title")
.addPaths("format")
.build();
GetProductionRequest request = GetProductionRequest.newBuilder()
.setProductionId(LA_CASA_DE_PAPEL_PRODUCTION_ID)
.setFieldMask(fieldMask)
.build();
请注意，尽管本文中的代码示例是用 Java 编写的，但演示的概念适用于protobuffer支持的任何其他语言。如果消费者只需要最后一个更新时间表的人的标题和电子邮件，他们可以设置不同的字段掩码：
FieldMask fieldMask = FieldMask.newBuilder()
.addPaths("title")
.addPaths("schedule.last_updated_by.email")
.build();
GetProductionRequest request = GetProductionRequest.newBuilder()
.setProductionId(LA_CASA_DE_PAPEL_PRODUCTION_ID)
.setFieldMask(fieldMask)
.build();
按照惯例，如果请求中不存在 FieldMask，则应返回所有字段.
Protobuf Field Names vs Field Numbers
您可能会注意到 FieldMask 中的路径是使用字段名称指定的，而在网络上，protocol buffers消息仅包含字段编号，而不包含字段名称。这（以及其他一些技术，如用于有符号类型的 ZigZag 编码）使 protobuf 消息能节省空间。
要了解字段编号和字段名称之间的区别，我们来详细了解一下 protobuf 是如何对消息进行编码和解码的。
我们的 protobuf 消息定义（.proto 文件）包含具有五个字段的生产消息。每个字段都有类型、名称和编号。
// Message with Production-related information
message Production {
string id = 1;
string title = 2;
ProductionFormat format = 3;
repeated ProductionScript scripts = 4;
ProductionSchedule schedule = 5;
}
当 protobuf 编译器 (protoc) 编译此消息定义时，它会以您选择的语言（在我们的示例中为 Java）创建代码。此生成的代码包含已定义消息的类，以及消息和字段描述符。描述符包含将消息编码和解码为其二进制格式所需的所有信息。例如，它们包含字段编号、名称、类型。消息生产者使用描述符将消息转换为其有线格式。为提高效率，二进制消息仅包含字段数字-值对。不包括字段名称。当消费者接收到消息时，它通过引用已编译的消息定义将字节流解码为一个对象（例如，Java 对象）。
如上所述，FieldMask列出了字段名，而不是数字。在Netflix，我们使用字段编号，并使用FieldMaskUtil.fromFieldNumbers()实用方法将其转换为字段名。这个方法利用编译后的消息定义，将字段号转换为字段名，并创建一个FieldMask。
FieldMask fieldMask = FieldMaskUtil.fromFieldNumbers(Production.class,
Production.TITLE_FIELD_NUMBER,
Production.FORMAT_FIELD_NUMBER);
GetProductionRequest request = GetProductionRequest.newBuilder()
.setProductionId(LA_CASA_DE_PAPEL_PRODUCTION_ID)
.setFieldMask(fieldMask)
.build();
但是，有一个容易忽略的限制：使用 FieldMask 会限制您重命名消息字段的能力。重命名消息字段通常被认为是一种安全操作，因为如上所述，字段名称不是在线发送的，而是使用消费者端的字段编号派生的。使用 FieldMask，字段名称在消息有效负载中（在路径字段值中）发送并变得重要.
假设我们要将字段标题重命名为 title_name 并发布我们的消息定义的 2.0 版本：
message Production {
string id = 1;
string title_name = 2; // this field used to be "title"
ProductionFormat format = 3;
repeated ProductionScript scripts = 4;
ProductionSchedule schedule = 5;
}
在此图表中，生产者（服务器）使用新的描述符，字段编号 2 名为 title_name。通过线路发送的二进制消息包含字段编号及其值。消费者仍然使用原始描述符，其中第 2 个字段称为title。它仍然能够通过字段编号解码消息。
如果消费者不使用 FieldMask 来请求该字段，这将很有效。如果消费者使用 FieldMask 字段中的“title”路径进行调用，生产者将无法找到该字段。生产者在其描述符中没有名为 title 的字段，因此它不知道消费者请求了第 2 个字段.
如我们所见，如果一个字段被重命名，后端应该能够支持新旧字段名称，直到所有调用者迁移到新字段名称（向后兼容性问题）
有多种方法可以解决此限制：
使用 FieldMask 时切勿重命名字段。这是最简单的解决方案，但并非总是可行. 要求后端支持所有旧的字段名称。这解决了向后兼容性问题，但需要在后端添加额外代码来跟踪所有历史字段名称 弃用旧的并创建一个新字段而不是重命名。在我们的示例中，我们将创建第 6 个 title_name 字段。与前一个选项相比，此选项具有一些优点：它允许生产者继续使用生成的描述符而不是自定义转换器；此外，弃用一个字段使其在消费者方面更加突出
message Production {
string id = 1;
string title = 2 [deprecated = true]; // use "title_name" field instead
ProductionFormat format = 3;
repeated ProductionScript scripts = 4;
ProductionSchedule schedule = 5;
string title_name = 6;
}
无论解决方案如何，重要的是要记住 FieldMask 使字段名称成为 API 约束的组成部分。
在服务端使用FieldMask
在生产者（服务器）端，可以使用 FieldMaskUtil.merge() 方法（第 ##8 和 9 行）从响应负载中删除不必要的字段。
@Override
public void getProduction(GetProductionRequest request,
StreamObserver<GetProductionResponse> response) {
Production production = fetchProduction(request.getProductionId());
FieldMask fieldMask = request.getFieldMask();
Production.Builder productionWithMaskedFields = Production.newBuilder();
FieldMaskUtil.merge(fieldMask, production, productionWithMaskedFields);
GetProductionResponse response = GetProductionResponse.newBuilder()
.setProduction(productionWithMaskedFields).build();
responseObserver.onNext(response);
responseObserver.onCompleted();
}
如果服务器代码知道客户端不需要哪些字段以避免进行外部调用、数据库查询或昂贵的计算，则可以从 FieldMask 路径字段中获取此信息：
private static final String FIELD_SEPARATOR_REGEX = "\\.";
private static final String MAX_FIELD_NESTING = 2;
private static final String SCHEDULE_FIELD_NAME = // (1)
Production.getDescriptor()
.findFieldByNumber(Production.SCHEDULE_FIELD_NUMBER).getName();
@Override
public void getProduction(GetProductionRequest request,
StreamObserver<GetProductionResponse> response) {
FieldMask canonicalFieldMask =
FieldMaskUtil.normalize(request.getFieldMask()); // (2)
boolean scheduleFieldRequested = // (3)
canonicalFieldMask.getPathsList().stream()
.map(path -> path.split(FIELD_SEPARATOR_REGEX, MAX_FIELD_NESTING)[0])
.anyMatch(SCHEDULE_FIELD_NAME::equals);
if (scheduleFieldRequested) {
ProductionSchedule schedule =
makeExpensiveCallToScheduleService(request.getProductionId()); // (4)
...
}
...
}
仅当请求调度字段时，此代码才会调用 makeExpensiveCallToScheduleService 方法（第 21 行）。让我们更详细地研究这个代码示例。
SCHEDULE_FIELD_NAME 常量包含字段的名称。此代码示例使用消息类型 Descriptor 和 FieldDescriptor 按字段编号查找字段名称。protobuf 字段名称和字段编号之间的区别在上面的 Protobuf 字段名称与字段编号部分中进行了描述. FieldMaskUtil.normalize() 返回具有按字母顺序排序和去重的字段路径（又名规范形式）的 FieldMask。 产生 scheduleFieldRequestedvalue 的表达式（第 ##14 - 17 行）采用 FieldMask 路径流，将其映射到顶级字段流，如果顶级字段包含 SCHEDULE_FIELD_NAME 常量的值，则返回 true。 仅当 scheduleFieldRequested 为 true 时才检索 ProductionSchedule
如果您最终将 FieldMask 用于不同的消息和字段，请考虑创建可重用的实用程序助手方法。例如，基于 FieldMask 和 FieldDescriptor 返回所有顶级字段的方法，如果 FieldMask 中存在字段则返回的方法等。
预先构建FieldMask
某些访问模式可能比其他访问模式更常见。如果多个消费者对相同的字段子集感兴趣，API 生产者可以提供带有为最常用字段组合预构建的 FieldMask 的客户端库。
提供预先构建的字段掩码可简化最常见场景的 API 使用，并使消费者能够灵活地为更具体的用例构建自己的字段掩码。
限制
使用 FieldMask 可能会限制您重命名消息字段的能力（在 Protobuf 字段名称与字段编号部分中描述） 重复字段只允许在路径字符串的最后位置。这意味着您不能在列表内的消息中选择（屏蔽）单个子字段。这在可预见的未来可能会发生变化，因为最近批准的 Google API 改进提案 AIP-161 字段掩码添加了对重复字段通配符的支持。