Netflix 实用 API 设计 (上)
gRPC 如今被很多公司应用在大规模生产环境中,很多时候我们并不需要通过 RPC 请求所有数据,而只关心响应数据中的部分字段,Protobuf FieldMask 就可以帮助我们实现这一目的。本文介绍了 Netflix 基于 FieldMask 设计更高效健壮的 API 的实践,全文分两个部分,这是第一部分。原文:Practical API Design at Netflix, Part 1: Using Protobuf FieldMask[1]
背景
在 Netflix,我们大量使用 gRPC[2]进行后端通信。处理请求的时候,如果能够知道调用者对哪些字段感兴趣、哪些字段可以忽略,会非常有用。有些响应字段的计算代价可能很高,有些字段可能需要对其他服务进行远程调用。远程调用需要付出额外的开销:额外的延迟,更高的出错概率,并且消耗了网络带宽。我们怎么样才能理解哪些字段不需要在响应中提供给调用者,从而避免进行不必要的计算以及远程调用?在 GraphQL 中,可以通过字段选择器来实现。在 JSON:API 标准中,有一个类似的被称为 Sparse Fieldsets[3]的技术。我们在设计 gRPC API 的时候,能不能实现类似的功能?在 Netflix Studio Engineering[4],我们提供的解决方案是 protobuf FieldMask[5]。
《纸钞屋》(La casa de papel) / Netflix
Protobuf FieldMask
Protocol Buffers[6],简称 protobuf,是一种数据序列化机制。默认情况下,gRPC 使用 protobuf 作为它的 IDL(接口定义语言)和数据序列化协议。
FieldMask 是一个 protobuf 消息,有许多实用工具和约定用来处理 RPC 请求中包含的 FieldMask。FieldMask 消息包含一个名为paths
的字段,用于指定应该由读操作返回或由更新操作修改的字段。
示例:Netflix 工作室内容制作
《纸钞屋》(La casa de papel) / Netflix
我们假设有一个 Production 服务,可以用来管理工作室内容的生产(Studio Content Productions,在电影和电视行业中,术语 production[7]指的是制作电影的过程,而不是运行软件的环境)。
GetProduction
通过其唯一 ID 返回一个生产消息。一个作品包含多个字段,如:标题、格式、日程日期、脚本(又称剧本)、预算、情节等,不过我们将重点放在过滤日程日期和脚本上,这样可以让例子简单一点。
读取制作细节
假设我们想要使用GetProduction
API 获取特定产品(如“纸钞屋”)的制作信息。虽然产品有很多字段,但有些字段是从其他服务获取的,比如 Schedule 服务的返回的schedule
,或者 Script 服务返回的scripts
。
即使客户端忽略响应中的schedule
和scripts
字段,Production 服务仍然需要在每次调用GetProduction
时为 Schedule 和 Script 服务生成 RPC。如上所述,远程调用是有成本的。如果服务知道调用者真正关心哪些字段,就可以做出明智的决策,决定是否进行昂贵的调用、启动资源繁重的计算和/或调用数据库。在本例中,如果调用者只需要产品标题和产品格式,那么 Production 服务就可以避免对 Schedule 和 Script 服务进行远程调用。
此外,请求大量字段会使响应负载变得很大,而这对于带宽有限的移动应用来说,可能会造成问题。在这些情况下,消费者只请求他们需要的字段是一个很好的实践。
《纸钞屋》(La casa de papel) / Netflix
一个丑陋的解决这些问题的方法是添加额外的请求参数,如includeSchedule
和includeScripts
:
不过这种方法需要为每个开销较大的响应字段添加自定义的includeXXX
字段,对于嵌套字段就不太适用,而且还增加了请求的复杂性,最终使得维护和支持更困难。
在请求消息里添加 FieldMask
API 设计者可以在请求消息中添加field_mask
字段,而不是创建一次性的“include”字段:
消费者可以为希望在响应中接收的字段设置路径,如果消费者只对产品标题和格式感兴趣,他们可以设置路径为“title”和“format”的 FieldMask:
Masking fields
请注意,尽管本文代码示例是基于 Java 的,但所演示的概念适用于 protocol buffers 支持的任何语言。
如果消费者只需要上一个更新日程的人的标题和电子邮件,他们可以设置一个不同的字段掩码:
按照惯例,如果请求中没有包含 FieldMask,则应该返回所有字段。
Protobuf 字段名 vs 字段号
你可能已经注意到,FieldMask 中的路径是基于字段名指定的,但实际上,编码后的 protocol buffers 消息只包含字段号,而不包含字段名,因此(以及其他技术,比如用于签名类型编码的 ZigZag[8])protobuf 消息的空间效率更高。
为了理解字段号和字段名之间的区别,让我们详细了解一下 protobuf 是如何编码和解码消息的。
Production 消息的 protobuf 消息定义(.proto 文件)含有五个字段,每个字段都有一个类型、名称和数字。
当 protobuf 编译器(protoc)编译这个消息定义时,会根据我们选择的语言(示例中是 Java)创建代码。生成的代码包含用于定义消息的类,以及消息和字段描述符。描述符包含将消息编码和解码成二进制格式所需的所有信息。例如,它们包含字段编号、名称和类型。消息生成程序使用描述符将消息编码为传输格式。为了提高效率,二进制消息里只包含字段号和对应的值,不包括字段名。当使用者接收到消息时,它通过引用已编译的消息定义将字节流解码为对象(例如,Java 对象)。
如上所述,FieldMask 列出的是字段名,而不是数字。而在 Netflix,我们使用字段号,并通过 FieldMaskUtil.fromFieldNumbers()[9]辅助程序转换为字段名。fromFieldNumbers 方法利用已编译的消息定义将字段号转换为字段名,并创建 FieldMask。
但是,有一个很容易被忽略的限制:使用 FieldMask 会限制我们重命名消息字段的能力。重命名消息字段通常被认为是安全的操作,因为如上所述,字段名并没有被编码发送,而是基于消费者端的消息定义产生的。要是使用 FieldMask,字段名就会编码在消息的有效负载中被发送出去(在paths
字段值中)。
假设我们想将字段title
重命名为title_name
,并发布消息定义的 2.0 版:
在这个图中,生产者(服务器端)使用了新的描述符,字段 2 名为title_name
。通过网络发送的二进制消息包含字段号及其值。消费者仍然使用原始的描述符,其中字段号 2 名为title
,仍然能够通过字段号解码消息。
如果消费者不使用 FieldMask 请求字段,这种方法仍然可以工作的很好。不过一旦消费者使用 FieldMask 字段中的“title”路径进行调用,生产者将无法找到该字段。生产者的描述符中没有名为 title 的字段,所以不知道消费者要求的字段号是 2。
如上所见,如果一个字段被重命名,后台应该能够支持新的和旧的字段名,直到所有调用者都迁移到新的字段名(向后兼容)。
有多种解决方案可以处理这个问题:
使用 FieldMask 时,永远不要重命名字段。这是最简单的解决方案,但并不总是可行。
要求后端支持所有旧字段名。这解决了向后兼容性问题,但需要在后端添加额外的代码来跟踪所有历史字段名。
弃用旧字段并创建一个新字段而不是重命名。在我们的示例中,我们将创建新的 title_name,并设置字段号为 6。与前一个选项相比,这个选项的优点在于:允许生产者继续使用生成的描述符而不是自定义转换器;另外,可以让消费者很快察觉到某个字段已经被弃用了。
不管用哪个解决方案,最重要的是要记住,FieldMask 使字段名称成为 API 合约的一个组成部分。
在生产者(服务器)端使用 FieldMask
在生产者(服务器)端,可以使用 FieldMaskUtil.merge()[10]方法从响应负载中删除不必要的字段(第 8、9 行):
如果服务器代码需要知道哪些字段被请求,以避免进行外部调用、数据库查询或昂贵的计算,可以从 FieldMask paths 字段获得相关信息:
这段代码只在请求schedule
字段时调用makeExpensiveCallToScheduleServicemethod
(第 21 行),让我们仔细看一下这段代码。
(1)SCHEDULE_FIELD_NAME
常量包含字段名。在示例代码中使用消息类型 Descriptor[11]和 FieldDescriptor[12]按字段编号查找字段名。protobuf 字段名和字段号之间的区别请参考前面的介绍。
(2)FieldMaskUtil.normalize()[13]返回按字母顺序排序并删除了重复数据的 FieldMask(又称规范形式)。
(3)生成scheduleFieldRequested
的表达式(第 14 - 17 行)接受 FieldMask 路径流,将其映射为顶级字段流,如果顶级字段中包含SCHEDULE_FIELD_NAME
常量的值,则返回true
。
(4)只有当scheduleFieldRequested
为true
时,才会检索ProductionSchedule
。
如果需要为不同的消息和字段应用 FieldMask,可以考虑创建可重用的 helper 方法。例如,可以基于 FieldMask 和 FieldDescriptor 返回所有顶级字段的方法,判断字段是否出现在 FieldMask 中的方法,等等。
使用预构建的 FieldMask
有些访问模式可能比其他模式更常见,如果多个消费者都对同一个字段子集感兴趣,API 生产商可以为最常用的字段组合提供预构建的 FieldMask 客户端库。
提供预构建字段掩码简化了大多数常见场景的 API 使用,并让消费者可以灵活的为更具体的用例构建自己的字段掩码。
限制
使用 FieldMask 限制了重命名消息字段的能力
重复字段只允许出现在路径字符串的最后一个位置,这意味着不能在列表中选择(屏蔽)单个子字段。在可预见的未来,这种情况可能会改变,因为最近批准的谷歌 API 改进建议 AIP-161 Field masks[14]包含了对重复字段的通配符支持。
最后
Protobuf FieldMask 是一个简单而强大的概念,有助于使 API 更健壮,服务实现更高效。
本文介绍了 Netflix Studio Engineering 如何以及为什么使用 FieldMask 来读取数据,下一篇文章将介绍如何使用 FieldMask 进行更新和删除操作。
References:
[2] https://grpc.io/
[3] https://jsonapi.org/format/#fetching-sparse-fieldsets
[4] https://netflixtechblog.com/netflix-studio-engineering-overview-ed60afcfa0ce
[6] https://developers.google.com/protocol-buffers
[7] https://en.wikipedia.org/wiki/Filmmaking
[8] https://en.wikipedia.org/wiki/Variable-length_quantity#Zigzag_encoding
[11] https://developers.google.com/protocol-buffers/docs/reference/java/com/google/protobuf/Descriptors
你好,我是俞凡,在 Motorola 做过研发,现在在 Mavenir 做技术工作,对通信、网络、后端架构、云原生、DevOps、CICD、区块链、AI 等技术始终保持着浓厚的兴趣,平时喜欢阅读、思考,相信持续学习、终身成长,欢迎一起交流学习。微信公众号:DeepNoMind
版权声明: 本文为 InfoQ 作者【俞凡】的原创文章。
原文链接:【http://xie.infoq.cn/article/9177627e96925ef1bd53ee01c】。
本文遵守【CC-BY 4.0】协议,转载请保留原文出处及本版权声明。
评论