loach v1.0.2
Loach
Loach是一个API调用库,它能依赖极少的配置信息,构造一个请求器,使得你的API调用不在依赖HTTP请求方法与特定的URL,而是直接与业务控制器的名称相关。
特别注意
目前我们约定控制器名称与二元组(http method,url)为绝对的一对一关系。
特性
- 依赖控制器名称请求业务
- 更简单的传参形式
- 提供了Eggjs的路由适配器
安装
npm install loach
约定
API:文中的API指的是一个后台暴露出来的一个由HTTP请求方法与URL构成的一个二元组,如('GET','/users')
API配置: 文中的API配置指的是一个大的map表,其中具有一些属性,这些属性的名字我们称为控制器方法名,这些属性的值为API。
前端使用
简单使用
<!-- AJAX 库 -->
<script src='jquery.min.js'></srcipt>
<!-- 同时也支持 Axios -->
<!-- <script src='axios.min.js'></script> -->
<script src='./node_modules/loach/dist/loach.min.js'></srcipt>
<script>
let API = Loach.Client({ // Client的构造方法接受一个 API配置
'users.query':['get','/users']
});
// or
/*
let API = new Loach.Client({
'users.query':['get','/users']
});
*/
API['users.query']().then( rs => { // 该方法会以get方法请求url'/users'
// rs 为服务器返回响应体 风格与Axios返回的一致
} );
</script>
API传参
let logic = rs => {/*前端业务逻辑*/};
let API = Loach.Client({
'users.query':['get','/users'],
'users.create':['post','/users'],
'users.show':['get','/users/:id'],
'users.update':['put','/users/:id']
});
// 查询10个注册时间在 10 到 20 名之间的用户记录
API['users.query'](JSON.parse({
limit:20,
offset:10,
orderBy:'create_time'
})).then( logic );
// 创建一个用户
API['users.create']({
username:'user1',
password:'123456',
vcode:'s5tt',
}).then( logic );
// 显示一个id为11的具体的用户记录
API['users.show']([11]).then( logic );
// 更加复杂的传参
// 修改id为11号用户信息
API['users.update']([11],{
password:'654321',
}).then( logic );
推荐所有的控制器写都是‘aaa.bbb.ccc’的,因为如果你这样写,以下的请求方式是等效的。
API['users.query']();
API.users.query();
所有的请求方法都存在8种重载,这些方法的参数中,我们将类型为对象的当做请求参数,类型为JSON字符串的当做查询字符串,我们将类型为数组的当做路径参数,完整的参数重载如下所示。
远程请求API配置
Loach.Client().then( API => {//
// API返回一个Client实例
// 修改id为11号用户信息
API['users.update']([11],{
password:'654321',
}).then( logic );
} );
适配器使用
目前Loach提供了Eggjs的路由适配器,只是为此你需要一些约束。
使用方式如下
// 在router.js中使用
'use strict';
/**
* @param {Egg.Application} app - egg application
*/
module.exports = app => {
const { router, controller } = app;
const Adapter = require('loach').Adapter.EggJS;
Adapter(router); //适配
router.get('/', 'home.index');
router.get('/hi', 'home.hi');
// router.get('/ctrl', controller.home.index); 这样挂载可以正常挂载,但是loach会跳过这个api
};
由于使用了loach的适配器,loach将收集路由信息,并在当前应用中额外挂载一个url为'/loach'的请求方法为GET的路由,用于返回API的配置信息。
若要修改默认挂载的url,可以像以下一样使用。
Adapter(router,'/API');
// 此时 前端以GET方式请求'/API'则可以获得API配置
API参考
浏览器端
构造方法
Loach.Client([client][,conf])
API请求的构造器,可以使用new,也可以不构造
client 请求接口的实现视力。需要支持四种常见的方法GET,POST,DELETE,PUT。若不提供,则会依次尝试使用JQuery/Axios,若都没有,则报错。
conf 当其未一个对象时,其表示API配置。当其为一个字符串时,其表示一个API配置信息的url。当不提供它是,Loach会使用client自动使用GET方法请求'/loach'路径并返回一个Promise。
实例属性
API.requestAble
返回可用的控制器名称。
实例方法
API['ctr']([params][,query],[,body])
API
服务器端
当前Loach提供了Eggjs的适配器,用于自动收集路由信息。你可以这样使用它
// 在router.js中使用
'use strict';
/**
* @param {Egg.Application} app - egg application
*/
module.exports = app => {
const { router, controller } = app;
const Adapter = require('loach').Adapter.EggJS;
Adapter(router); //适配
router.get('/', 'home.index');
router.get('/hi', 'home.hi');
// router.get('/ctrl', controller.home.index); 这样挂载可以正常挂载,但是loach会跳过这个api
};
Adapter([,mountUrl])
服务端适配器,适配器会在你的后台应用上挂载一个路径为mountUrl,请求方法为get的控制器,用于返回服务器的路由配置
router 后端路由管理对象。需要支持四种常见的方法GET,POST,DELETE,PUT。
mountUrl API配置信息的挂载路径。默认为'/loach'