RestQL:现代化的 API 开发方式
koa-restql 已经在 github 开源并在 npm 发布。感兴趣的同学可以前往围观一下。欢迎 Pull Request,同时热烈欢迎 Star。
在现代的业务系统中,后端开发工作基本上可以被拆分为三项:
- 接口鉴权。例如判断是不是当前系统的用户,以及该用户是否有权限访问接口。
- 与其他系统的交互。例如调用第三方的服务,或内部搭建的其他服务。
- 数据操作。基本上所有需要持久化存储的系统都会在这项工作上耗费大量时间。
本文将介绍如何利用 RestQL 来非常有效地减少「数据操作」相关的工作量。
现状与挑战
我们先来做个假设。
- 假设系统中有 60 张表,每张表对应的接口都要有四种 CRUD 的 API。那么就需要后端工程师写60 * 4 = 240个API。
- 假设上述 60 张表中,40 张表存的是资源类的数据,其余 20 张表为关系类的数据,也就是说每张表和 20 张表都要进行关联,每个关联也需要四种 CRUD 操作,那么又要增加40 * 20 * 4 = 3200个API。
所以在上述假设场景中,后端工程师要编写 3200 + 240 = 3440 个 API。而且这还不是全部,假如后端代码需要 100% 的测试覆盖,那么工程师们就要写至少 3440 个测试!
60 张表 = 3440 个 API + 3440 + 个单元测试
众所周知,数据操作 API 的实现过程基本上是重复的,有的同学甚至认为这是低端的,体现不出工程师价值的工作,纯粹的「体力活」。但是却没有一个能真正解放生产力的方案。
解决思路
尽管我们把数据库抽象成了「关系型」数据库,把操作数据的命令抽象成了 SQL ,同时我们也有了 MySQL 客户端,甚至是 sequelize 这种非常方便的库,也有「RESTful」API 命名规则,但是接口的实现从来都是需要工程师们自己用手敲出来的。
如果说我看得比别人远,那是因为我站在巨人的肩膀上。
所以我们在现有的技术基础上再抽象,把已有的东西重新组合起来,拼装成一个新的工具,帮助工程师从「体力活」中解脱出来,解放生产力。
什么样的工具
最开始的时候,我们最先需要明确的问题就是:「我们需要什么样的工具?」或者说「这种工具要帮我们解决什么问题?」。
实际上我们从刚才的假设中,已经可以得出结论:我们希望有一个工具可以让工程师免于编写数据操作 API,把数据库操作直接映射到 HTTP RESTful API 上。
调用方式
如何请求
为了解释「如何请求」,我们先从一些公认的规则出发,举一个例子,然后再从例子中抽象出一些规则。
注意:为了更便于理解,我们把所有的命名从客户端一直穿透到数据库,所以请不要纠结于我们在定义一个 API 时名词单复数的问题。
基本用例
几乎所有的系统都会有一个用户表(user)。根据 RESTful 规则的约定,我们应该把访问 user 表的 API 路径定义为 /user,并把 CRUD 的访问方法映射到 HTTP 协议中的四种方法:GET、POST、PUT、DELETE。
比如:
- GET /user:获取用户列表,应该返回一个数组。
- GET /user/:id:获取指定的用户,应该返回一个对象。
- POST /user:创建一个用户,应该返回被存储的对象,状态码应该为 201(Created)。
- PUT /user:修改一个用户的信息,应该返回修改后的对象。
- DELETE /user/:id:删除一个用户,状态码应该为 204(No Content)。
如果 user 表有一个关系表 feed,那么我们的路径就会再复杂一点:
- GET /user/:id/feed 或 GET /feed?user_id=:id:获取某个用户的帖子,应该返回一个数组。
- GET /user/:id/feed/:feed_id 或 GET /feed/:id:获取指定的帖子,应该返回一个对象。
上述的例子中还会衍生出其他的数据操作,不仅仅只有 GET,这里不一一列举了。
抽象出规则
上一节中,列举了要提供一个表的数据访问 API,大概要实现哪些路由。从这些枚举中,可以找出其中的规律,总结出一套规则。最终我们在「把能实现的路由,全部实现」的原则基础上,开发了 RestQL 的 koa 版本。
支持的 HTTP 方法:
HTTP verb |
CRUD |
|
---|---|---|
GET |
Read |
|
POST |
Create |
|
PUT |
Create/Update |
|
DELETE |
Delete |
支持的带有 body 的 HTTP 方法:
HTTP verb |
List |
Single |
|
---|---|---|---|
POST |
Array/Object |
× |
|
PUT |
Array/Object |
Object |
说明:
- List 路径为返回值为数组的路径,包括:
- /resource
- /resource/:id/association, association 为 1:n 关系
- /resource/:id/association, association 为 n:m 关系
- Single 路径为返回值为单个对象的路径,包括:
- /resource/:id
- /resource/:id/association, association 为 1:1 关系
- /resource/:id/association/:id, association 为 1:n 关系
- /resource/:id/association/:id, association 为 n:m 关系
如何使用
我们已经开源了 koa-restql,koa 应用开发者可以通过 npm 安装它:
npm install koa-restql
然后在 koa 应用的代码中引用 RestQL:
const koa = require('koa')const RestQL = require('koa-restql')let app = koa()// Build APIs from `sequelize.models`let restql = new RestQL(sequelize.models)
app.use(restql.routes())
常见问题
修改参数
用户可以通过querystring来修改参数。强烈建议使用qs对 querystring 进行解析,例如:
qs.stringify({a: 1, b:2}) // => a=1&b=2
RestQL 中的querystring仅有 3 条规则:
- 所有不以_开头的键,都会被放进sequelize#query()的where参数中。例如: // query { name: "Li Xin" } // option for sequelize { where: { name: "Li Xin" } }
- 所有以_开头的键,都会被放进sequelize#query()的参数中,和where保持平级。例如: // query { _limit: 10 } // option for sequelize { limit: 10 }
- 当需要使用关系时,可以用关系名称的字符串代替关系对象传入。例如需要使用include时: // query { _include: ['friends'] } // option for sequelize { include: [ models.user.association.friends ] }
访问控制
通常来说,我们有两种方法实现访问控制:
通过中间件
在 koa 应用挂载 RestQL 的 router 之前,可以实现一个鉴权中间件,控制用户的访问权限:
app.use(authorizeMiddleware)
app.use(restql.routes())
通过 restql 参数
在使用sequelize定义关联时,我们可以设定restql参数,实现访问控制。例如:
- 禁止通过restql访问关联: models.user.hasOne( models.privacy, { restql: { ignore: true } } )
- 禁止通过restql使用指定的 HTTP 方法访问关联 models.user.hasOne( models.privacy, { restql: { ignore: ['get'] } } )
其他语言/框架
目前我们仅实现了基于node和koa的版本,还没有其他语言/框架的实现版本。欢迎开发者提交其他语言/框架的实现到 RestQL 组。
参考链接
- GitHub, https://github.com/koajs/koa
- GitHub, https://github.com/sequelize/sequelize
- GitHub, https://github.com/Meituan-Dianping/koa-restql
- JavaScript 教程
- JavaScript 编辑工具
- JavaScript 与HTML
- JavaScript 与Java
- JavaScript 数据结构
- JavaScript 基本数据类型
- JavaScript 特殊数据类型
- JavaScript 运算符
- JavaScript typeof 运算符
- JavaScript 表达式
- JavaScript 类型转换
- JavaScript 基本语法
- JavaScript 注释
- Javascript 基本处理流程
- Javascript 选择结构
- Javascript if 语句
- Javascript if 语句的嵌套
- Javascript switch 语句
- Javascript 循环结构
- Javascript 循环结构实例
- Javascript 跳转语句
- Javascript 控制语句总结
- Javascript 函数介绍
- Javascript 函数的定义
- Javascript 函数调用
- Javascript 几种特殊的函数
- JavaScript 内置函数简介
- Javascript eval() 函数
- Javascript isFinite() 函数
- Javascript isNaN() 函数
- parseInt() 与 parseFloat()
- escape() 与 unescape()
- Javascript 字符串介绍
- Javascript length属性
- javascript 字符串函数
- Javascript 日期对象简介
- Javascript 日期对象用途
- Date 对象属性和方法
- Javascript 数组是什么
- Javascript 创建数组
- Javascript 数组赋值与取值
- Javascript 数组属性和方法
- 我向面试官讲解了单例模式,他对我竖起了大拇指
- 47 张图带你 MySQL 进阶!!!
- 新特性解读 | InnoDB-Cluster 扫盲-日常运维
- Laravel 框架实现无限极分类
- 这样设置IDEA,让你爽到飞起!
- 这些年,我写过的BUG(一)
- Selenium处理下拉列表
- 掌握好这几个css属性,少写100行js代码
- 计算机基础知识总结与操作系统 PDF 下载
- Kafka工作流程及文件存储机制
- JS破解初探,折腾到头秃的美拍视频采集下载
- 去哪儿景点信息爬取并使用Django框架网页展示
- Kubernetes v1.15.3 升级到 v1.18.5 心得
- 结巴分词seo应用,Python jieba库基本用法及案例参考
- nali一个可以查询IP归属和CDN的命令