serve-index用法、实现原理（源码解读）

本文主要讲解serve-index的用法和实现原理（源代码分析）。

一 说明

serve-index的功能是将文件夹中文件列表显示到浏览器中。

serve-index是一个NodeJS模块，可以通过NPM安装。

二 安装方法

$ npm install serve-index --save

三 使用方法

通过ExpressJS创建静态服务器时，使用serve-index方法如下：

 var express = require('express');
 var serveIndex = require('serve-index');
 var app = express();

 app.use(express.static('staticServer'));

 app.use(serveIndex('staticServer',{ 'icons': true }));

 var server = app.listen(3000, function () {
     var host = server.address().address;
     var port = server.address().port;

     console.log('Example app listening at http://%s:%s', host, port);
 });

通过nodeJS的serve-static创建静态服务器时，用法如下：

 var finalhandler = require('finalhandler')
 var http = require('http')
 var serveIndex = require('serve-index')
 var serveStatic = require('serve-static')

 // Serve directory indexes for public/ftp folder (with icons)
 var index = serveIndex('public/ftp', {'icons': true})

 // Serve up public/ftp folder files
 var serve = serveStatic('public/ftp')

 // Create server
 var server = http.createServer(function onRequest(req, res){
   var done = finalhandler(req, res)
   serve(req, res, function onNext(err) {
     if (err) return done(err)
     index(req, res, done)
   })
 })

 // Listen
 server.listen(3000)

四 接口说明

serveIndex（path，options）

1.功能说明：

创建一个中间件函数。

2.返回值：

中间件函数，这个中间件创建了文件夹中所有文件的索引目录。

3.参数：

path：

静态文件服务器的路径地址，一般与创建静态服务器地址一致。

options：

ServeIndex在options对象中接受这些属性：

filter

类型：Function；默认值为false。

功能：文件夹中每个文件都调用filter函数进行过滤，实际就是让开发人员可以决定哪些文件显示哪些不显示，也可以改变文件名。如果该函数返回false（或者空字符串）【注意：只测试了这两种】，则不显示该文件夹。

参数：filter(filename, index, files, dir)

filename是文件名，index是数组索引，files是文件数组，是文件dir所在的绝对路径。

下边是filter的一个示例，用于过滤不显示READEME.md文件。

 var options = {
     icons : true,
     filter : serveIndexFilter
 };

 function serveIndexFilter(filename, index, list, path) {
     console.log(filename);
     console.log(index);
     console.log(list);
     console.log(path);

     // 过滤README.md文件，如果是该文件，就不显示
     if (filename.match('README.md')) {
         return '';
     } else {
         return filename;
     }
 }

 app.use(serveIndex('staticServer', options));

hidden

类型：Boolean

默认值：false

功能：是否隐藏文件名是“.”的文件。设置为true时，显示；设置为false时，不显示。

icons

显示文件图标。默认为false。

stylesheet

CSS样式表的可选路径。默认为内置样式表。

template

HTML模板的可选路径或将呈现HTML字符串的函数。默认为内置模板。

给定字符串时，该字符串将用作要加载的文件路径，然后在模板中替换以下标记：

• {directory} 使用目录的名称。
• {files} 使用无序的文件链接列表的HTML。
• {linked-path} 使用目录链接的HTML。
• {style} 使用指定的样式表和嵌入的图像。

当作为函数给出时，该函数被调用为template(locals, callback) ，并且需要调用它callback(error, htmlString)。以下是提供的当地人：

• directory是显示的目录（/根在哪里）。
• displayIcons 是否应该呈现图标的布尔值。
• fileList是目录中的已排序文件数组。该数组包含具有以下属性的对象：
  • name 是文件的相对名称。
  • stat是fs.Stats文件的对象。
• path是完整的文件系统路径directory。
• style是默认样式表或stylesheet选项的内容。
• viewName是view选项提供的视图名称。

view

类型：String

功能：显示模式。可选值："tiles"、"details"。默认为tiles。

说明：设置为details时，显示样子如下：

五 实现原理

通过上边用法可以知道，serveIndex方法返回一个中间件函数，这个中间件函数会在服务器接收到请求时执行，这个函数的主要功能是根据请求url地址，读取本地文件夹中对应的文件，创建一个HTML文件，生成文件列表DOM、样式等插入HTML文件中，并将这个HTML作为请求内容返回给浏览器显示，这样就实现了将文件夹内容显示到浏览器中了。

详细步骤如下：

5.1.serveIndex方法创建并返回中间件函数，该中间件函数作为app.use()的参数，这样就相当于给服务器注册了一个回调函数，当有请求过来时，就会调用该函数。

app.use(serveIndex('staticServer', options));

serveIndex的缩略代码（省去了返回的函数代码）如下：

 function serveIndex(root, options) {
     var opts = options || {};

     // root required
     if (!root) {
         throw new TypeError('serveIndex() root path required');
     }

     // resolve root to absolute and normalize
     var rootPath = normalize(resolve(root) + sep);

     var filter = opts.filter;
     var hidden = opts.hidden;
     var icons = opts.icons;
     var stylesheet = opts.stylesheet || defaultStylesheet;
     var template = opts.template || defaultTemplate;
     var view = opts.view || 'tiles';

     return function (req, res, next) {
         //...
     };
 };

5.2 当服务器受到浏览器请求时，会执行上边返回的中间的函数，该函数主要功能是根据请求url地址，读取本地文件夹中对应的文件，创建一个HTML文件，生成文件列表DOM、样式等插入HTML文件中，并将这个HTML作为请求内容返回给浏览器显示，这样就实现了将文件夹内容显示到浏览器中了。

重点代码片段如下：

通过NodeJS的fs文件接口读取请求路径中的文件：

       fs.readdir(path, function(err, files){
         if (err) return next(err);
         if (!hidden) files = removeHidden(files);
         if (filter) files = files.filter(function(filename, index, list) {
           return filter(filename, index, list, path);
         });
         files.sort();

         // content-negotiation
         var accept = accepts(req);
         var type = accept.type(mediaTypes);

         // not acceptable
         if (!type) return next(createError(406));
         serveIndex[mediaType[type]](req, res, files, next, originalDir, showUp, icons, path, view, template, stylesheet);
       });

上边代码中最后调用的serveIndex[mediaType[type]]，实际是调用serveIndex.html()方法，该方法主要做了2件事：创建HTML文件和文件列表DOM，并设置给请求头的body中。

     fs.readFile(stylesheet, 'utf8', function (err, style) {
       if (err) return next(err);

       // create locals for rendering
       var locals = {
         directory: dir,
         displayIcons: Boolean(icons),
         fileList: fileList,
         path: path,
         style: style,
         viewName: view
       };

       // render html
       render(locals, function (err, body) {
         if (err) return next(err);
         send(res, 'text/html', body)
       });
     });

 function createHtmlRender(template) {
   return function render(locals, callback) {
     // read template
     fs.readFile(template, 'utf8', function (err, str) {
       if (err) return callback(err);

       var body = str
         .replace(/\{style\}/g, locals.style.concat(iconStyle(locals.fileList, locals.displayIcons)))
         .replace(/\{files\}/g, createHtmlFileList(locals.fileList, locals.directory, locals.displayIcons, locals.viewName))
         .replace(/\{directory\}/g, escapeHtml(locals.directory))
         .replace(/\{linked-path\}/g, htmlPath(locals.directory));

       callback(null, body);
     });
   };
 }

 function send (res, type, body) {
   // security header for content sniffing
   res.setHeader('X-Content-Type-Options', 'nosniff')

   // standard headers
   res.setHeader('Content-Type', type + '; charset=utf-8')
   res.setHeader('Content-Length', Buffer.byteLength(body, 'utf8'))

   // body
   res.end(body, 'utf8')
 }

参考资料&内容来源：

Express官网：http://www.expressjs.com.cn/en/resources/middleware/serve-index.html