MongoDB Shell API 点滴

      Mongo shell是一款很不错的javascript解析器，它除了支持javascript的标准API之外，还扩展了用于操作MongoDB服务的API（shell内部API）, 就好比浏览器一样，扩展了DOM、BOM、DHTM等等相关的API。shell在启动后，会去加载内部实现，给用户提供方法接口。shell内部API的实现在shell/collection.js、shell/db.js、shell/mongo.js、shell/mr.js、shell/query.js、shell/servers.js、shell/utils.js、shell/utils_sh.js等文件里，下面就来介绍下各个文件里的方法的作用。


shell/servers.js 这个文件主要是提供对MongoDB服务的操作，如启动一个MongoDB、Mongos服务，并返回服务连接对象（Mongo实例）
_parsePath(args)：该方法是全局方法，接收命令行参数,返回dbpath路径。 eg:_parsePath("--dbpath","/data/db") 可以接收多个参数。
_parsePort(args)：该方法是全局方法，接收命令行参数,返回服务端口。eg:_parsePort("--port",10000)  参数格式不对的话，会报异常。
createMongoArgs (binaryName,args) ：binary是可执行（mongod、mongos），args是命令行参数，数组里只有一个元素时，元素是个object，各个属性和值就命令行参数
startMongodTest(port,dirname,restart,extraOptions)：启动一个测试版的Mongod服务，返回链接（Mongo实例，超时为10分钟）。port为端口（默认为27000），dirname为数据库目录名（默认为端口号），restart不存在则启动服务时，会清空数据库目录内容（目录不存在则创建），反之则以普通方式启动服务（非副本集），extraOptions为启动服务参数。
startMongodEmpty(args)：启动一个普通服务，返回Mongo实例。启动时会清空数据库目录内容，目录不存在则创建。
getHostName()：取得本机名
resetDbpath(dbpath)：目录存在，则清空目录里的内容；不存在，则创建目录。
startMongod(args)：启动mongod服务，返回Mongo实例。内部调用的是startMongodEmpty
startMongodNoReset(args)：启动服务，返回Mongo实例。不会清空数据库目录内容
startMongos(args)：启动路由服务，返回Mongo实例.
startMongoProgram(args)：启动一个Mongod、Mongos实例，返回Mongo实例。args为启动参数，需要注意的是参数数组第一个参数必须是可执行命令(mongod,mongos)
startMongoProgramNoConnect(args)：启动一个mongo shell 实例，返回子进程PID。args为启动参数。eg:startMongoProgramNoConnect("mongo","--nodb")
_startMongoProgram(args)：根据命令参数启动服务或客户端。启动服务接口最终都是通过这个内置接口启动。
myPort()：返回当前shell链接的服务端口。
stopMongoProgram(port)：停掉服务。
stopMongod(port)：停掉服务。
MongodRunner：服务启动器类
MongodRunner.prototype.start(reuseData )：启动服务，启动过程会去删除lock文件。reuseData存在时，按普通方式启动，不会清空数据库目录下的内容，不存在时，执行startMongod
MongodRunner.prototype.port()：取得服务端口
MongodRunner.prototype.toString()：返回启动器参数串。
ToolTest(name)：普通服务测试类，name会被映射成数据库目录名，默认路径为/data/db，端口号为31000
ToolTest.prototype.startDB(coll)：启动服务，coll存在时返回指定的集合，不存在的话，返回DB实例。启动过程中不会启动web服务
removeFile(filename)：删除指定文件。
ToolTest.prototype.stop：停掉测试服务
ToolTest.prototype.runTool(args)：指定参数，启动服务，返回Mongo实例。
ReplTest(name,ports)：主从服务测试类。name会被映射成数据库目录名，默认路径为/data/db/。ports[0]为主接口，ports[1]为从接口
ReplTest.prototype.getPort(master)：返回主或从接口
ReplTest.prototype.getPath(master)：返回主或从数据库目录路径
ReplTest.prototype.getOptions(master,extra,putBinaryFirst,norepl)：取得主或从服务启动时完整的命令数组
ReplTest.prototype.start(master,options,restart,norepl)：启动主或从服务，返回Mongo实例。restart存在时，不会清除数据库目录下的内容，反之则为之。
ReplTest.prototype.stop(master,signal)：停掉服务。singal默认为15
allocatePorts(n,startPort)：返回[31000...31000+n-1]
quit(int)：退出客户端
waitProgram(pid)
sleep(num)：休眠函数，休眠一段时间后，在往下执行。时间是毫秒。




shell/collection.js 这个文件是DBCollection类和MapReduceResult类的封装，管理着集合信息。下面就来看看这个文件里都有哪些操作。
DBCollection(mongo,db,shortName,fullName)：构造器。参数分别是Mongo实例，DB实例，集合名，集合完整名称。DBCollection实例的属性分别为_mongo,_db,_shortName,_fullName
DBCollection.prototype.verify：校验实例各个属性是否存在，DBCollection实例化时会调用，所以实例化时，参数不对会报异常。
DBCollection.prototype.getName：返回_shortName
DBCollection.prototype.help：打出帮助信息，提示DBCollection支持哪些操作。
DBCollection.prototype.getFullName：返回_fullName
DBCollection.prototype.getMongo：返回_db.getMongo()
DBCollection.prototype.getDB：返回_db
DBCollection.prototype._dbCommand(cmd,param)：命令执行，返回执行结果
DBCollection.prototype.runCommand：等同_dbCommand
DBCollection.prototype._massageObject(q)：返回查询对象
DBCollection.prototype._validateObject(o)：验证对象是不是一个DBQuery Object.不是的话会抛异常
DBCollection._allowedFields：设置默认能显示的字段。这里默认是{ $id : 1 , $ref : 1 }
DBCollection.prototype._validateForStorage(o)：验证对象(文档)能否保存，比如对象里含有系统的关键字时。
DBCollection.prototype.find(query,fields,limit,skip)：查询
DBCollection.prototype.findOne(query,fields)：查询满足条件的第一条记录。
DBCollection.prototype.insert(obj,_allow_dot)：插入。_allow_dot存在时，不会去验证obj的格式能否保存(内容是否含有保留字)
DBCollection.prototype.remove(q,justOne)：删除文档。justOne存在时，删除满足条件的第一条记录
DBCollection.prototype.update(query,obj,upsert,multi)：更新操作。
DBCollection.prototype.save(obj)：保存操作，根据_id查找，存在就修改，不存在就新增
DBCollection.prototype._genIndexName(keys)：取得索引名字(根据文档构造索引名)
DBCollection.prototype._indexSpec(key,options)：返回组织够搞好的用于创建索引的参数
DBCollection.prototype.createIndex(key,options)：创建索引
DBCollection.prototype.ensureIndex(key,options)：创建索引
DBCollection.prototype.resetIndexCache：重置索引缓存
DBCollection.prototype.reIndex：等同db.runCommand({reIndex:集合名})
DBCollection.prototype.dropIndexes：删除所有索引
DBCollection.prototype.drop:删除集合，返回true，删除成功，flase删除失败
DBCollection.prototype.findAndModify：upsert操作
DBCollection.prototype.renameCollection(newName,dropTarget)：修改集合名字，newName是一个shortname
DBCollection.prototype.validate(full)：验证命令空间
DBCollection.prototype.getShardVersion：取得分片版本
DBCollection.prototype.getIndexes：拿到当前集合的索引集，数组结构。
DBCollection.prototype.getIndices：同getIndexes
DBCollection.prototype.getIndexSpecs：同getIndexes
DBCollection.prototype.getIndexKeys：拿到索引的keys
DBCollection.prototype.count：返回集合里的文档数
DBCollection.prototype.clean：删除集合中空闲的内存，一般情况下，用户都不会用，只有集合内部操作时，会去执行。
DBCollection.prototype.dropIndex(index)：删除指定索引
DBCollection.prototype.copyTo(newName)：将集合里的数据拷贝到db指定的库下的newName集合里。newName是一个shortName
DBCollection.prototype.getCollection(subName)：拿到该集合的子集合对象。newName(是一个shortname)为子集合名.
DBCollection.prototype.stats(scale)：拿到集合的一些系统信息。
DBCollection.prototype.dataSize：拿到集合占用的内容大小
DBCollection.prototype.storageSize：拿到集合存储数据占用的大小
DBCollection.prototype.totalIndexSize：拿到集合索引占用的大小
DBCollection.prototype.totalSize：拿到集合占用总大小。相当于dataSize、storageSize等的和
DBCollection.prototype.convertToCapped(bytes)：将普通集合转换成固定集合
DBCollection.prototype.exists：判断构造的集合是否存在
DBCollection.prototype.isCapped：判断集合是否是固定大小的集合
DBCollection.prototype._distinct(key,query)：返回满足查询条件的结果集中某个key对应的值
DBCollection.prototype.distinct(key,query)：同_distinct方法
DBCollection.prototype.group(condition):对应group命令操作
DBCollection.prototype.groupcmd：同group方法


MapReduceResult(db,o)：构造器
MapReduceResult.prototype._simpleKeys：返回构造参数o
MapReduceResult.prototype.find(args)：返回查询结果
MapReduceResult.prototype.drop：删除结果集
MapReduceResult.prototype.convertToSingleObject：此方法只提供给debug时用。一般情况下，用户应用不会用到。
DBCollection.prototype.convertToSingleObject(valuefield)：查询集合里的文档内容，然后遍历文档。将文档集存储在一个Object对象里。结构如：z={},z[a._id]=a[valuefield],返回z。
DBCollection.prototype.mapReduce(map,reduce,optionsOrOutString)：执行mapreduce操作，返回一个MapReduceResult实例
DBCollection.prototype.toString：返回fullname
DBCollection.prototype.tojson：同toString
DBCollection.prototype.shellPrint：同toString
DBCollection.autocomplete(obj)：设置集合自动补全功能，内部使用。在shell控制台中输入类似"db."后，按"tab"键自动补全功能。


note：研究过程发现Mongo shell的js引擎在判断DB或DBCollection的属性是否存在时，永远都返回真。个人觉得，它对DB实例做了特殊处理：如果对象是DB实例，且属性不存在的话，则给对象创建这个属性，值为DBCollection实例(相当于创建了一个临时集合，服务端还没有持久化)，反之是其他对象(自定义)的话，会走标准的javascript解析(返回undefined)


shell/db.js,这个文件是DB类的封装，管理DB的一些操作，下面来简要说说各个方法的用处。
DB(mongo,name)：构造器。mongo为Mongo实例，name为数据库名
DB.prototype.getMongo：返回mongo实例_mongo
DB.prototype.getSiblingDB(name)：拿到其他DB，name：指定的数据库名。
DB.prototype.getSisterDB：同getSiblingDB
DB.prototype.getName：返回数据库名_name
DB.prototype.stats：返回该数据库的系统信息，如这个库的占用空间。
DB.prototype.getCollection(name)：取得指定的集合对象
DB.prototype.commandHelp(name)：命令帮助，查看命令使用方式。name:命令名，如name:"findandmodify"
DB.prototype.runCommand(obj)：执行命令，返回object对象。obj为命令参数，
DB.prototype._dbCommand：同runCommand
DB.prototype.adminCommand()：admin权限执行命令
DB.prototype._adminCommand：同adminCommand
DB.prototype.addUser(user,pass,readonly)：给数据库添加用户。readonly默认是false
hex_md5(args)：生成md5码
DB.prototype.removeUser(username)：删除用户
DB.prototype.__pwHash(nonce,username,pass)：根据参数进行md5编码。具体可以查看方法的实现。一般是给内部使用。
DB.prototype.auth(username,pass)：验证这个用户及口令是否合法。返回1合法。返回0不合法，也就是用户或口令错误。
DB.prototype.createCollection(name,opt)：手动创建集合(可创建固定集合)，返回object。一般情况下都是自动创建集合。自动创建集合在没有对集合执行insert等操作时，集合只是在客户端缓存，服务端并没有持久化。手动创建的话，则会持久化到服务端
DB.prototype.getProfilingLevel：文件级别
DB.prototype.getProfilingStatus：文件状态。不建议使用
DB.prototype.dropDatabase：删除当前数据库
DB.prototype.dropDatabase：删除数据库
DB.prototype.shutdownServer：关闭服务。需要admin数据库下执行
DB.prototype.cloneDatabase(from)：从另一个server中拷贝数据库，一般不建议使用。用的话，通常是先执行dropDatabase()。eg：use tt db.cloneDatabase("localhost:10000")
DB.prototype.cloneCollection(from,collection,query)：从另一个server拷贝集合中数据。collection为集合名，query为查询条件。一般情况下是先执行drop()
DB.prototype.copyDatabase(fromdb,todb,fromhost,username,password)：数据库备份。建议使用。这个需要admin权限执行。fromhost未指定的话，就从本机拷贝
DB.prototype.repairDatabase：修复数据库
DB.prototype.help：打印DB实例支持的方法。
DB.prototype.printCollectionStats：打印当前数据库集合的一些系统状态信息，如内存开销。
DB.prototype.setProfilingLevel(level,slowns)：设置文件级别。目前还不知道这个作用
DB.prototype.eval(jsfunction,[options])：服务器端执行javascript。对应$eval命令
DB.prototype.dbEval(jsfunction)：同DB.prototype.eval(jsfunction)
DB.prototype.groupeval(paramsObj)：服务端执行
DB.prototype.groupcmd(paramsObj)：group命令操作
DB.prototype.group：同groupcmd
DB.prototype._groupFixParms(paramsObj)：将对象格式转换成group接收的格式
DB.prototype.resetError：执行reseterror命令
DB.prototype.forceError：执行forceerror命令
DB.prototype.getLastError(w,wtimeout)：执行getlasterror命令，返回最后一次错误执行的系统信息，这些信息里可以看到最后一次是执行了什么操作。
DB.prototype.getLastErrorObj(w,wtimeout)：返回最后一次错误执行的系统信息对象，对象里存储了执行的细节，执行的是什么操作，如insert
DB.prototype.getLastErrorCmd：同getLastErrorObj
DB.prototype.getPrevError：执行getpreerror命令
DB.prototype.getCollectionNames：返回当前数据库下有哪些集合
DB.prototype.tojson：返回数据库名
DB.prototype.toString：返回数据库名
DB.prototype.isMaster：执行ismaster命令，判断当前client链接的数据库服务是不是一个主服务
DB.prototype.currentOp：查询当前操作，暂时还不知道使用场景
DB.prototype.killOp：具体作用可以查看官方文档
DB.prototype.killOP：同DB.prototype.killOp
DB.tsToSeconds：改方法作用，具体可以查看官方文档
DB.prototype.getReplicationInfo：拿到副本集信息，该方法使用于集群环境，不能应用于大多数数据库，只能应用于local数据库，具体可以查看官方文档
DB.prototype.printReplicationInfo：打印副本集信息
DB.prototype.printSlaveReplicationInfo：打印从服务信息
DB.prototype.serverBuildInfo：服务器构建信息，执行buildinfo命令
DB.prototype.serverStatus：服务器状态信息，执行serverstatus命令
DB.prototype.serverCmdLineOpts：返回服务端的命令行参数
DB.prototype.version：返回数据库版本
DB.prototype.serverBits：查看服务器是32位还是64位操作系统
DB.prototype.listCommands：列出支持的命令，执行listCommands命令
DB.prototype.printShardingStatus：打印片服务的状态信息
DB.prototype.fsyncLock：让数据库同步加锁
DB.prototype.fsyncUnlock：检查数据库当前是不是出于同步加锁状态
DB.autocomplete(obj)：设置数据库对象自动补全，内部使用。


shell/mongo.js,这个文件是Mongo类的封装，管理着数据库的链接信息，相当关系数据库中Connection对象。下面来介绍mongo.js里都有哪些操作。
Mongo(host)：Mongo实例构造器。eg.new Mongo("127.0.0.1:3333"),端口号可选，默认为27017
Mongo.prototype.setSlaveOk：设置服务为从服务
Mongo.prototype.getDB(name)：创建一个DB实例，并将实例返回。
Mongo.prototype.getDBs：返回数据库列表，执行listDatabases命令。
Mongo.prototype.adminCommand(cmd)：已admin权限执行命令
Mongo.prototype.getDBNames：取得数据库名集合
Mongo.prototype.getCollection(ns)：根据命名空间取得集合对象
Mongo.prototype.toString：打印对象
Mongo.prototype.tojson：同toString
connect(url,user,pass)：连接服务器，返回DB实例，默认是test数据库的实例
Mongo.prototype.find()：查询操作,返回游标对象。 一般情况下不会直接调用,
Mongo.prototype.insert()：创建操作
Mongo.prototype.remove()：删除操作
Mongo.prototype.update()：更新操作


note：find,insert,remove,update这几个方法是由DBQuery对象来调用


shell/query.js,这个文件是DBQuery类（游标InternalCursor的包装者）的封装实现。这个类主要是组织查询条件，最后发送命令给服务端取得数据，作用类似于关系数据库的statement(java)
DBQuery(mongo,db,collection,ns,query,fields,limit,skip,batchSize,options)：游标对象构造器。一般情况下是内部使用。
DBQuery.prototype.help：打印DBQuery对象支持哪些方法
DBQuery.prototype.clone：返回克隆的DBQuery对象。
DBQuery.prototype._ensureSpecial：内部使用，具体可以参照官方文档
DBQuery.prototype._checkModify：方法抛异常，就表示操作已经执行了。内部使用
DBQuery.prototype._exec：执行操作,创建游标对象
DBQuery.prototype.limit(limit)：设置limit，返回当前对象
DBQuery.prototype.batchSize(batchSize)：设置批量大小，返回当前对象
DBQuery.prototype.addOption(option)：添加查询参数，返回当前对象
DBQuery.prototype.skip(skip)：设置skip参数，返回当前对象
DBQuery.prototype.hasNext：执行_exec,内部调用游标对象的hasNext方法来遍历结果
DBQuery.prototype.next：执行_exec,内部调用游标对象的next方法来遍历结果
DBQuery.prototype.objsLeftInBatch：执行游标对象的objsLeftInBatch方法
DBQuery.prototype.toArray：调用游标的遍历方法，将查询的结果集转换成数组
DBQuery.prototype.count(applySkipLimit)：执行命令实时返回查询结果集的文档个数.applySkipLimit存在，则计算limit和skip
DBQuery.prototype.size：等同DBQuery.prototype.count(true)
DBQuery.prototype.countReturn：返回this.count()-skip>limit?limit:this.count()-skip,一般情况下和count()一样。
DBQuery.prototype.itcount：测试环境下用的，根据游标结果计算count值。
DBQuery.prototype.length：计算游标结果集文档个数。
DBQuery.prototype._addSpecial(name,value)：对query添加查询字段,一般情况下是给内部使用的
DBQuery.prototype.sort(sortby)：按照某个字段排序，内部执行_addSpecial，对query添加orderby条件。
DBQuery.prototype.hint(hit)：对query添加"$hint"条件
DBQuery.prototype.min(min)：对query添加"$min"条件
DBQuery.prototype.max(max)：对query添加"$max"条件
DBQuery.prototype.showDiskLoc：对query添加"$showDiskLoc"条件
DBQuery.prototype.forEach(func)：遍历游标结果集，将文档传给func执行
DBQuery.prototype.map(func)：遍历游标结果集，将文档传给func执行，最后返回存储func执行结果的数组
DBQuery.prototype.arrayAccess(index)：根据位置索引游标结果集文档
DBQuery.prototype.explain：打印查询过程中的一些系统信息，如用到哪些索引，扫描了多少个文档等等。
DBQuery.prototype.snapshot：查询结果是快照，对query添加"$snapshot"条件，返回当前查询对象
DBQuery.prototype.pretty：设置DBQuery实例的_prettyShell属性，默认为false，返回当前查询对象，一般情况下不用
DBQuery.prototype.shellPrint：打印输出方法。
DBQuery.prototype.toString：toString方法
DBQuery.shellBatchSize：全局属性，默认为20，在shellPrint方法里用到，一般不会使用。


shell/mr.js,这个文件是封装mapreduce相关操作。简要介绍下API，应用一般不会直接用到这些
MR：是Object实例
MR.init：初始化操作
MR.cleanup：重新初始化
MR.emit(k,v)：做mapreduce操作时的用到emit方法
MR.doReduce：执行reduce方法
MR.check：检查参数
MR.finalize：mapreduce执行后执行