什么是模块

在XARPackage里,在config.json里配置modules,可以导出XARPackage下的js模块。

假设calc是一个XARPacakge,目录结构如下:

├── src
│   └── test
│       └── calc
│           ├── calc.js
│           ├── config.json
│           └── onload.js

则导出calc.js的方式是在config.json里配置modules字段:

// src/test/calc/config.json
{
    ...
    "modules": {"calc": "calc.js"},
    ...
}

calc:calc 就代表calc这个XARPackage下的calc模块,{xarpacakge_name}:{module_name}是模块的id

如何默认导出XARPackage内的所有js模块

上面的方式每导出一个模块,都需要在config.json/modules里增加一条配置,如果希望默认导出包内所有的js模块,则 可以配置config.json/moduleAccess字段,例如:

// src/test/calc/config.json
{
    ...
    moduleAccess:'public', // 模块导出级别, 可选值是'public','protect', 'private',默认是'public'
    ...
}

不过,从工程的角度来说,不建议默认全部导出,通过导出设计过的特定模块是一个更合理的做法。

什么是模块的导出接口

在上面的calc.js里,通过module.exports导出的函数就是模块的导出接口,例如calc:calc的模块接口如下,其中的注释 简要解释了模块导出接口的输入输出参数要求:

function main(){
    // 模块加载后先执行main函数
}

//
// bucky package 导出函数的两种声明方式
// ===============
//
// ## 方式1: 回调方式,
// 1. 采用最后一个回调函数退出函数
// 2. 该回调只接受一个参数
// 
// ## 方式2: async/await方式
// 1. 返回值是个只能有一个元素的数组,(i.e: [result])
// 2. 由于bucky框架不使用异常机制,不能返回异常
// 3. 如果返回Promise,则只使用resolve,不能使用reject,原因如上
//
// 下面的示例两种方式导出包接口,测试代码请见test目录
// 


/**
 * 示例:采用方式一导出函数
 * 
 * 导出div1函数,接受两个参数x和y,通过调用onComplete退出
 *
 * @param {double} x 除数
 * @param {double} y 被除数,y不应该为零
 * @param {function} onComplete(result) 退出回调,只接受一个参数
 */
function div1(x,y,onComplete) {

    /** onComplete只接受一个参数,因此需要把返回结果打包在一个对象内 */
    let result = {
        err:null,
        value:null
    };

    try{
        let value = x/y;
        result.value = value;

        /** 正确执行,返回计算结果 */
        onComplete(result);
    }catch(err){
        /** 执行异常,返回出错信息 */

        result.err = err;
        onComplete(result);
    }
}

/**
 * 示例:采用方式二导出函数
 * 
 * 导出div2函数,接受两个参数x和y,通过resolve返回结果(正确/错误 通过错误码标识)
 *
 * @param {double} x 除数
 * @param {double} y 被除数,y不应该为零
 */
async function div2(x,y) {

    /** onComplete只接受一个参数,因此需要把返回结果打包在一个对象内 */
    let result = {
        err:null,
        value:null
    };

    return new Promise((resolve, reject) => {
        try{
            let value = x/y;
            result.value = value;

            /** 正确执行,返回计算结果 */
            resolve([result]);
        }catch(err){
            /** 执行异常,返回出错信息 */

            result.err = err;
            resolve([result]);
        }
    });
}

/** 导出接口 */
module.exports = {
    __main:main,
    div1,
    div2
};

模块接口函数的返回值怎么返回

Bucky的模块接口函数有两种形式。

形式1,导出普通函数,最后一个回调参数onComplete返回,onComplete只接受一个参数:

function test(arg1,arg2,onComplete){
    ...
    onComplete(result);
}

形式2,导出async函数,返回值必须是个只含有一个值的数组:

async funciton test(arg1,arg2){
    ....
    return [result];
}

或者:

async funciton test(arg1,arg2){
    return new Promise((resolve,reject)=>{
        ...
        resolve([result]);
    });
}

为什么模块接口函数的返回值必须是单个值

  1. JavaScript语言的函数是单返回值语义的
  2. Bucky的导出函数支持下面两种形式:
    1. 使用最后一个回调函数onComplete返回结果值
    2. 导出函数是一个async函数

综合考虑设计上的一致性,bucky的模块接口函数的返回值必须是单个值

为什么模块接口函数不使用异常

  1. Bucky认为使用异常应该在语言提供完整的Checked Exception机制的情况下使用。
  2. Bucky整个框架都是使用错误码返回错误信息,尽量避免异常的传播。

results matching ""

    No results matching ""