在 Flutter 中使用 dio
应用程序开发的一个关键部分是优雅地处理网络请求。网络返回的响应可能包含意想不到的结果,为了获得良好的用户体验,您需要提前处理边缘情况。
关于如何使用 HTTP 包,可以看我的上一篇文章https://xie.infoq.cn/article/cdc7d247b4a5c73a6ddd797b9
在本文中,我们将看看如何使用 Dio 包在 Flutter 中处理 REST API 请求。
什么是 dio?
Dio是Dart的强大 HTTP 客户端。它支持拦截器、全局配置、FormData
请求取消、文件下载和超时等。Flutter 提供了一个http 包,它非常适合执行基本的网络任务,但在处理一些高级功能时使用起来却非常令人生畏。相比之下,Dio 提供了一个直观的 API,可以轻松执行高级网络任务。
入门
让我们开始创建一个新的 Flutter 项目。使用以下命令:
flutter create flutter_dio_networking
复制代码
您可以使用您最喜欢的 IDE 打开该项目,但在本示例中,我将使用 VS Code:
code flutter_dio_networking
复制代码
将 Dio 包添加到您的pubspec.yaml
文件中:
dio: ^4.0.4
复制代码
将文件内容替换为以下内容:main.dart
import 'package:flutter/material.dart'; void main() { runApp(MyApp()); } class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { return MaterialApp( title: 'Dio Networking', theme: ThemeData( primarySwatch: Colors.blue, ), debugShowCheckedModeBanner: false, home: HomePage(), ); } }
我们将在HomePage
获取网络数据后定义类。
现在,让我们看一下我们将用于演示的网络数据。
使用 API 数据进行测试
我们将使用REQ | RES来测试我们的网络数据,因为它为您提供了由示例用户数据组成的托管 REST API,并允许您执行各种网络操作测试。
我们将首先执行一个简单的 GET 请求来获取数据。所需的端点是:Single User
GET https://reqres.in/api/users/<id>
复制代码
请注意,此处<id>
必须替换为对应于并用于查找特定用户的整数值。
以下是请求成功时示例 JSON 响应的样子:
{ "data": { "id": 2, "email": "janet.weaver@reqres.in", "first_name": "Janet", "last_name": "Weaver", "avatar": "https://reqres.in/img/faces/2-image.jpg" } }
定义模型类
如果您想轻松处理从 REST API 请求返回的数据,您需要定义一个模型类。
现在,我们将定义一个简单的类来存储单个用户数据。您可以互换使用纯 Dart 代码或库,而无需在同一个示例应用程序中进行任何其他更改。我们将像这样手动定义一个模型类:
class User { User({ required this.data, }); Data data; factory User.fromJson(Map<String, dynamic> json) => User( data: Data.fromJson(json["data"]), ); Map<String, dynamic> toJson() => { "data": data.toJson(), }; }
为了防止手动定义时可能发生的任何未注意到的错误,您可以使用 JSON 序列化并自动生成工厂方法。
为此,您将需要以下软件包:
json_serializable
json_annotation
build_runner
将它们添加到您的文件中:pubspec.yaml
dependencies: json_annotation: ^4.0.1 dev_dependencies: json_serializable: ^4.1.3 build_runner: ^2.0.4
将用户和数据类分成两个 Dart 文件 -和,并分别修改它们的内容。user.dart``data.dart
该User
级内容将作如下安排:
import 'package:json_annotation/json_annotation.dart'; import 'data.dart'; part 'user.g.dart'; @JsonSerializable() class User { User({ required this.data, }); Data data; factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json); Map<String, dynamic> toJson() => _$UserToJson(this); }
该Data
级内容将作如下安排:
import 'package:json_annotation/json_annotation.dart'; part 'data.g.dart'; @JsonSerializable() class Data { Data({ required this.id, required this.email, required this.firstName, required this.lastName, required this.avatar, }); int id; String email; @JsonKey(name: 'first_name') String firstName; @JsonKey(name: 'last_name') String lastName; String avatar; factory Data.fromJson(Map<String, dynamic> json) => _$DataFromJson(json); Map<String, dynamic> toJson() => _$DataToJson(this); }
的fromJson
和toJson
方法将通过生成json_serializable
包。一些类属性被注释,@JsonKey
因为 Map 中定义的名称(并由 API 请求返回)与其属性名称不同。
您可以使用以下命令触发代码生成:
flutter pub run build_runner build
保持代码生成器在服务器中运行,以便对类的任何新更改都会自动触发代码生成。使用以下命令执行此操作:
flutter pub run build_runner serve --delete-conflicting-outputs
复制代码
如果发现任何冲突,--delete-conflicting-outputs
标志有助于重新生成类的一部分。
初始化 Dio
您可以创建一个单独的类,其中包含用于执行网络操作的方法。这有助于将功能逻辑与用户界面代码分开。
为此,请创建一个新的文件:dio_client.dart
包含DioClient
class DioClient { // TODO: Set up and define the methods for network operations }
您可以使用以下方法初始化 Dio:
import 'package:dio/dio.dart'; class DioClient { final Dio _dio = Dio();}
定义 API 服务器的基本 URL:
import 'package:dio/dio.dart'; class DioClient { final Dio _dio = Dio(); final _baseUrl = 'https://reqres.in/api'; // TODO: Add methods}
现在,我们可以定义执行网络请求所需的方法。
定义 GET 请求
我们将定义一个通过传递一个从 API 检索单个用户数据的方法id
:
Future<User> getUser({required String id}) async { // Perform GET request to the endpoint "/users/<id>" Response userData = await _dio.get(_baseUrl + '/users/$id'); // Prints the raw data returned by the server print('User Info: ${userData.data}'); // Parsing the raw JSON data to the User class User user = User.fromJson(userData.data); return user; }
上述方法有效,但如果这里有任何编码错误,应用程序会在您运行时崩溃。
一种更好、更实用的方法是用块包装方法:get()``try-catch
Future<User?> getUser({required String id}) async { User? user; try { Response userData = await _dio.get(_baseUrl + '/users/$id'); print('User Info: ${userData.data}'); user = User.fromJson(userData.data); } on DioError catch (e) { // The request was made and the server responded with a status code // that falls out of the range of 2xx and is also not 304. if (e.response != null) { print('Dio error!'); print('STATUS: ${e.response?.statusCode}'); print('DATA: ${e.response?.data}'); print('HEADERS: ${e.response?.headers}'); } else { // Error due to setting up or sending the request print('Error sending request!'); print(e.message); } } return user; }
在这个例子中,我们还设置了User
可为空的,以便在出现任何错误时,服务器将返回null
而不是任何实际的用户数据。
为了显示用户数据,我们必须构建HomePage
类。创建一个名为home_page.dart
的新文件并向其中添加以下内容:
class HomePage extends StatefulWidget { @override _HomePageState createState() => _HomePageState(); } class _HomePageState extends State<HomePage> { final DioClient _client = DioClient(); @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: Text('User Info'), ), body: Center( child: FutureBuilder<User?>( future: _client.getUser(id: '1'), builder: (context, snapshot) { if (snapshot.hasData) { User? userInfo = snapshot.data; if (userInfo != null) { Data userData = userInfo.data; return Column( mainAxisSize: MainAxisSize.min, children: [ Image.network(userData.avatar), SizedBox(height: 8.0), Text( '${userInfo.data.firstName} ${userInfo.data.lastName}', style: TextStyle(fontSize: 16.0), ), Text( userData.email, style: TextStyle(fontSize: 16.0), ), ], ); } } return CircularProgressIndicator(); }, ), ), ); } }
在_HomePageState
类内部,DioClient
首先实例化。然后,在build
方法内部, FutureBuilder
用于检索和显示用户数据。CircularProgressIndicator
获取结果时将显示。
定义 POST 请求
您可以使用 POST 请求将数据发送到 API。让我们尝试发送请求并创建一个新用户。
首先,我将定义另一个模型类,因为这个 JSON 数据的属性将与之前定义的User
模型类不同,用于处理我们必须发送的用户信息:
import 'package:json_annotation/json_annotation.dart'; part 'user_info.g.dart'; @JsonSerializable()class UserInfo { String name; String job; String? id; String? createdAt; String? updatedAt; UserInfo({ required this.name, required this.job, this.id, this.createdAt, this.updatedAt, }); factory UserInfo.fromJson(Map<String, dynamic> json) => _$UserInfoFromJson(json); Map<String, dynamic> toJson() => _$UserInfoToJson(this);}
复制代码
在DioClient
类中指定用于创建新用户的方法:
Future<UserInfo?> createUser({required UserInfo userInfo}) async { UserInfo? retrievedUser; try { Response response = await _dio.post( _baseUrl + '/users', data: userInfo.toJson(), ); print('User created: ${response.data}'); retrievedUser = UserInfo.fromJson(response.data); } catch (e) { print('Error creating user: $e'); } return retrievedUser;}
复制代码
这将一个UserInfo
对象作为参数,然后将其发送到 API 的端点。它返回一个带有新创建的用户信息和创建日期和时间的响应。/users
定义 PUT 请求
您可以使用 PUT 请求更新 API 服务器中存在的数据。
要在类中定义用于更新用户的新方法DioClient
,我们必须将更新的UserInfo
对象与id
要应用更新的用户的一起传递。
Future<UserInfo?> updateUser({ required UserInfo userInfo, required String id,}) async { UserInfo? updatedUser; try { Response response = await _dio.put( _baseUrl + '/users/$id', data: userInfo.toJson(), ); print('User updated: ${response.data}'); updatedUser = UserInfo.fromJson(response.data); } catch (e) { print('Error updating user: $e'); } return updatedUser;}
复制代码
上面的代码将向端点发送一个 PUT 请求/users/<id>
以及UserInfo
数据。然后它返回更新的用户信息以及更新的日期和时间。
定义 DELETE 请求
您可以使用 DELETE 请求从服务器中删除一些数据。
在DioClient
类中定义一个新方法,用于通过传递用户的 来从 API 服务器中删除id
用户。
Future<void> deleteUser({required String id}) async { try { await _dio.delete(_baseUrl + '/users/$id'); print('User deleted!'); } catch (e) { print('Error deleting user: $e'); }}
复制代码
选择和定义您的请求头
baseUrl
您可以在内部定义它BaseOptions
并在实例化时传递一次,而不是每次都传递端点Dio
。
为此,您需要进行Dio
如下初始化:
final Dio _dio = Dio( BaseOptions( baseUrl: 'https://reqres.in/api', connectTimeout: 5000, receiveTimeout: 3000, ),);
复制代码
此方法还提供各种其他自定义设置——在同一个示例中,我们为请求定义了connectTimeout
和receiveTimeout
。
上传文件
Dio 使上传文件到服务器的过程变得更加简单。它可以同时处理多个文件上传,并有一个简单的回调来跟踪它们的进度,这使得它比http
包更容易使用。
您可以使用FormData
Dio 轻松地将文件上传到服务器。以下是向 API 发送图像文件的示例:
String imagePath; FormData formData = FormData.fromMap({ "image": await MultipartFile.fromFile( imagePath, filename: "upload.jpeg", ),}); Response response = await _dio.post( '/search', data: formData, onSendProgress: (int sent, int total) { print('$sent $total'); },);
复制代码
拦截器
您可以在使用then
处理 Dio 请求、响应错误之前拦截它们catchError
。在实际场景中,拦截器可用于使用JSON Web Tokens (JWT)进行授权、解析 JSON、处理错误以及轻松调试 Dio 网络请求。
您可以通过重写回调运行拦截:onRequest
,onResponse
,和onError
。
对于我们的示例,我们将定义一个简单的拦截器来记录不同类型的请求。创建一个名为Logging
从Interceptor
以下扩展的新类:
import 'package:dio/dio.dart'; class Logging extends Interceptor { @override void onRequest(RequestOptions options, RequestInterceptorHandler handler) { print('REQUEST[${options.method}] => PATH: ${options.path}'); return super.onRequest(options, handler); } @override void onResponse(Response response, ResponseInterceptorHandler handler) { print( 'RESPONSE[${response.statusCode}] => PATH: ${response.requestOptions.path}', ); return super.onResponse(response, handler); } @override void onError(DioError err, ErrorInterceptorHandler handler) { print( 'ERROR[${err.response?.statusCode}] => PATH: ${err.requestOptions.path}', ); return super.onError(err, handler); }}
复制代码
在这里,我们覆盖了由 Dio 请求触发的各种回调,并为每个回调添加了一个打印语句,用于在控制台中记录请求。
Dio
在初始化期间添加拦截器:
final Dio _dio = Dio( BaseOptions( baseUrl: 'https://reqres.in/api', connectTimeout: 5000, receiveTimeout: 3000, ), )..interceptors.add(Logging());
复制代码
调试控制台中记录的结果将如下所示:
结论
在 Flutter 中使用 Dio 网络感觉简直不要太爽,它可以优雅地处理许多边缘情况。Dio 可以更轻松地处理多个同时发生的网络请求,同时具有高级错误处理能力。它还允许您避免使用 http 包跟踪任何文件上传进度所需的样板代码。您还可以使用 Dio 包进行各种其他高级自定义,这些自定义超出了我们在此处介绍的内容。