Flutter核心功能扩展插件dartcore的使用

Dartcore 是一个为 Dart 编程语言设计的极简且强大的 HTTP 服务器框架。它提供了一个简单的 API 来处理和路由 HTTP 请求，非常适合用于轻量级（不是非常轻量级，可以用于复杂的应用）的 Web 应用、API 或微服务。

特性

• 简单直观的路由
• 轻量且快速
• 最小依赖
• 易于构建 RESTful API
• 可定制的请求处理
• 看起来有点像 Flask :)

开始使用

安装

库

首先，确保你已经安装了 Dart SDK。然后，在你的 pubspec.yaml 文件中添加 dartcore 作为依赖项。

dependencies:
  dartcore: any

运行 dart pub get 来安装依赖。

命令行工具

你可以通过运行以下命令来安装它：

dart pub activate global dartcore

然后尝试：

dartcore --version

示例使用

按照以下简单步骤设置你的 Dartcore 服务器。

1. 创建一个新的 Dartcore 实例

import 'package:dartcore/dartcore.dart' as dartcore;

// "" 是配置文件路径
final app = dartcore.App(debug: true); // 在生产模式下替换为 false！这指定了调试模式

2. 添加路由

使用 route 方法来处理传入的 HTTP 请求。指定 HTTP 方法（例如 GET、POST 等）和路由。

app.route('GET', '/', (req, res) {
  res.send("Hello from Dartcore!", ContentType.text);
});

app.route('GET', '/hello', (req, res) {
  res.json({"from":"Dartcore","message":"Hello World!"});
});

3. 启动服务器

使用 start 方法启动服务器。

app.start(port: 8080);

可选参数

• (String) <code>address</code>: 服务器的 IP 地址（默认：0.0.0.0 -> 所有 IP 地址）
• (int) <code>port</code>: 服务器监听的端口（默认：8080）

完整示例

完整的示例可以在 pub.dev 查看！

运行服务器

运行你的 Dart 服务器：

dart run

访问 http://127.0.0.1:8080/、http://localhost:8080/ 或 http://YOUR_PRIVATE_IP:8080/ 来查看服务器是否正常运行！

示例代码

以下是完整的示例代码，展示了如何使用 Dartcore 构建一个简单的 Web 服务器。

import 'dart:io';
import 'package:dartcore/apikeymanager.dart';
import 'package:dartcore/blocker.dart';
import 'package:dartcore/custom_template_engines/json.dart';
import 'package:dartcore/dartcore.dart' as dartcore;
import 'package:dartcore/hotreload.dart';
import 'package:dartcore/rate_limiter.dart';

final app = dartcore.App(
    debug: true,
    useHttps: false,
    // sslOptions: SSLOptions(keyFile: "./private.key", certificate: "./certificate.crt"),
    metadata: {
      "version": "1.0.0",
      "description": "Dartcore Example",
      "title": "Example",
    }); // 可选的配置，但可能有助于减少重复代码

final apiKeyManager = ApiKeyManager();
final IPBlocker ipBlocker = IPBlocker();
final RateLimiter rateLimiter = RateLimiter(
  shouldDisplayCaptcha: true,
  storagePath: "./ratelimits",
  maxRequests: 2,
  resetDuration: Duration(hours: 1),
  encryptionPassword: "encryptionPassword",
  ipBlocker: ipBlocker,
);

void main() async {
  app.setRateLimiter(rateLimiter);

  // app.use(app.apiKeyMiddleware(apiKeyManager));           // 不需要此示例，将使所有路由需要 API 密钥
  app.setupApiKeyRoutes(apiKeyManager);

  // 自定义 500 错误
  app.set500((request, error) {
    request.response
      ..statusCode = HttpStatus.internalServerError
      ..write('Custom 500 Internal Server Error: $error\n')
      ..close();
  });

  app.openApi();

  // WebSocket 支持
  app.ws('/ws', (socket) {
    print('[App] WebSocket connection established');
    socket.listen((message) {
      print('Received: $message');
      socket.add('[App] $message');
    }, onDone: () {
      print('[App] WebSocket connection closed');
    });
  });

  app.route('GET', '/data', (req, res) async {
    final cacheKey = 'data_key';
    final cachedData = app.getCachedResponse(cacheKey);

    if (cachedData != null) {
      await res.json(cachedData); // 发送缓存响应
    } else {
      // 模拟获取数据
      final data = {'key': 'value'};
      app.cacheResponse(cacheKey, data); // 缓存响应
      await res.json(data); // 发送新鲜响应
    }
  }, metadata: {
    'summary': 'A route',
    'operationId': 'getMain',
    'responses': {
      '200': {
        'description': 'Successful Response',
        'content': {
          'application/json': {'type': 'string'}
        }
      }
    }
  });

  // 事件测试
  app.route('GET', '/d', (req, res) async {
    app.emit('dataRequested', {'path': req.uri.path}); // 发射事件
    final data = {'key': 'value'};
    await res.json(data);
  });

  // 关机时触发事件
  app.on('serverShutdown', (data) {
    print('Event: ${data['message']}');
  });

  // 监听事件
  app.on('dataRequested', (data) {
    print('Data requested from ${data['path']}');
  });

  // 使用错误处理中间件
  app.use(app.errorHandlingMiddleware());

  // 日志中间件
  app.use((request, next) async {
    print('[Middleware] ${request.method} ${request.uri}');
    await next();
  });

  // 获取配置
  app.route('GET', '/config', (req, res) async {
    final someSetting = app.getFromConfig('hi');
    await res.json({'hi': someSetting});
  });

  // 提供静态文件
  app.route('GET', '/static/<file>', (req, res) async {
    var filePath = req.uri.pathSegments[2];
    await app.serveStaticFile(req, 'static/$filePath');
  });

  // 渲染模板
  app.route('GET', '/hello', (req, res) async {
    final context = {
      'name': 'Alex',
      'version': dartcore.version,
      'showDetails': true,
      'email': 'alex@example.com',
      'subscription': 'Premium',
      'showItems': true,
      'items': ['Item 1', 'Item 2', 'Item 3']
    };
    await app.renderTemplate(req, './templates/child.html',
        context); // 渲染继承自 hello.html 的 child.html
  });

  app.get("/hello/v2", (req, res) async {
    await app.render(
        req,
        JsonTemplateEngine(),
        '{"hello": "world", "name": "{{ name }}", "version": "{{ version }}}"',
        {
          'name': 'Alex',
          'version': dartcore.version,
        });
  });

  // 处理 JSON POST 请求
  app.route('POST', '/json', (req, res) async {
    var jsonData = await app.parseJson(req);
    await res.json({'received': jsonData});
  });

  // 文件上传     -- 在执行前创建 "uploads" 目录，否则服务器会因为操作系统错误而崩溃。
  app.post('/upload', (req, res) async {
    await app.parseMultipartRequest(req, 'uploads');
    await res.send("File Uploaded Successfully!", ContentType.text);
  });

  app.get("/", (req, res) => res.html("<h1>Hello World!</h1>"));
  app.get("/test",
      (req, res) async => res.json({"request": await app.parseJson(req)}));
  app.get("/shutdown", (req, res) async {
    res.html(
        "<center><h1>Server is shutting down in 3 seconds...</h1></center>");
    Future.delayed(Duration(seconds: 3), () {
      app.shutdown();
    });
  });

  // 启用热重载 (仅在代码位于同一目录时有效)
  enableHotReload(app);

  // 启动服务器
  await app.start(port: 8080);
}