Dart HttpClientRequest
最后修改于 2025 年 4 月 4 日
Dart 中的 HttpClientRequest 类代表一个 HTTP 客户端请求。它用于配置和向服务器发送 HTTP 请求。此类提供了设置标头、写入数据和管理请求生命周期的方法。
HttpClientRequest 是 Dart dart:io 库的一部分。它由 HttpClient 在打开连接时创建。该类支持各种 HTTP 方法，如 GET、POST、PUT 和 DELETE。
基本定义
HttpClientRequest 代表一个传出的 HTTP 请求。它提供了对请求标头、请求正文输出流和响应处理的访问。
主要功能包括标头操作、请求方法配置和基于流的正文写入。它与 HttpClientResponse 配合使用以实现完整的 HTTP 客户端功能。
基本的 GET 请求
此示例展示了如何使用 HttpClientRequest 进行简单的 GET 请求。
import 'dart:io';
import 'dart:convert';
Future<void> main() async {
var client = HttpClient();
try {
HttpClientRequest request = await client.getUrl(
Uri.parse('https://jsonplaceholder.typicode.com/posts/1')
);
HttpClientResponse response = await request.close();
var responseBody = await response.transform(utf8.decoder).join();
print('Status code: ${response.statusCode}');
print('Response body:\n$responseBody');
} finally {
client.close();
}
}
我们创建一个 HttpClient，然后使用 getUrl() 创建一个 GET 请求。配置完成后，我们关闭请求并等待响应。响应正文将从 UTF-8 解码。
$ dart main.dart
Status code: 200
Response body:
{
"userId": 1,
"id": 1,
"title": "...",
"body": "..."
}
带 JSON 正文的 POST 请求
此示例演示了发送带 JSON 数据的 POST 请求。
import 'dart:io';
import 'dart:convert';
Future<void> main() async {
var client = HttpClient();
try {
HttpClientRequest request = await client.postUrl(
Uri.parse('https://jsonplaceholder.typicode.com/posts')
);
request.headers.contentType = ContentType.json;
request.write(jsonEncode({
'title': 'foo',
'body': 'bar',
'userId': 1
}));
HttpClientResponse response = await request.close();
var responseBody = await response.transform(utf8.decoder).join();
print('Status code: ${response.statusCode}');
print('Response body:\n$responseBody');
} finally {
client.close();
}
}
我们创建一个 POST 请求，并将 Content-Type 标头设置为 application/json。请求正文以 JSON 编码的数据写入。服务器响应已创建的资源表示。
$ dart main.dart
Status code: 201
Response body:
{
"title": "foo",
"body": "bar",
"userId": 1,
"id": 101
}
设置自定义标头
此示例展示了如何为请求设置自定义标头。
import 'dart:io';
import 'dart:convert';
Future<void> main() async {
var client = HttpClient();
try {
HttpClientRequest request = await client.getUrl(
Uri.parse('https://httpbin.org/headers')
);
request.headers.add('X-Custom-Header', 'DartClient');
request.headers.add('Accept', 'application/json');
HttpClientResponse response = await request.close();
var responseBody = await response.transform(utf8.decoder).join();
print('Status code: ${response.statusCode}');
print('Response body:\n$responseBody');
} finally {
client.close();
}
}
我们使用 headers 属性向请求添加自定义标头。httpbin.org 服务在其响应中回显所有接收到的标头。这有助于验证标头的传输。
$ dart main.dart
Status code: 200
Response body:
{
"headers": {
"Accept": "application/json",
"Host": "httpbin.org",
"X-Custom-Header": "DartClient",
...
}
}
使用 PUT 请求上传文件
此示例演示了使用 PUT 请求上传文件。
import 'dart:io';
import 'dart:convert';
Future<void> main() async {
var client = HttpClient();
var file = File('example.txt');
try {
HttpClientRequest request = await client.putUrl(
Uri.parse('https://example.com/upload')
);
request.headers.contentType = ContentType.text;
request.contentLength = await file.length();
await request.addStream(file.openRead());
HttpClientResponse response = await request.close();
print('Upload complete. Status: ${response.statusCode}');
} finally {
client.close();
}
}
我们创建一个 PUT 请求，并根据文件大小设置内容长度。文件内容直接流式传输到请求正文中。这种方法对于大文件来说内存效率很高。
$ dart main.dart Upload complete. Status: 200
处理重定向
此示例展示了如何配置和处理 HTTP 重定向。
import 'dart:io';
import 'dart:convert';
Future<void> main() async {
var client = HttpClient();
try {
client.maxRedirects = 3; // Set maximum redirects
HttpClientRequest request = await client.getUrl(
Uri.parse('http://google.com')
);
request.followRedirects = true;
HttpClientResponse response = await request.close();
print('Final status: ${response.statusCode}');
print('Redirect count: ${response.redirects.length}');
print('Final URL: ${response.redirects.last?.location}');
} finally {
client.close();
}
}
我们配置客户端以遵循重定向并设置最大限制。响应对象包含有关发生的所有重定向的信息。这有助于调试和分析重定向链。
$ dart main.dart Final status: 200 Redirect count: 1 Final URL: https://www.google.com/
最佳实践
- 关闭请求：始终使用 close() 关闭请求
- 错误处理：实现适当的错误处理
- 流式传输数据：对大型有效负载使用流
- 重用客户端：尽可能重用 HttpClient 实例
- 设置超时：配置超时以提高可靠性
来源
本教程介绍了 Dart 的 HttpClientRequest 类，并通过实际示例展示了各种 HTTP 方法、标头、文件上传和重定向处理。
作者
列出 所有 Dart 教程。