近呢,在做 api 的设计

对于设计,一方面是对于后端 server 框架的设计,另一方面呢,是对于整个 api 体系的设计

在这里呢,我们来理理思路,先来大致分一下块

风格就不用说了,我们就用 restful 风格,接下来:

• IDL,也就是我们所说的接口描述语言

• server 框架,整个 api 服务的核心驱动

• 版本控制

• 还有一些辅助工具,比如说,自动化工具、认证授权、监控上报、日志记录、检索等等

然后呢,我们就来分别说说设计开发中的一些感触

IDL

顾名思义,IDL 是我们整个 api 体系的核心模型,基本上所有的东西都是要基于我们的 IDL 的,在使用的选择上有很多,比如Yaml、Json、xml、PB 等等,这些都可以作为接口描述语言,同时呢,各有优劣,在这里呢,我们考虑了以下这几种:

• Json:Json 是一种稳定并得到广泛应用的序列化格式,浏览器包含对该格式的原生解析能力,浏览器内建调试器也能很好地显示这种内容。唯一不足在于要具备 Json 解析器/序列器,好在基本所有语言都已提供。使用 Json 最主要的麻烦在于每条信息会重复包含属性名,导致传输效率低下,同时呢,Json 对于一些 api 开发过程中可能出现的特殊需求可能会处理不好,比如说,字段之间的依赖关系,就不容易描述出来

• Yaml:使用 Yaml 来定义我们的 api 模型的话,可谓是非常的简洁明了,但是对于 api 模型中的一些复杂结构,以及一些字段的自检测,并不能够很好的支持,同时,这个格式也不容易在开发中进行约定,可能会引起一些不必要的麻烦

• PB:PB 全称是 Protocol Buffers,是谷歌创建的一种基于二进制连接格式的接口描述语言。在解析和网络传输方面Protocol Buffers 更高效,并经历了谷歌高负荷环境的考验,不足在于一些语言的支持并不是很好,主要还是对于 C、python 和 java 的支持,并且呢,在 .proto 文件的共享和编译方面会产生些许额外开发负担

• xml:这个大家就都非常熟悉了,相对于 Json 和 Yaml,xml 就显得有些笨重了,但是 xml 能够很好的应用于各种特殊的场景,能够根据不断的线上需求进一步的扩展,并且可以直接通过 xsd 进行自校验,从功能上来讲,或许会更加完善一些

因为 IDL 是我们 api 的核心,以后的各项业务基本都要围绕 IDL 展开,所以需要能够功能完善,便于扩展,并且在开发中能够有一些自动化的工具来进行约束,so,最终呢,还是决定采用 xml 的形式

server 框架

核心代码非常的简单,只需要写一个 route 来实现路由调用就行了,但是,为了辅助他能够正常的调用,我们就不得不实现更多的一些辅助功能了

可以来看一下我的基本的目录结构

同时呢,开发过程中要降低各模块间依赖关系,就比如说,与其 new 一个对象,不如采用 set 的方式来解耦,预期继承,不如采用组合的方式,保证各个模块的独立性,同时呢各模块间又要有一个通讯通道

为了实现一些特殊的需求,我们采用协程调度来实现非阻塞 IO,当然,这里我们就需要实现一个单独的服务端口监听,就好比 swoole 或是 workerman 那样,编写独立的服务进程

ok,上面也提到了,核心代码只需要实现一个 route 路由就行了,但是在路由前后,要记得留出认证、鉴权接口,同时呢,对于运行时的异常也要及时捕获上报,同时记入日志,方便调试

对了,除了这些 server 服务依赖,数据也要注意哦,最好是能够在原始数据之上再单独抽离出来一层数据接口层,不要直接操作原始数据

这些核心服务完成后,剩下的就是客户端和服务端代码,这个就可以根据实际的服务去自由发挥了,对于 api,我们也可以把客户端代码称之为 SDK,同时呢,为了方便以后的开发维护,可以统一编写自动化工具生成,对于不同语言对应的做支持

对于设计,一方面是对于后端 server 框架的设计,另一方面呢,是对于整个 api 体系的设计

在这里呢,我们来理理思路,先来大致分一下块

风格就不用说了,我们就用 restful 风格,接下来:

• IDL,也就是我们所说的接口描述语言

• server 框架,整个 api 服务的核心驱动

• 版本控制

• 还有一些辅助工具,比如说,自动化工具、认证授权、监控上报、日志记录、检索等等

上次呢,讲了 IDL 和 server 框架的设计思路

这次呢,来吧剩下两个也给说说

版本控制

说到版本控制,大多数人的大脑中都一定会立刻想到 git 和 svn 吧,只可惜,这次的主角可不是他们

虽说 git 和 svn 虽好,对于一些项目也能够进行很好的开发,但是呢,对于某些场景,还是有些 hold 不住的

比如,我们来举一个场景:

• 现在我们的源码大约有 500M,然后呢,采用的是分支开发,主干发布,但是呢,因为我们是提供中间层 service 的,迭代周期很短,对于一些特殊的客户,会时常有些特殊的逻辑处理,每个开发者可能会有好几个分支进行开发,这个样子的话,对于这些特殊逻辑,特殊版本的管理就非常的不方便,而且,因为每次都要拉出来一个分支,然后改动可能非常小,这就造成了非常大量的冗余量。

于是,这个场景中,冗余量、大量迭代版本的管理,就上升到了我们的一个主要问题

如何解决呢?

单体代码库

在这里,我们引入一个节点(标签)的概念,先来说一下整体思路

现在,我们就抛弃 git 和 svn 的思想,把所有的代码都放在一起,通过控制 节点粒度 来控制整体的冗余

首先,节点粒度我们先设定为以文件为单位,同时呢,约定我们的命名规范,文件名.节点标识.php,例如 Test.v1.php

接下来呢,就会有我们原始的版本,在这个原始的版本里面,所有的文件都是 base 节点

所有的文件都会有一个父节点,最终都是继承与 base 节点的

当我们需要迭代到 1.0.1 版本的时候,我们只要把需要改动的文件 copy 一个副本,然后按规范命名,接着只需对于这一个文件进行改动,这样,冗余的粒度就控制在了这个文件内

大大减少冗余的同时,还大大的提高了代码的复用,避免了菱形依赖,不同团队间的跨团队协作也变得更加灵活

接下来,我们怎么能够正常调用呢?

所以说,这种单体代码库需要一个路由引擎来驱动,这就要我们根据实际情况来实现了,可以直接根据节点表示来路由,也可以在中间加一层路由映射表,这就看具体需求了

同理,我们可以进一步调整节点粒度,来控制整体的冗余,比如,粒度细化到接口级别

~~~~~~ 萌萌哒的分割线 ~~~~~~~~~

好了,下面就来分析一下这种单体代码库的优劣

优点:

• 统一版本控制

• 广泛地代码共享和复用

• 简化依赖管理,避免菱形依赖

• 原子修改

• 大规模重构

• 跨团队协作

• 灵活的团队边界和代码所有权

• 代码可见性以及清晰的树形结构提供了隐含的团队命名空间

但是呢,随着代码量的增加,也会出现以下问题:

• 单体模型让代码结构更容易理解,但却让代码发现变得更困难

• 开发人员需要能够查看代码库,找到相关程序库,并看看如何使用它们以及谁编写了它们。这就需要有代码搜索和代码浏览工具

• 依赖重构和代码清理辅助工具,定期对无用代码进行清理

• 版本管理的重心转移到了冗余控制上

所以说呢,对于管理,我们就需要开发一套额外的自动化工具了

具体关于单体代码库的细节也可以查看这篇文章:

ok,关于版本控制就说这么多,接下来就是最后的一些自动化工具以及辅助工程了

自动化工具

为什么需要自动化工具呢?

一方面,节约我们维护开发的成本,对于一些可以自动化的操作就没必要去人工操作

另一方面呢,也是为了减少人工操作中可能带来的一些失误

就比如我们现在的 api,都需要哪些自动化工具呢?

• SDK 自动生成工具:对于我们提供给用户的 SDK,我们当然不希望每次迭代都要重新给用户写一份新的,所以说呢,通过自动化工具,自动生成各种语言调用的 SDK 是很有必要的

• IDL 解析工具:我们在读取数据的时候,肯定不能每次都去解析 IDL 的结构,这样会带来太多不必要的额外开销,所以说呢,我们需要提前解析 IDL 进行缓存,从而提高我们调用的速度,而这个解析生成的过程,就交给工具来完成了

• 代码库搜索工具:因为我们采用了单体代码库,所以慢慢的代码越来越多,代码搜索工具就变的必不可少了

• 代码发现工具:也是为了维护代码库,定期发现清理无用代码

至于一些其他的自动化工具,就根据大家的具体需求去实现吧,也就不一一列举了

其他辅助工具

比如说,认证、授权、监控、上报、日志等等

这些在 server 框架设计的同时就都要考虑进去,什么时候需要上报,如何设定日志格式从而使得我们能够更加方便的去维护等等

对于日志管理,可以使用一些开源系统快速搭建

比如,logstash 来搭建日志管理系统,通过 ElasticSearch 来进行索引检索服务,然后呢使用 kibana作为分析和可视化平台