Flutter虚拟目录服务插件shelf_virtual_directory的使用

Flutter虚拟目录服务插件shelf_virtual_directory的使用

简介

shelf_virtual_directory 是一个用于 Dart 的 Shelf 服务器的插件，它提供了 Handler、Router 和 Cascade 来从文件系统中提供静态文件，并且可以与 WebSockets 一起工作。这个插件可以帮助你轻松地为你的 Shelf 服务器设置静态文件服务。

安装

1. 添加依赖
   在 pubspec.yaml 文件中添加 shelf_virtual_directory 依赖：

   dependencies:
     shelf_virtual_directory: latest_version
   

2. 获取依赖
   运行以下命令来获取依赖：

   pub get
   

3. 导入库
   在 Dart 文件中导入 shelf_virtual_directory 和 path 包：

   import 'package:shelf_virtual_directory/shelf_virtual_directory.dart';
   import 'package:path/path.dart' as p;
   

4. 创建 ShelfVirtualDirectory 实例
   创建一个 ShelfVirtualDirectory 实例，指定要提供的静态文件所在的目录（例如 web 目录），并设置默认的索引文件和 404 页面：

   final fsPath = p.join(Directory.current.path, 'example', 'web'); // 服务器文件路径
   final virtualDir = ShelfVirtualDirectory(
     fsPath,
     defaultFile: 'index.html', // 默认索引文件
     default404File: '404.html', // 404 页面
   );
   

   注意：index.html 和 404.html 文件必须直接放在根目录下。在上面的例子中，应该放在 web/ 目录下。

使用场景

1. 作为 Handler 使用

你可以将 ShelfVirtualDirectory 作为 Handler 使用，将其添加到 Pipeline 中，以便在请求时处理静态文件：

final virDirHandler = ShelfVirtualDirectory(fsPath).handler;

final staticFileHandler = const Pipeline()
    .addMiddleware(logRequests()) // 添加日志中间件
    .addHandler(virDirHandler); // 使用作为处理器

await io.serve(Cascade().add(staticFileHandler).handler, address, port)
    .then((server) {
  print('Server is running at ${server.address}:${server.port}');
});

2. 作为 Router 使用

你可以将 ShelfVirtualDirectory 作为 Router 的子路由挂载，这样可以在不同的路径下提供静态文件：

// 作为子路由挂载
final router = Router()
  ..get('/otherroute', otherRouteHandler) // 其他路由
  ..mount('/', ShelfVirtualDirectory(fsPath).router); // 挂载到根路径 (localhost:8080/)

// 或者挂载到特定路径
final router = Router()
  ..get('/otherroute', otherRouteHandler)
  ..mount('/home/', ShelfVirtualDirectory(fsPath).router); // 挂载到 /home/ 路径 (localhost:8080/home/)

// 注意：如果你打算在根目录 ('/') 下使用 `ShelfVirtualDirectory`，请确保将其挂载或处理到最后。
final mainRoute = Router()
  ..get('/rest', (_) => Response.ok('Other routes'))
  ..mount('/', ShelfVirtualDirectory(fsPath).router);

3. 作为 Cascade 使用

你也可以将 ShelfVirtualDirectory 作为 Cascade 使用，直接在服务器中添加其他处理器：

import 'package:shelf/shelf_io.dart' as io show serve;

// 你可以在此处添加其他处理器
final virDirCascade = ShelfVirtualDirectory(fsPath).cascade;
await io.serve(virDirCascade.add(someOtherHandler), 'localhost', 8080)
    .then((server) {
  print('Server is running at ${server.address}:${server.port}');
});

限制

• 只有 mount 方法支持用于 Router。例如：

  final router = Router()
      ..mount('/home/', virDir.handler)
      ..get('/api', apiHandler);
  

完整示例代码

以下是一个完整的示例代码，展示了如何使用 shelf_virtual_directory 提供静态文件服务：

import 'dart:io';

import 'package:path/path.dart' as p;
import 'package:shelf/shelf.dart' show Pipeline, Response, logRequests;
import 'package:shelf/shelf_io.dart' as io show serve;
import 'package:shelf_router/shelf_router.dart';
import 'package:shelf_virtual_directory/shelf_virtual_directory.dart';

Future<void> main(List<String> args) async {
  // 静态文件目录
  const folderToServe = 'web';
  final address = InternetAddress.loopbackIPv4;
  final port = int.parse(Platform.environment['PORT'] ?? '8082');

  // 创建 [ShelfVirtualDirectory] 实例并提供 [Router] 实例
  final folderPath = p.join(
    Directory.current.path,
    'example',
    folderToServe,
  );
  final virDir = ShelfVirtualDirectory(folderPath);

  // 定义路由
  final apiRouter = Router()
    ..mount('/routerstatic/', virDir.router) // 挂载到 /routerstatic/
    ..mount('/mountstatic/', virDir.handler) // 挂载到 /mountstatic/
    ..mount('/nodirlisting/',
        ShelfVirtualDirectory(folderPath, listDirectory: false).handler) // 禁用目录列表
    ..get('/getstatic/', virDir.handler) // GET 请求 /getstatic/
    ..get('/api/user', (_) => Response.ok('/api/user')) // GET 请求 /api/user
    ..get('/api', (_) => Response.ok('/api')) // GET 请求 /api
    ..mount('/', virDir.handler); // 挂载到根路径

  // 使用 [Pipeline] 添加日志中间件
  final pipeline = const Pipeline().addMiddleware(logRequests()).addHandler(apiRouter);

  // 启动服务器
  final server = await io.serve(
    pipeline,
    address,
    port,
  );

  print('Server is running at http://${server.address.host}:${server.port}');
}