用途:在 Relic(Dart 服务端框架)中处理 HTTP 请求并构建响应,适用于读取请求数据、解析 JSON、构建 API 响应等场景。
请求对象:每个 handler 收到 Request,含 method(Method 枚举)、url、headers、body、pathParameters 与 queryParameters。headers 不可变;body 可变(中间件可替换),但底层流只能读取一次,重复读取抛 StateError。
查询参数:可用 queryParameters.raw 取原始值,或用类型化参数 IntQueryParam、DoubleQueryParam、NumQueryParam,缺失时抛错;加括号调用返回可空值。可自定义 QueryParam<T>(如 DateTime.parse)。多值使用 url.queryParametersAll。
请求头与授权:通过 req.headers 以类型安全方式读取 userAgent、contentLength 等;authorization 可识别 BearerAuthorizationHeader 与 BasicAuthorizationHeader。
读取请求体:req.readAsString() 取字符串;jsonDecode 解析 JSON;req.read() 返回 Stream<Uint8List>;read(maxLength:) 限制大小,超限抛 MaxBodySizeExceeded。
构建响应:可用 Response.ok、noContent、badRequest、unauthorized、notFound、internalServerError 等状态码构造器,或 Response(418, body: ...) 自定义。正文类型包括 Body.fromString(自动检测 JSON/HTML/XML/纯文本)、Body.fromData(自动检测 PNG/JPEG/PDF 等二进制)、Body.fromDataStream(流式,支持已知大小或分块)、Body.empty()。编码默认 UTF-8,可用 encoding 覆盖。
响应头与流式:通过 Headers.build 设置缓存控制与自定义头;流式响应可用 Body.fromDataStream 配合生成器。修改请求用 request.copyWith(请求本身不可变)。
限制:请求体流只能读一次;类型化查询参数缺失时会抛错,需注意处理;资料未提供更多框架级限制说明。