ZetCode

Dart HttpHeaders

最后修改于 2025 年 4 月 4 日

Dart 中的 HttpHeaders 类提供了管理请求和响应的 HTTP Header 的功能。它是 Dart HTTP 库的一部分。

HttpHeaders 会自动处理 Header 名称的区分大小写、多个值以及诸如 content-length 之类的特殊 Header。它与 HttpClient 和 HttpServer 类一起使用。

基本定义

HttpHeaders 是一个表示 HTTP Header 的抽象类。它提供了添加、设置、删除和检查 Header 的方法。

主要功能包括不区分大小写的 Header 名称、值列表管理以及对 Cookie 和 Content Header 的特殊处理。一旦冻结，它是不可变的。

创建 HttpHeaders

此示例展示了如何创建和填充 HttpHeaders。

main.dart 
import 'dart:io';

void main() {
  var headers = HttpHeaders();
  
  headers.add('Content-Type', 'text/html');
  headers.add('X-Custom-Header', 'value1');
  headers.add('X-Custom-Header', 'value2');
  
  print('Content-Type: ${headers.value('content-type')}');
  print('X-Custom-Header: ${headers['x-custom-header']}');
}

我们创建 HttpHeaders 并添加多个 Header。Header 名称不区分大小写。同一个 Header 可以有多个值。可以通过名称访问值。

$ dart main.dart
Content-Type: text/html
X-Custom-Header: [value1, value2]

设置与添加 Header

此示例演示了 set 和 add 操作之间的区别。

main.dart 
import 'dart:io';

void main() {
  var headers = HttpHeaders();
  
  headers.add('Accept', 'text/html');
  headers.add('Accept', 'application/json');
  
  print('Before set: ${headers['accept']}');
  
  headers.set('Accept', 'image/png');
  
  print('After set: ${headers['accept']}');
  
  headers.remove('accept', 'image/png');
  print('After remove: ${headers['accept']}');
}

Add 追加值，而 set 则替换所有现有值。Remove 删除特定值。所有操作均不区分大小写。

$ dart main.dart
Before set: [text/html, application/json]
After set: [image/png]
After remove: []

Content Headers

此示例展示了对内容相关 Header 的特殊处理。

main.dart 
import 'dart:io';

void main() {
  var headers = HttpHeaders();
  
  headers.contentType = ContentType('text', 'html', charset: 'utf-8');
  headers.contentLength = 1024;
  headers.chunkedTransferEncoding = false;
  
  print('Content-Type: ${headers.contentType}');
  print('Content-Length: ${headers.contentLength}');
  print('Chunked: ${headers.chunkedTransferEncoding}');
}

Content Header 具有用于类型、长度和编码的专用属性。这些属性提供了对常见 HTTP 内容 Header 的类型安全访问。

$ dart main.dart
Content-Type: text/html; charset=utf-8
Content-Length: 1024
Chunked: false

Date 和 Cookie Headers

此示例演示了日期和 Cookie Header 的处理。

main.dart 
import 'dart:io';

void main() {
  var headers = HttpHeaders();
  var date = DateTime.now();
  
  headers.date = date;
  headers.add('Set-Cookie', 'id=a3fWa; Expires=Wed, 21 Oct 2025 07:28:00 GMT');
  headers.add('Set-Cookie', 'session=abc123; HttpOnly');
  
  print('Date: ${headers.date}');
  print('Cookies:');
  headers.forEach((name, values) {
    if (name == 'set-cookie') {
      values.forEach(print);
    }
  });
}

Date Header 使用 DateTime 对象进行处理。Cookie 可以作为字符串添加，但会进行特殊格式化。forEach 方法会遍历所有 Header。

$ dart main.dart
Date: 2025-04-04 12:34:56.789
Cookies:
id=a3fWa; Expires=Wed, 21 Oct 2025 07:28:00 GMT
session=abc123; HttpOnly

HttpClient 与 Headers

此示例展示了如何在 HttpClient 请求中使用 HttpHeaders。

main.dart 
import 'dart:io';
import 'dart:convert';

Future<void> main() async {
  var client = HttpClient();
  
  try {
    var request = await client.getUrl(Uri.parse('https://example.com'));
    
    request.headers.add('Accept', 'application/json');
    request.headers.add('User-Agent', 'Dart/3.0');
    request.headers.add('X-Request-ID', '12345');
    
    var response = await request.close();
    print('Status: ${response.statusCode}');
    
    var body = await response.transform(utf8.decoder).join();
    print('Response length: ${body.length}');
  } finally {
    client.close();
  }
}

我们创建一个带有自定义 Header 的 HTTP GET 请求。headers 属性是 HttpHeaders 实例。Header 会随请求一起发送到服务器。

$ dart main.dart
Status: 200
Response length: 1256

最佳实践

来源

Dart HttpHeaders 文档

本教程通过实际示例涵盖了 Dart 的 HttpHeaders 类，展示了 Header 管理、特殊 Header 以及 HTTP 客户端集成。

作者

我叫 Jan Bodnar，是一名热情的程序员，拥有丰富的编程经验。我自 2007 年以来一直在撰写编程文章。迄今为止，我已撰写超过 1,400 篇文章和 8 本电子书。我在教授编程方面拥有十多年的经验。

列出 所有 Dart 教程。