API 工程化分享 _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 IDLgRPC 从协议缓冲区使用接口定义语言 (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 工程化分享】
集中式仓库最大的风险是什么呢？是谁都可以更改
大仓的核心是放弃了读权限的管理，针对写操作是有微观管理的，就是你可以看到我的 API 声明，但是你实际上调用不了，但是对于迁入 check in ，提到主干，你可以在不同层级加上 owner 文件，它里面会描述谁可以合并代码，或者谁负责 review ，两个角色，那就可以方便利用 gitlab 的 hook 功能，然后用 owner 文件做一些细粒度的权限管理，针对目录级别的权限管理
最终你的同事不能随便迁入，就是说把文件的写权限， merge 权限关闭掉，只允许通过 merge request 的评论区去回复一些指令，比方说 lgtm（looks good to me），表示 review 通过，然后你可以回复一个 Approve ，表示这个代码可以被成功 check in ，这样来做一些细粒度的权限检验