flutter-networking

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flutter Networking

Flutter 网络开发

Quick Start

快速开始

Add HTTP dependency to

pubspec.yaml

yaml

dependencies:
  http: ^1.6.0

Basic GET request:

dart

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<Album> fetchAlbum() async {
  final response = await http.get(
    Uri.parse('https://api.example.com/albums/1'),
  );

  if (response.statusCode == 200) {
    return Album.fromJson(jsonDecode(response.body));
  } else {
    throw Exception('Failed to load album');
  }
}

Use in UI with

FutureBuilder

dart

FutureBuilder<Album>(
  future: futureAlbum,
  builder: (context, snapshot) {
    if (snapshot.hasData) {
      return Text(snapshot.data!.title);
    } else if (snapshot.hasError) {
      return Text('${snapshot.error}');
    }
    return const CircularProgressIndicator();
  },
)

在

pubspec.yaml

中添加HTTP依赖：

yaml

dependencies:
  http: ^1.6.0

基础GET请求：

dart

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<Album> fetchAlbum() async {
  final response = await http.get(
    Uri.parse('https://api.example.com/albums/1'),
  );

  if (response.statusCode == 200) {
    return Album.fromJson(jsonDecode(response.body));
  } else {
    throw Exception('Failed to load album');
  }
}

结合

FutureBuilder

在UI中使用：

dart

FutureBuilder<Album>(
  future: futureAlbum,
  builder: (context, snapshot) {
    if (snapshot.hasData) {
      return Text(snapshot.data!.title);
    } else if (snapshot.hasError) {
      return Text('${snapshot.error}');
    }
    return const CircularProgressIndicator();
  },
)

HTTP Methods

HTTP 请求方法

GET - Fetch Data

GET - 获取数据

Use for retrieving data. See http-basics.md for complete examples.

用于检索数据。完整示例请参考http-basics.md。

POST - Create Data

POST - 创建数据

Use for creating new resources. Requires

Content-Type: application/json

header.

dart

final response = await http.post(
  Uri.parse('https://api.example.com/albums'),
  headers: <String, String>{
    'Content-Type': 'application/json; charset=UTF-8',
  },
  body: jsonEncode(<String, String>{'title': title}),
);

See http-basics.md for POST examples.

用于创建新资源。需要设置

Content-Type: application/json

请求头。

dart

final response = await http.post(
  Uri.parse('https://api.example.com/albums'),
  headers: <String, String>{
    'Content-Type': 'application/json; charset=UTF-8',
  },
  body: jsonEncode(<String, String>{'title': title}),
);

POST请求示例请参考http-basics.md。

PUT - Update Data

PUT - 更新数据

Use for updating existing resources.

dart

final response = await http.put(
  Uri.parse('https://api.example.com/albums/1'),
  headers: <String, String>{
    'Content-Type': 'application/json; charset=UTF-8',
  },
  body: jsonEncode(<String, String>{'title': title}),
);

用于更新现有资源。

dart

final response = await http.put(
  Uri.parse('https://api.example.com/albums/1'),
  headers: <String, String>{
    'Content-Type': 'application/json; charset=UTF-8',
  },
  body: jsonEncode(<String, String>{'title': title}),
);

DELETE - Remove Data

DELETE - 删除数据

Use for deleting resources.

dart

final response = await http.delete(
  Uri.parse('https://api.example.com/albums/1'),
  headers: <String, String>{
    'Content-Type': 'application/json; charset=UTF-8',
  },
);

用于删除资源。

dart

final response = await http.delete(
  Uri.parse('https://api.example.com/albums/1'),
  headers: <String, String>{
    'Content-Type': 'application/json; charset=UTF-8',
  },
);

WebSocket

Add WebSocket dependency:

yaml

dependencies:
  web_socket_channel: ^3.0.3

Basic WebSocket connection:

dart

import 'package:web_socket_channel/web_socket_channel.dart';

final _channel = WebSocketChannel.connect(
  Uri.parse('wss://echo.websocket.events'),
);

// Listen for messages
StreamBuilder(
  stream: _channel.stream,
  builder: (context, snapshot) {
    return Text(snapshot.hasData ? '${snapshot.data}' : '');
  },
)

// Send message
_channel.sink.add('Hello');

// Close connection
_channel.sink.close();

See websockets.md for complete WebSocket implementation.

添加WebSocket依赖：

yaml

dependencies:
  web_socket_channel: ^3.0.3

基础WebSocket连接：

dart

import 'package:web_socket_channel/web_socket_channel.dart';

final _channel = WebSocketChannel.connect(
  Uri.parse('wss://echo.websocket.events'),
);

// 监听消息
StreamBuilder(
  stream: _channel.stream,
  builder: (context, snapshot) {
    return Text(snapshot.hasData ? '${snapshot.data}' : '');
  },
)

// 发送消息
_channel.sink.add('Hello');

// 关闭连接
_channel.sink.close();

完整WebSocket实现请参考websockets.md。

Authentication

身份验证

Add authorization headers to requests:

dart

import 'dart:io';

final response = await http.get(
  Uri.parse('https://api.example.com/data'),
  headers: {HttpHeaders.authorizationHeader: 'Bearer $token'},
);

Common authentication patterns:

Bearer Token:
```
Authorization: Bearer <token>
```

Basic Auth:

Authorization: Basic <base64_credentials>

API Key:
```
X-API-Key: <key>
```

See authentication.md for detailed authentication strategies.

在请求中添加授权头：

dart

import 'dart:io';

final response = await http.get(
  Uri.parse('https://api.example.com/data'),
  headers: {HttpHeaders.authorizationHeader: 'Bearer $token'},
);

常见身份验证模式：

Bearer Token：
```
Authorization: Bearer <token>
```

Basic Auth：

Authorization: Basic <base64_credentials>

API Key：
```
X-API-Key: <key>
```

详细身份验证策略请参考authentication.md。

Error Handling

错误处理

Handle HTTP errors appropriately:

dart

if (response.statusCode >= 200 && response.statusCode < 300) {
  return Data.fromJson(jsonDecode(response.body));
} else if (response.statusCode == 401) {
  throw UnauthorizedException();
} else if (response.statusCode == 404) {
  throw NotFoundException();
} else {
  throw ServerException();
}

See error-handling.md for comprehensive error handling strategies.

合理处理HTTP错误：

dart

if (response.statusCode >= 200 && response.statusCode < 300) {
  return Data.fromJson(jsonDecode(response.body));
} else if (response.statusCode == 401) {
  throw UnauthorizedException();
} else if (response.statusCode == 404) {
  throw NotFoundException();
} else {
  throw ServerException();
}

全面错误处理模式请参考error-handling.md。

Performance

性能优化

Background Parsing with Isolates

使用Isolates进行后台解析

For large JSON responses, use

compute()

to parse in background isolate:

dart

import 'package:flutter/foundation.dart';

Future<List<Photo>> fetchPhotos(http.Client client) async {
  final response = await client.get(
    Uri.parse('https://api.example.com/photos'),
  );

  return compute(parsePhotos, response.body);
}

List<Photo> parsePhotos(String responseBody) {
  final parsed = (jsonDecode(responseBody) as List)
      .cast<Map<String, dynamic>>();
  return parsed.map<Photo>((json) => Photo.fromJson(json)).toList();
}

See performance.md for optimization techniques.

对于大型JSON响应，使用

compute()

在后台isolate中解析：

dart

import 'package:flutter/foundation.dart';

Future<List<Photo>> fetchPhotos(http.Client client) async {
  final response = await client.get(
    Uri.parse('https://api.example.com/photos'),
  );

  return compute(parsePhotos, response.body);
}

List<Photo> parsePhotos(String responseBody) {
  final parsed = (jsonDecode(responseBody) as List)
      .cast<Map<String, dynamic>>();
  return parsed.map<Photo>((json) => Photo.fromJson(json)).toList();
}

优化技巧请参考performance.md。

Integration with Architecture

与架构集成

When using MVVM architecture (see flutter-architecture):

Service Layer: Create HTTP service for API endpoints
Repository Layer: Aggregate data from services, handle caching
ViewModel Layer: Transform repository data for UI

Example service:

dart

class AlbumService {
  final http.Client _client;

  AlbumService(this._client);

  Future<Album> fetchAlbum(int id) async {
    final response = await _client.get(
      Uri.parse('https://api.example.com/albums/$id'),
    );

    if (response.statusCode == 200) {
      return Album.fromJson(jsonDecode(response.body));
    } else {
      throw Exception('Failed to load album');
    }
  }
}

当使用MVVM架构时（参考flutter-architecture）：

服务层：为API端点创建HTTP服务
仓库层：聚合来自服务的数据，处理缓存
视图模型层：转换仓库数据以适配UI

示例服务：

dart

class AlbumService {
  final http.Client _client;

  AlbumService(this._client);

  Future<Album> fetchAlbum(int id) async {
    final response = await _client.get(
      Uri.parse('https://api.example.com/albums/$id'),
    );

    if (response.statusCode == 200) {
      return Album.fromJson(jsonDecode(response.body));
    } else {
      throw Exception('Failed to load album');
    }
  }
}

Common Patterns

常见模式

Repository Pattern

仓库模式

Single source of truth for data type:

dart

class AlbumRepository {
  final AlbumService _service;
  final LocalStorage _cache;

  Future<Album> getAlbum(int id) async {
    try {
      return await _cache.getAlbum(id) ?? 
             await _service.fetchAlbum(id);
    } catch (e) {
      throw AlbumFetchException();
    }
  }
}

单一数据源：

dart

class AlbumRepository {
  final AlbumService _service;
  final LocalStorage _cache;

  Future<Album> getAlbum(int id) async {
    try {
      return await _cache.getAlbum(id) ?? 
             await _service.fetchAlbum(id);
    } catch (e) {
      throw AlbumFetchException();
    }
  }
}

Retry Logic

重试逻辑

Implement exponential backoff for failed requests:

dart

Future<T> fetchWithRetry<T>(
  Future<T> Function() fetch, {
  int maxRetries = 3,
}) async {
  for (int i = 0; i < maxRetries; i++) {
    try {
      return await fetch();
    } catch (e) {
      if (i == maxRetries - 1) rethrow;
      await Future.delayed(Duration(seconds: 2 << i));
    }
  }
  throw StateError('Unreachable');
}

为失败请求实现指数退避：

dart

Future<T> fetchWithRetry<T>(
  Future<T> Function() fetch, {
  int maxRetries = 3,
}) async {
  for (int i = 0; i < maxRetries; i++) {
    try {
      return await fetch();
    } catch (e) {
      if (i == maxRetries - 1) rethrow;
      await Future.delayed(Duration(seconds: 2 << i));
    }
  }
  throw StateError('Unreachable');
}

Best Practices

最佳实践

DO

建议

Use type-safe model classes with
```
fromJson
```
factories
Handle all HTTP status codes appropriately
Parse JSON in background isolates for large responses
Implement retry logic for transient failures
Cache responses when appropriate
Use proper timeouts
Secure tokens and credentials

使用带
```
fromJson
```
工厂方法的类型安全模型类
合理处理所有HTTP状态码
对于大型响应，在后台isolates中解析JSON
为临时故障实现重试逻辑
适时缓存响应
使用适当的超时配置
保护令牌和凭据安全

DON'T

不建议

Parse JSON on main thread for large responses
Ignore error states in UI
Store tokens in source code or public repositories
Make requests without timeout configuration
Block UI thread with network operations
Throw generic exceptions without context

在主线程中解析大型JSON响应
在UI中忽略错误状态
在源代码或公共仓库中存储令牌
发起无超时配置的请求
用网络操作阻塞UI线程
抛出无上下文的通用异常

Resources

资源

references/

http-basics.md - Complete HTTP CRUD operations examples
websockets.md - WebSocket implementation patterns
authentication.md - Authentication strategies and token management
error-handling.md - Comprehensive error handling patterns
performance.md - Optimization techniques and best practices

http-basics.md - 完整HTTP CRUD操作示例
websockets.md - WebSocket实现模式
authentication.md - 身份验证策略与令牌管理
error-handling.md - 全面错误处理模式
performance.md - 优化技巧与最佳实践

assets/examples/

```
fetch_example.dart
```
- Complete GET request with FutureBuilder
```
post_example.dart
```
- POST request implementation
```
websocket_example.dart
```
- WebSocket client with stream handling
```
auth_example.dart
```
- Authenticated request example
```
background_parsing.dart
```
- compute() for JSON parsing

```
fetch_example.dart
```
- 结合FutureBuilder的完整GET请求示例
```
post_example.dart
```
- POST请求实现示例
```
websocket_example.dart
```
- 带流处理的WebSocket客户端示例
```
auth_example.dart
```
- 认证请求示例
```
background_parsing.dart
```
- 使用compute()进行JSON解析的示例

assets/code-templates/

```
http_service.dart
```
- Reusable HTTP service template
```
repository_template.dart
```
- Repository pattern template

```
http_service.dart
```
- 可复用HTTP服务模板
```
repository_template.dart
```
- 仓库模式模板