swop-store

Welcome to the Swop 🎉

swop 是一个用于JavaScript与客户端进行数据交互应用程序，他提供了简洁的api来帮助开发者来做这些事情。

swop 的来源

       在我们与客户端交互的时候，大量的数据散落在项目各个文件，或者集中于繁琐的redux和window对象之中，管理维护困难，操作麻烦，使得开发效率很低。

swop 要解决什么样的问题

       swop 使用 aop 的理念进行设计开发，通过对于数据的拦截来做一些事情，swop 内置了中间件，参考一下express和redux的middleware，但不同的是 swop 的middleware没有next函数，swop 能让开发者更好的处理数据，更好的异步和错误处理。

API

options

• json_stringify： 与客户端交互时是否让 swop 对传输的数据进行json stringify，默认值为 false。

• json_parse： 客户端响应时是否让 swop 对传输的数据进行json parse，默认值为 false。

钩子函数

swop.send

考虑到不同业务场景下的需求不同，swop 最终与客户端交互的时候必须通过 send 方法进行。

  // 可以通过以下方式进行
  // name 接口名
  // send_data 经过 swop 包装过的数据
  // 原始数据
  S.send = function (name, send_data, origin_data) {
    ...
  }

swop.onerror

swop 提供一个捕捉错误的钩子函数，如果 onerror 函数被定义了, swop 发出的错误都会被捕捉到，否则，swop 会直接在控制台输出错误。

  // msg 错误信息
  // stack 错误堆栈
  // error_text swop 将要输出到控制台上的信息
  S.onerror = function (msg, stack, error_text) {
    ...
  }

swop 类 api

• call(name, [data])
• response(data)
• create(attr_name, [default_value], [read_only])
• use(name, fun)
• get_all_data()
• get_queue(name)
• get_funs(name)
• clear_polling([name])

绑定属性 api

• get()
• set(value)
• subscribe(fun)
• unsubscribe()
• polling([name], [data], [fun])

实例化 swop

swop 可以通过两种方式来实例化。

  import { Swop, CreateSwop } from 'swop-data';

  const S = new Swop(options);

  // 或者你可以用 swop 提供的创建实例的函数
  const S = CreateSwop(options);

  S.create('dataOne', 1);

  S.dataOne.set(2).get();

如果你是用typescript进行的开发

  import {
    Swop,
    CreateSwop,
    ContainerDataTypes as C,
  } from 'swop-data';

  export type A = C<I, keyof D>;

  // 需要的接口在这里添加
  export type I =
    'interfaceOne' |
    'interfaceTwo';

  // 实时变化数据存储容器
  export type D = {
    'dataOne': A;
    'dataTwo': A;
    'dataThree': A;
  }

  // 通过 new 来创建的实例，在调用 create 方法
  // 绑定数据后，没有办法通过实例拿到绑定属性的类型
  const S = new Swop<I, D>(options);
  S.creata('dataOne');
  // 这种情况下 dataOne 的类型没有办法推断出来，但有两种办法可以拿到绑定数据的类型
  //  S.dataOne.XX

  // 第一种，使用 types 属性
  S.types.dataOne.get();

  // 第二种，用 swop 提供的实例函数来创建实例
  interface _Swop extends Swop<I, D>, D {}
  const S = CreateSwop<_Swop>(options);
  S.dataOne.get();

  // 如果你不需要知道绑定属性的类型，你可以这样写
  S['dataOne'].get();

swop 类 api

call

call 方法是于客户端进行通信的入口函数，他需要传入一个name字符和需要发送的数据。

  // name 是于客户端交互的接口名
  // data 传输给客户端的数据，默认为 null
  // call 方法会返回一个 promise
  // value 是客户端返回数据
  S.call(name, data).then(([value, args]) => {
    ...
    args.next();
  }).catch(err => {
    ...
  })

  // 如果不需要对错误进行处理，你可以使用 AsyncFunction 进行更好的流程处理
  async function call_height () {
    const data = await S.call(name, data)
    ...
  }

  // 客户端的响应会以队列的形式进行触发，所以你可以这里对数据做一些传递
  S.call(name).then(([value, args]) => {
    /**
     * 我们可以在这里拿到客户端的下一次响应
     * args 有三个值
     *  next : 下一次的响应（如果当前环境正在被调用，而下一次响应还没有到达，此时next是一个空函数）不管next函数是否是一个空函数，都必须调用，否则可能会出现下一次响应没有办法触发的情况
     *  params : 上一次传过来的数据
     *  nextSwopFun : 下一次的 call
     */

    args.next(`上一次的响应值为：${value}`);
  })

response

response 方法是客户端的入口函数。返回一个promise。

  // 我们假设客户端响应统一在 window 上的 callback 方法上
  window.callback = data => S.response(data);

  // or
  window.callback = data => {
    S.response(data).then(_ => {
      console.log('success');
    }).catch(err => {
      ...
    })
  };

create

create 方法会创建一个绑定属性和绑定数据，返回值为this。

   // attr_name : 绑定数据名
   // default_value : 创建绑定数据时默认值
   // read_only : 数据是否只读
   // 需要注意的是，当创建的数据是只读数据时，直接修改此数据的值也是不被允许的
  S.create(attr_name, default_value, read_only)
   .create(attr_name);

  // 当创建一个绑定属性后，会在 swop 实例上生成一同名的绑定属性
  // 需要注意的事项可以看实例化时的注释

use

use 方法是 swop 提供的一个中间件函数，你可以通过 use 方法来注入一些中间件，中间件的注入与先后顺序相关，use 方法返回的是this，所以你可以像 jQuery 那样链式调用。

  // name match字符，接口名或者'*'，当为通配符的时候，所有的接口都会匹配上
  // val 有两个属性 value 和 match
  S.use(name, val => {
    // 需要注意的是，use 方法的回调参数，swop 改成了引用的方式，所以你不需要纠结这里怎么没有`return`关键字
    // 当然，这里如果你要对响应数据做些修改，你不应该用解构，除非你要做的事情与源数据没什么关系
    if (typeof val.value === 'string') {
      val.value = JSON.parse(val.value);
    }
  })

  // bad
  S.use(name, [value, match] => {
    ...
  })

get_all_data

get_all_data 能够获取所有的绑定数据。

  const all_data = S.get_all_data();

get_queue

swop 把当前接口的所有客户端响应都放到一个队列里面，get_queue 方法会返回当前接口的客户端响应队列。

  const queqe = S.get_queue(name);

get_funs

当调用 call 方法与客户端进行数据交互时，会生成一个接收客户端响应的集合，每个集合由一个fun_body和id组成。get_funs 能够得到当前接口的所有集合。

  const funs = S.get_funs(name);

  // 手动响应
  const ids = funs.map(val => val.id);
  ids.forEach((id, i) => {
    S.response(JSON.stringify({
      id,
      origin_data: {
        xx: 'xxx',
      }
    }))
  })

clear_polling

clear_polling 方法清除绑定属性的轮询。如果name为空，则清空所有绑定属性的轮询，返回值为this。

  S.clear_polling(name);
  // or
  S.clear_polling();

绑定属性 api

当通过create api 创建一个静态属性后，每个静态属性都会生成对应的方法，需要注意的是当生成的绑定数据是readOnly时，当前绑定属性只有get方法。

• 假定以下 api 描述的绑定属性名为 dataOne。

get

  const data = S.dataOne.get();

set

set 方法会给当前绑定数据重新赋值，返回值是当前绑定属性

  S.dataOne.set(1);
  // or
  S.dataOne.set(1).get();

  // 我们可以通过中间件做一些数据的更改
  S.use('dataOne', val => val.value *= 100);

  S.dataOne.set(1).get(); // 100

  // 但是最常用的应该是客户端数据上报时用，假定客户端上报于 window.report
  window.report = (data_name, data) => {
    S[data_name].set(data);
  }

当跟改数据时，虽然 swop 对榜单数据的值直接变动也能监听，但是正确的做法应该通过 set 方法来赋值。

  // 绑定数据直接赋值也能被监听到
  S.dataOne.subscribe(new_value => {
    ...
  })

  S.get_all_data().dataOne = 1;

subscribe

subscribe 方法会对绑定数据进行监听，返回一个 remove 函数，用于注销当前的监听。

  // S.dataOne.subscribe(fun, once);
  // fun : 监听回调接受两个参数，分别为新值和旧值
  // once : 此次监听是否只触发一次
  S.create('dataOne');

  const remove = S.dataOne.subscribe((new_value, old_value) => {
    document.body.innerHTML = new_value;

    // 如果你是在使用 react 进行开发，你可以
    this.setState({
      xx: new_value,
    })
  }, true);

  // 你可以在适当的时机注销掉这个监听
  remove();

unsubscribe

subscribe 方法会对绑定数据进行监听，需要手动一个个的注销掉监听，你会不会觉得太麻烦呢？unsubscribe 就是一个可以省事的 api，返回值为this。

  // 使用起来也很简单
  S.dataOne.unsubscribe();

polling

polling 会不停的对客户端进行 call，以此更新当前绑定数据的值，返回值为 stop 函数，用于终止轮询。

  // 如果你自己对绑定属性的值进行更新，你可以这样做
  let interval;
  function polling () {
    const get = setInterval(async _ => {
      const data = await S.call('interface', data);
      S.dataOne.set(data);

      if (S.get_funs().length < 50) { return; }

      interval = setInterval(_ => {
        // 预防无限注入，导致大的内存开销
        if ( S.get_funs().length < 50) {
          clearInterval(interval);
          interval = null;
          polling();
        }
      }, 100)
    }, 100)
  }

  polling();

  // swop 提供了 polling 来轮询获取数据，需要传入的三个参数都是可选的
  // interface_name : 需要轮询的接口，默认与当前的绑定属性名相同
  // data : 轮询时需要传入的数据
  // hook_fun : 轮询时每次响应的钩子函数

  const stop = S.dataOne.polling('interfaceOne', '', data => {
    ...
  });

  stop();

  // 但最常用的应该是
  S.dataOne.subscribe(new_value => {
    // react
    this.setState({
      xx: new_value,
    })
  })

  S.dataOne.polling();

polling 方法在内部没有采用定时器的方法来轮询，所以不会带来大的内存开销。当返回的数据没有变动时候，polling 方法会降低轮询的频率，减少运行时的开销，关于清除所有绑定属性的轮询，可以看这里 clear_polling。

约定

swop 使用约定好的数据格式与客户端进行交互，这需要客户端的开发者配合。

在 JavaScript 层面，swop 会把数据转换成

{
  origin_data: xxx（真正需要发送的数据）,
  id: xxx（swop 生成的一段随机字符串）,
}

相应的，响应数据也应该保证统一的格式

{
  origin_data: xx（真正需要响应的数据）,
  id: xx（swop 生成的id，id 是必须的），
}

       id 和 origin_data 是唯一约定好的字段名，不应该带有其他的数据字段，不同的是，响应数据的格式是需要客户端的开发者手动转换成我们需要的格式，而 swop 会帮 JavaScript 开发者来做转换，id 是两者之间通信的凭证，swop 必须依靠 id 才能找到相应的响应集合。

       如果响应数据的格式是 json，但在初始化实例的时候并没有让 swop 做 json 的解析，那么 swop 会通过正则表达式来截取真正需要的数据，需要注意带来的运行时开销。

       绑定数据的更新也不应该通过 polling 函数来实现更新，客户端应该在数据发生变化时，数据上报给 JavaScript，通过绑定属性的 set 方法实现更新.