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