续写Appium 源码分析 (8)-helpers 模块

configureServer

该方法在 main.js 模块中有调用。

module.exports.configureServer = function (rawConfig, appiumVer, appiumServer,
    cb) {
  //定义一个变量
  var appiumRev;
  //判断配置数据是否定义，未定义的话就直接报错，cb代表回调函数callback
  if (!rawConfig) {
    return cb(new Error('config data required'));
  }
  //定义一个空json字符串
  var versionMismatches = {};
  //定义一个数组excludedKeys并赋值
  var excludedKeys = ["git-sha", "node_bin", "built"];
  //遍历rawConfig
  _.each(rawConfig, function (deviceConfig, key) {
    //如果配置的元素中，版本的信息不等于appium的版本，而且属性的name值不在excludedKeys内，说明
    //这个配置项是不匹配的，需要保存在versionMismatches中。
    if (deviceConfig.version !== appiumVer && !_.contains(excludedKeys, key)) {
      versionMismatches[key] = deviceConfig.version;
    } else if (key === "git-sha") {
      //如果上面的条件不满足，但是key值等于git-sha，将appiumRev的值设置为rawConfig中的git-sha指代的值
      appiumRev = rawConfig['git-sha'];
    }
  });
  //keys为遍历所有json字符串中的key值，组成一个数组，判断该数组的长度
  if (_.keys(versionMismatches).length) {
    //如果不匹配的配置项的个数大于0，输出一些错误的提示信息
    logger.error("Got some configuration version mismatches. Appium is " +
                 "at " + appiumVer + ".");
    _.each(versionMismatches, function (mismatchedVer, key) {
      logger.error(key + " configured at " + mismatchedVer);
    });
    logger.error("Please re-run reset.sh or config");
    return cb(new Error("Appium / config version mismatch"));
  } else {
    //如果配置都是正确的，调用registerConfig开始设置
    appiumServer.registerConfig(rawConfig);
    cb(null, appiumRev);
  }
};

conditionallyPreLaunch

//预加载模式
module.exports.conditionallyPreLaunch = function (args, appiumServer, cb) {
  //判断args.launch的属性是否为true
  if (args.launch) {

    logger.debug("Starting Appium in pre-launch mode");
    //调用appium.js模块的预加载函数preLaunch，传入的参数为一个回调函数
    appiumServer.preLaunch(function (err) {
      if (err) {
        logger.error("Could not pre-launch appium: " + err);
        cb(err);
      } else {
        cb(null);
      }
    });
  } else {
    cb(null);
  }
};

prepareTmpDir

//创建临时目录
module.exports.prepareTmpDir = function (args, cb) {
  if (args.tmpDir === null) return cb();
  //调用mkdirp模块的的方法创建目录
  mkdirp(args.tmpDir, function (err) {
    if (err) {
      logger.error("Could not ensure tmp dir '" + args.tmpDir + "' exists");
      logger.error(err);
    }
    cb(err);
  });
};

startAlertSocket

var startAlertSocket = function (restServer, appiumServer) {
  var alerts = io(restServer, {
    'flash policy port': -1,
    'logger': logger,
    'log level': 1,
    'polling duration': 10,
    'transports': ['websocket', 'flashsocket']
  });
  //连接服务器，回调函数为连接后进行的处理
  alerts.sockets.on("connection", function (socket) {
    logger.debug("Client connected: " + (socket.id).toString());
    //监听disconnect事件，当断开连接后，调用回调函数
    socket.on('disconnect', function (data) {
      logger.debug("Client disconnected: " + data);
    });
  });

  // add web socket so we can emit events
  //将该alerts时间添加到web socket中
  appiumServer.attachSocket(alerts);
};

getDeprecatedArgs

//得到废弃的参数
var getDeprecatedArgs = function (parser, args) {
  var deprecated = {};
  //遍历parser中定义的参数，设置遍历的元素为rawArg
  _.each(parser.rawArgs, function (rawArg) {
    //获取元素的dest的值
    var arg = rawArg[1].dest;
    //如果dest指代的值存在，且rawArg[1]的属性deprecatedFor也存在
    //将该值添加到json字符串deprecated中
    if (args[arg] && rawArg[1].deprecatedFor) {
      deprecated[rawArg[0]] = "use instead: " + rawArg[1].deprecatedFor;
    }
  });
  return deprecated;
};

startListening

module.exports.startListening = function (server, args, parser, appiumVer, appiumRev, appiumServer, cb) {

  //声明变量alreadyReturned并赋值为false
  var alreadyReturned = false;
  //监听某个url下的某个端口的消息，回调函数为连接成功后处理函数
  server.listen(args.port, args.address, function () {
    //欢迎信息，这些信息相信用过appium的人都见过，首先打印欢迎信息
    var welcome = "Welcome to Appium v" + appiumVer;
    //如果git-sha的赋值给了appiumRev，就将其追加到欢迎信息中
    if (appiumRev) {
      welcome += " (REV " + appiumRev + ")";
    }
    //打印welcome信息
    logger.info(welcome);

    var logMessage = "Appium REST http interface listener started on " +
                     args.address + ":" + args.port;
    //打印ip地址和端口号
    logger.info(logMessage);
    //调用startAlertSocket启动连接socket
    startAlertSocket(server, appiumServer);
    if (args.nodeconfig !== null) {
      //如果node配置信息不为null，那么就配置node信息
      gridRegister.registerNode(args.nodeconfig, args.address, args.port);
    }
    var showArgs = getNonDefaultArgs(parser, args);
    if (_.size(showArgs)) {
      //如果非默认参数的个数大于0，需要打印出来
      logger.debug("Non-default server args: " + JSON.stringify(showArgs));
    }
    var deprecatedArgs = getDeprecatedArgs(parser, args);
    if (_.size(deprecatedArgs)) {
      //如果有废弃的参数，也需要打印出来
      logger.warn("Deprecated server args: " + JSON.stringify(deprecatedArgs));
    }
    //这个应该很熟悉，我们经常启动的时候就能看见这个,输出log的等级，大于等于这个等级的log才会输出
    logger.info('Console LogLevel: ' + logger.transports.console.level);
    //文件log的等级，大于等于这个等级的信息才会保存
    if (logger.transports.file) {
      logger.info('File LogLevel: ' + logger.transports.file.level);
    }
  });
  //监听error事件
  server.on('error', function (err) {
    if (err.code === 'EADDRNOTAVAIL') {
      logger.error("Couldn't start Appium REST http interface listener. Requested address is not available.");
    } else {
      logger.error("Couldn't start Appium REST http interface listener. Requested port is already in use. Please make sure there's no other instance of Appium running already.");
    }
    if (!alreadyReturned) {
      alreadyReturned = true;
      cb(err);
    }
  });
  //设置超时连接时间为10分钟
  server.on('connection', function (socket) {
    socket.setTimeout(600 * 1000); // 10 minute timeout
  });
  //延迟任务，在1秒后执行函数
  setTimeout(function () {
    if (!alreadyReturned) {
      alreadyReturned = true;
      cb(null);
    }
  }, 1000);
};

调用该方法，一般会打印如下信息：

nfo: Welcome to Appium v1.3.7 (REV 72fbfaa116d3d9f6a862600ee99cf02f6d0e2182)

info: Appium REST http interface listener started on 0.0.0.0:4723

info: [debug] Non-default server args: {"platformName":"Android","platformVersion":"4.4","automationName":"Appium","defaultCommandTimeout":7200}
info: Console LogLevel: debug

compile

function compile(fmt) {
  fmt = fmt.replace(/"/g, '\\"');
  var js = '  return "' + fmt.replace(/:([-\w]{2,})(?:\[([^\]]+)\])?/g,
    function (_, name, arg) {
      return '"\n    + (tokens["' + name + '"](req, res, "' + arg + '") || "-") + "';
    }) + '";';
  // jshint evil:true
  return new Function('tokens, req, res', js);
}

这个函数是设置打印的字符串格式

requestStartLoggingFormat

//一次请求的开始，输出的log格式，格式类似 info: --> GET /wd/hub/status {}
module.exports.requestStartLoggingFormat = compile('-->'.white + ' ' + ':method'.white + ' ' +
  ':url'.white);

requestEndLoggingFormat

//一次请求的结束，输出log格式，格式类似：info: <-- GET /wd/hub/status 200 4.102 ms - 104 
//{"status":0,"value":{"build":{"version":"1.3.7","revision":"72fbfaa116d3d9f6a862600ee99cf02f6d0e2182"}}}
module.exports.requestEndLoggingFormat = function (tokens, req, res) {
  var status = res.statusCode;
  var statusStr = ':status';
  //状态码大于500的话，状态码为红色
  if (status >= 500) statusStr = statusStr.red;
  //状态码大于400小于500，状态码为黄色
  else if (status >= 400) statusStr = statusStr.yellow;
  //状态码大于300小于400，状态码为蓝绿色
  else if (status >= 300) statusStr = statusStr.cyan;
  //小于300，状态码为绿色
  else statusStr = statusStr.green;
  var fn = compile('<-- :method :url '.white + statusStr +
    ' :response-time ms - :res[content-length]'.grey);
  return fn(tokens, req, res);
};

getRequestContext

//得到请求的内容
function getRequestContext(req) {
  //如果req未定义，直接返回空字符串
  if (!req) return '';
  var data = '';
  try {
    //截取req的body部分，索引0到200的字符串
    if (req.body) data = JSON.stringify(req.body).substring(0, 200);
  } catch (ign) {}
  return format('context: [%s %s %s]', req.method, req.url, data).replace(/ ]$/, '');
}

safely

var safely = function () {
  //获取传递进来的参数
  var args = new (Args)(arguments);
  //获得第一个参数
  var req = args.all[0];
  //回调函数
  var fn = args.callback;
  try {
    //调用回调函数
    fn();
  } catch (err) {
    logger.error('Unexpected error:', err.stack, getRequestContext(req));
  }
};
module.exports.safely = safely;

domainMiddleware

module.exports.domainMiddleware = function () {
  return function (req, res, next) {
    //创建一个域记录
    var reqDomain = domain.create();
    //将req和res添加到域管理
    reqDomain.add(req);
    reqDomain.add(res);
    //res监听close事件
    res.on('close', function () {
      //延迟事件，5秒后关闭域
      setTimeout(function () {
        reqDomain.dispose();
      }, 5000);
    });
    //reqDomain添加error事件
    reqDomain.on('error', function (err) {
      logger.error('Unhandled error:', err.stack, getRequestContext(req));
    });
    //执行next函数
    reqDomain.run(next);
  };
};