Flutter Web服务框架插件xserver的使用_xserver是一个基于Dart语言的Web服务器框架

xserver是一个基于Dart语言的Web服务器框架，它通过源代码生成技术实现了自动注册处理器的功能，从而让管理与扩展Web服务器端点变得更加简单。本文将详细介绍如何使用xserver插件，并提供完整的示例代码。

特性

xserver具有以下特点：

• 自动处理器注册：利用注解自动注册处理器。
• 灵活的响应类型：支持返回多种类型，包括Future<T>、Stream<T>等。
• 类型安全的参数处理：通过注解处理查询参数、请求体、头信息及路径参数。
• 客户端代码生成：自动生成客户端代码，方便API调用。
• 异步上下文管理：可以通过XServer.currentRequest访问当前请求上下文。

入门指南

安装

首先，在项目的pubspec.yaml文件中添加xserver依赖：

dependencies:
  xserver: ^0.2.0

然后运行以下命令安装包：

dart pub get

使用示例

1. 定义服务器

创建一个类用于定义服务器，并使用@xServer注解。

import 'package:xserver/xserver.dart';

part 'app_server.g.dart'; // 自动生成的文件

@xServer
class AppServer extends _$AppServer {
}

2. 定义处理器

在AppServer类中定义不同的处理器，并使用注解指定HTTP方法和路径。

@xServer
class AppServer extends _$AppServer {
  // 处理GET请求
  @get
  Future<String> test({
    @query required String query,
    @body required Data body,
    @query required int query2,
    @header required String header,
    @header required int header2,
  }) async {
    return 'test';
  }

  // 处理带有路径参数的GET请求
  [@Get](/user/Get)('/user/<id>')
  Future<String> user(@path String id) async {
    return 'User: $id';
  }

  // 处理POST请求
  @Post('/data')
  Future<Data> data() async {
    return const Data(
      query: 'query',
      body: 'body',
      query2: 1,
      header: 'header',
      header2: 2,
    );
  }

  // 处理流式响应
  [@Get](/user/Get)('/stream')
  Stream<String> stream() async* {
    for (var i = 0; i < 100; i++) {
      yield 'stream $i';
      await Future.delayed(const Duration(seconds: 1));
    }
  }
}

3. 生成处理器代码

运行以下命令以生成处理器注册代码：

dart run build_runner build

4. 启动服务器

在主函数中启动服务器：

import 'package:xserver/xserver.dart';

void main() async {
  final server = AppServer();
  await server.start('localhost', 8080);
  print('Server listening on port 8080');
}

处理器注解

以下是常用的处理器注解：

• @All(path)：处理所有HTTP方法。
• [@Get](/user/Get)(path)：处理GET请求。
• @Post(path)：处理POST请求。

参数注解

以下是常见的参数注解：

• @Query([name])：提取查询参数。如果省略名称，则使用参数名。
• @Body()：提取请求体。
• @Header([name])：提取头信息。如果省略名称，则使用参数名。
• @Path([name])：提取路径参数。如果省略名称，则使用参数名。

响应类型

处理器可以返回以下几种类型：

• Future<T>：异步响应。
• Stream<T>：流式响应。
• T：同步响应（会自动包装为Future）。

其中，T可以是：

• String：文本响应。
• Map<String, dynamic>：JSON响应。
• 自定义类（具有toJson方法）：序列化为JSON。

客户端代码生成

xserver还生成了客户端代码，便于从其他部分调用API：

final client = AppServerClient('http://localhost:8080');
final result = await client.test(
  query: 'example',
  body: Data(...),
  query2: 42,
  header: 'some-header',
  header2: 123
);
print(result);

该客户端负责请求和响应的序列化与反序列化，简化了与其他模块交互的过程。

异步上下文管理

xserver使用区域上下文来管理异步请求。可以在任何地方通过XServer.currentRequest访问当前请求：

import 'package:xserver/xserver.dart';

[@Get](/user/Get)('/example')
Future<String> exampleHandler() async {
  final currentRequest = XServer.currentRequest;
  // 使用 currentRequest 作为所需数据
  return 'Handled asynchronously!';
}