干货 | Api 体系架构分享（上）

最近呢，在做 api 的设计

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

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

风格就不用说了，我们就用 restful 风格，接下来：

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

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

• 版本控制

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

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

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 来实现路由调用就行了，但是，为了辅助他能够正常的调用，我们就不得不实现更多的一些辅助功能了

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

Framework
    │
    ├── Auth        认证、鉴权模块
    │
    ├── Base        基础服务
    │
    ├── Client      各种端服务
    │
    ├── Common      公共组件
    │
    ├── Core        核心调度逻辑
    │
    ├── Coroutine   协程调度实现
    │
    ├── Exception   异常处理
    │
    ├── Http        协议实现
    │
    ├── Log         日志上报，监控模块
    │
    ├── Pool        连接池（资源池）
    │
    └── Resource    资源模型

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

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

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

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

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

---

OK 了，上篇就先写到这里吧，主要说了对于 server 框架以及 IDL 的设计选择思路

下篇呢，会主要对于 api 的版本控制，发布，以及一些自动化工具进行一些分享

From: 一名热爱动漫的攻城狮