API 工程化分享

概要

本文是学习B站毛剑老师的《API 工程化分享》的学习笔记，分享了 gRPC 中的 Proto 管理方式，Proto 分仓源码方式，Proto 独立同步方式，Proto git submodules 方式，Proto 项目布局，Proto Errors，服务端和客户端的 Proto Errors，Proto 文档等等

目录

• Proto IDL Management
• IDL Project Layout
• IDL Errors
• IDL Docs

Proto IDL Management

• Proto IDL
• Proto 管理方式
• Proto 分仓源码方式
• Proto 独立同步方式
• Proto git submodules 方式

Proto IDL

gRPC 从协议缓冲区使用接口定义语言 (IDL)。协议缓冲区 IDL 是一种与平台无关的自定义语言，具有开放规范。 开发人员会创作 .proto 文件，用于描述服务及其输入和输出。 然后，这些 .proto 文件可用于为客户端和服务器生成特定于语言或平台的存根，使多个不同的平台可进行通信。 通过共享 .proto 文件，团队可生成代码来使用彼此的服务，而无需采用代码依赖项。

Proto 管理方式

煎鱼的一篇文章：真是头疼，Proto 代码到底放哪里？

文章中经过多轮讨论对 Proto 的存储方式和对应带来的优缺点，一共有如下几种方案：

• 代码仓库
• 独立仓库
• 集中仓库
• 镜像仓库

镜像仓库

在我自己的微服务仓库里面，有一个 Proto 目录，就是放我自己的 Proto，然后在我提交我的微服务代码到主干或者某个分支的时候，它可能触发一个 mirror 叫做自动同步，会镜像到这个集中的仓库，它会帮你复制过去，相当于说我不需要把我的源码的 Proto 开放给你，同时还会自动复制一份到集中的仓库

在煎鱼的文章里面的集中仓库还是分了仓库的，B站大仓是一个统一的仓库。为什么呢？因为比方像谷歌云它整个对外的 API 会在一个仓库，不然你让用户怎么找？到底要去哪个 GitHub 下去找？有这么多 project 怎么找？根本找不到，应该建统一的一个仓库，一个项目就搞定了

我们最早衍生这个想法是因为无意中看到了 Google APIs 这个仓库。大仓可以解决很多问题，包括高度代码共享，其实对于 API 文件也是一样的，集中在一个 Repo 里面，很方便去检索，去查阅，甚至看文档，都很方便

我们不像其他公司喜欢弄一个 UI 的后台，我们喜欢 Git，它很方便做扩展，包括 CICD 的流程，包括 coding style 的 check，包括兼容性的检测，包括 code review 等等，你都可以基于 git 的扩展，gitlab 的扩展，GitHub 的一些 actions，做很多很多的工作

Proto 分仓源码方式

过去为了统一检索和规范 API，我们内部建立了一个统一的 bapis 仓库，整合所有对内对外 API。它只是一个申明文件。

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

集中式仓库最大的风险是什么呢？是谁都可以更改

大仓的核心是放弃了读权限的管理，针对写操作是有微观管理的，就是你可以看到我的 API 声明，但是你实际上调用不了，但是对于迁入 check in，提到主干，你可以在不同层级加上 owner 文件，它里面会描述谁可以合并代码，或者谁负责 review，两个角色，那就可以方便利用 gitlab 的 hook 功能，然后用 owner 文件做一些细粒度的权限管理，针对目录级别的权限管理

最终你的同事不能随便迁入，就是说把文件的写权限，merge 权限关闭掉，只允许通过 merge request 的评论区去回复一些指令，比方说 lgtm（looks good to me），表示 review 通过，然后你可以回复一个 approve，表示这个代码可以被成功 check in，这样来做一些细粒度的权限检验

怎么迁入呢？我们的想法是在某一个微服务的 Proto 目录下，把自己的 Proto 文件管理起来，然后自动同步进去，就相当于要写一个插件，可以自动复制到 API 仓库里面去。做完这件事情之后，我们又分了 api.go，api.java，git submodule，就是把这些代码使用 Google protobuf，protoc 这个编译工具生成客户端的调用代码，然后推到另一个仓库࿰