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

最近呢，在作 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 来实现路由调用就好了，可是，为了辅助他可以正常的调用，咱们就不得不实现更多的一些辅助功能了

能够来看一下个人基本的目录结构

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: 一名热爱动漫的攻城狮