Question

来自.NET世界我很难消耗javascript框架的文档。我将以“Node.js MongoDB Driver API”为例。有一个Collection对象具有count()方法。以下是它的链接：http://mongodb.github.io/node-mongodb-native/2.0/api/Collection.html#count

从那里我看到count()有三个参数：

count(query, options, callback)

起初我认为我需要提供所有这三个才能使用这种方法。但是，在此方法的示例代码中，我看到它有时只使用一个参数，有时只使用一个参数：

// Perform a total count command
collection.count(function(err, count) {
  test.equal(null, err);
  test.equal(4, count);

  // Peform a partial account where b=1
  collection.count({b:1}, function(err, count) {
    test.equal(null, err);
    test.equal(1, count);

    db.close();
  });

在第一种情况下，它仅使用callback参数调用count（），而在第二种情况下，它提供options和callback。没有使用原始方法描述中所述的所有三个参数的示例。

我的问题是如何才能知道这些事情？我的意思是，如果本文档中没有示例，我怎么知道这可能？另外，如果没有这样的例子，我怎么能确定该方法还有其他可能的用途？

我知道调用javascript函数只提供一些参数是完全合法的，函数应该能够根据实现来处理它。但作为API的消费者，我不想查看函数实现来确定我可以传递哪种参数组合。我觉得这个文档并不完整（我把这个mongodb驱动程序作为一个例子，但我遇到了与其他js框架文档类似的问题）。

在阅读javascript文档时，我应该有什么样的推理，在尝试理解不同框架的API时如何思考，如何知道什么是可能的，什么不是等等......？

Answer 1

在JavaScript和特别是Node.JS世界中，异步函数有一个共同的模式，它们的最后一个参数应该是一个回调函数。

count(query, options, callback)

当您调用异步函数时，您必须预见到调用的结果将在回调中出现，否则如何获取异步函数调用的结果？所以根据上面的语句，你至少应该为count方法和你在JavaScript中调用的其他异步函数提供一个回调函数。

当您看到MongoDB的方法时，另一件可以帮助您的事情是，如果您要使用数据库处理某些数据，通常需要提供至少一个查询对象， 回调函数，但如果您需要提供有关查询的其他信息，则选项对象。

我知道文档不能很好地解释查询和选项参数是否是选项，但如果您看到count method的源代码并阅读我在您能理解的代码上添加的注释：

Collection.prototype.count = function(query, options, callback) {

    // args represents the three parameters
    var args = Array.prototype.slice.call(arguments, 0);

    // extract your last argument and assumes that it is the callback function
    callback = args.pop();

    // extract the first argument that is query
    query = args.length ? args.shift() || {} : {};

    // extract the second argument but this time shift already extracted query
    // so the first parameter this time will be options.
    options = args.length ? args.shift() || {} : {};

    ...
}

如果您将以下值传递给调用，您将看到订单注释了count方法将如何获取参数：

count({}, {}, function callback() {}); // count(query, options, callback)
count({}, function callback() {}); // count(query, callback)
count(function callback() {}); // count(callback)

事实上，在您通过嵌套调用count方法提供的示例中，您将查询和回调以及非选项和回调传递给计数方法：

collection.count(function(err, count) {
  test.equal(null, err);
  test.equal(4, count);

  // You are passing the values in this order (query, callback)
  // {b: 1} === query
  collection.count({b:1}, function(err, count) {
    test.equal(null, err);
    test.equal(1, count);

    db.close();
});

我希望这个解释和代码可以帮助您理解围绕JavaScript世界的这种常见回调模式。

如何阅读javascript框架文档？

1 个答案: