Go语言进阶(七)API设计

gRPC

gRPC是什么可以用官网的一句话来概括:“A high-performance, open-source universal RPC framework

  • 多语言:语言中立,支持多种语言
  • 轻量级、高性能:序列化支持 PB(Protocol Buffer)JSONPB 是一种语言无关的高性能序列化框架。
  • 可插拔
  • IDL:基于文件定义服务,通过 proto3 工具生成指定语言的数据结构、服务端接口以及客户端 Stub
  • 设计理念
  • 移动端:基于标准的 HTTP2 设计,支持双向流、消息头压缩、单 TCP 的多路复用、服务端推送等特性,这些特性使得 gRPC 在移动端设备上更加省电和节省网络流量。

image-20211213141408161

  • 服务而非对象、消息而非引用:促进微服务的系统间粗粒度消息交互设计理念。
  • 负载无关的:不同的服务需要使用不同的消息类型和编码,例如 protocol buffersJSONXMLThrift
  • 流: Streaming API
  • 阻塞式和非阻塞式:支持异步和同步处理在客户端和服务端间交互的消息序列。
  • 元数据交换:常见的横切关注点,如认证或跟踪,依赖数据交换。
  • 标准化状态码:客户端通常以有限的方式响应 API 调用返回的错误。

不要过早关注性能问题,先标准化。

API Project (管理API项目)

B站为例,参考了谷歌等大厂的案例:

  • https://github.com/googleapis/googleapis
  • https://github.com/envoyproxy/data-plane-api
  • https://github.com/istio/api

为了统一检索和规范 API,B站内部建立了一个统一的 bapis 仓库,整合所有对内对外 API。完成几个目标:

  • API 仓库,方便跨部门协作。
  • 版本管理,基于 git 控制。
  • 规范化检查,API lint
  • API design review,变更 diff
  • 权限管理,目录 OWNERS

image-20211213142837221

API Project Layout(API项目布局)

image-20211213143054330

项目中定义 proto,以 api 为包名根目录:

image-20211213142921054

在统一仓库中管理 proto ,以仓库为包名根目录:

image-20211213142937467

API Compatibility(API 兼容性)

向后兼容(非破坏性)的修改

  • API 服务定义添加 API 接口,从协议的角度来看,这始终是安全的。
  • 给请求消息添加字段,只要客户端在新版和旧版中对该字段的处理不保持一致,添加请求字段就是兼容的。
  • 给响应消息添加字段,在不改变其他响应字段的行为的前提下,非资源(例如,ListBooksResponse)的响应消息可以扩展而不必破坏客户端的兼容性。即使会引入冗余,先前在响应中填充的任何字段应继续使用相同的语义填充。

向后不兼容(破坏性)的修改

  • 删除或重命名服务,字段,方法或枚举值,从根本上说,如果客户端代码可以引用某些东西,那么删除或重命名它都是不兼容的变化,这时必须修改 major 版本号。
  • 修改字段的类型,即使新类型是传输格式兼容的,这也可能会导致客户端库生成的代码发生变化,因此必须增加major 版本号。 对于编译型静态语言来说,会容易引入编译错误。
  • 修改现有请求的可见行为,客户端通常依赖于 API 行为和语义,即使这样的行为没有被明确支持或记录。 因此,在大多数情况下,修改 API 数据的行为或语义将被消费者视为是破坏性的。如果行为没有加密隐藏,您应该假设用户已经发现它,并将依赖于它。
  • 给资源消息添加 读取/写入 字段

API Naming Conventions (API 命名约定)

包名为应用的标识(APP_ID),用于生成 gRPC 请求路径,或者 proto 之间进行引用 Message。文件中声明的包名称应该与产品和服务名称保持一致。带有版本的 API 的软件包名称必须以此版本结尾。

  • my.package.v1,为 API 目录,定义service相关接口,用于提供业务使用。

image-20211213143624421

image-20211213143726185

API Primitive Fields (API原始字段)

gRPC 默认使用 Protobuf v3 格式,因为去除了 requiredoptional 关键字,默认全部都是 optional 字段。如果没有赋值的字段,默认会基础类型字段的默认值,比如 0 或者 “”

image-20211213144114674

Protobuf v3 中,建议使用:https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/wrappers.proto

Warpper 类型的字段,即包装一个 message,使用时变为指针。

image-20211213144028487

API Errors(API 错误)

使用一小组标准错误配合大量资源, 例如,服务器没有定义不同类型的“找不到”错误,而是使用一个标准 google.rpc.Code.NOT_FOUND 错误代码并告诉客户端找不到哪个特定资源。

image-20211213144439053

错误传播,如果您的 API 服务依赖于其他服务,则不应盲目地将这些服务的错误传播到您的客户端。在翻译错误时,我们建议执行以下操作:

  • 隐藏实现详细信息和机密信息。
  • 调整负责该错误的一方。例如,从另一个服务接收 INVALID_ARGUMENT 错误的服务器应该将 INTERNAL 传播给它自己的调用者。

全局错误码,是松散、易被破坏契约的,基于我们上述讨论的,在每个服务传播错误的时候,做一次翻译,这样保证每个服务 + 错误枚举,应该是唯一的,而且在 proto 定义中是可以写出来文档的。

image-20211213144742169

image-20211213144805983

API Design(API设计)

刚开始设计接口:一个更新接口,但是我们无法控制需要修改那些字段,那么接收方就会更新所有字段。

我们引入了FieldMask 部分更新的方案,客户端可以执行需要更新的字段信息:

  • paths: "author"
  • paths: "submessage.submessage.field"
  • FieldMask 默认应用到 “所有字段”

需要更新的字段,写道mask字段中。