什么是模块

在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的导出函数支持下面两种形式：
3. 使用最后一个回调函数onComplete返回结果值
4. 导出函数是一个async函数

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

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

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