Flutter插件dioxide的介绍与使用

Flutter插件dioxide的介绍与使用

Dioxide 是一个用于类型转换的 Dio 客户端生成器。

使用Flutter插件dioxide

添加依赖

在 pubspec.yaml 文件中添加以下依赖：

dependencies:
  dioxide: ^lastVersion

dev_dependencies:
  build_runner: ^2.2.0
  dioxide_generator: ^lastVersion

然后运行生成器：

# dart
pub run build_runner build

# flutter
flutter pub run build_runner build

定义并生成你的API

import 'package:json_annotation/json_annotation.dart';
import 'package:dio/dio.dart';
import 'package:dioxide/dioxide.dart';

part 'example.g.dart';

[@RestApi](/user/RestApi)(baseUrl: "http://localhost:8080/api/Task")
abstract class RestClient {
  factory RestClient(Dio dio, {String baseUrl}) = _RestClient;

  [@GetRequest](/user/GetRequest)()
  Future<List<Task>> getTasks();
}

@JsonSerializable()
class Task {
  String? id;
  String? name;
  String? avatar;
  String? createdAt;

  Task({this.id, this.name, this.avatar, this.createdAt});

  factory Task.fromJson(Map<String, dynamic> json) => _$TaskFromJson(json);

  Map<String, dynamic> toJson() => _$TaskToJson(this);
}

类型转换

在使用类型转换之前，请确保为每个模型类提供了一个 factory Task.fromJson(Map<String, dynamic> json) 方法。推荐使用 json_serializable 作为序列化工具。

@JsonSerializable()
class Task {
  String name;
  Task({this.name});
  factory Task.fromJson(Map<String, dynamic> json) => _$TaskFromJson(json);
}

HTTP方法

Dioxide 支持以下 HTTP 方法：

// 获取指定ID的任务
[@GetRequest](/user/GetRequest)("/tasks/{id}")
Future<Task> getTask(@Path("id") String id);

// 查询任务
[@GetRequest](/user/GetRequest)('/demo')
Future<String> queries([@Queries](/user/Queries)() Map<String, dynamic> queries);

// 带有查询参数的任务搜索
[@GetRequest](/user/GetRequest)("/search")
Future<String> namedExample(
    @Query("name") String name,
    @Query("tag") String tag,
);

// 部分更新任务
@PatchRequest("/tasks/{id}")
Future<Task> updateTaskPart(@Path() String id, @Body() Map<String, dynamic> map);

// 更新任务
@PutRequest("/tasks/{id}")
Future<Task> updateTask(@Path() String id, @Body() Task task);

// 删除任务
@DeleteRequest("/tasks/{id}")
Future<void> deleteTask(@Path() String id);

// 创建任务
@PostRequest("/tasks")
Future<Task> createTask(@Body() Task task);

// 从文件创建新任务
@PostRequest("/post")
Future<void> createNewTaskFromFile(@Part() File file);

// 提交编码为URL表单的数据
@PostRequest("/post")
@FormUrlEncoded()
Future<String> postUrlEncodedFormData(@Field() String hello);

获取原始HTTP响应

// 获取指定ID的任务
[@GetRequest](/user/GetRequest)("/tasks/{id}")
Future<HttpResponse<Task>> getTask(@Path("id") String id);

// 获取所有任务
[@GetRequest](/user/GetRequest)("/tasks")
Future<HttpResponse<List<Task>>> getTasks();

获取Dio响应

// 获取文件
[@GetRequest](/user/GetRequest)("/file/{fileId}")
[@DioResponseType](/user/DioResponseType)(ResponseType.stream)
Future<Response<ResponseBody>> getTask(@Path("fileId") String id);

HTTP头

动态添加HTTP头

[@GetRequest](/user/GetRequest)("/tasks")
Future<Task> getTasks(@Header("Content-Type") String contentType );

静态添加HTTP头

[@GetRequest](/user/GetRequest)("/tasks")
@Headers(<String, dynamic>{
	"Content-Type" : "application/json",
	"Custom-Header" : "Your header"
})
Future<Task> getTasks();

多个端点支持

如果你想要使用多个端点到 RestClient，你应该在初始化 RestClient 时传递基础 URL。在 RestApi 中定义的任何值将被忽略。

[@RestApi](/user/RestApi)(baseUrl: "this url will be ignored if baseUrl is passed")
abstract class RestClient {
  factory RestClient(Dio dio, {String baseUrl}) = _RestClient;
}

final client = RestClient(dio, baseUrl: "your base url");

如果你希望使用 dio.option.baseUrl 的基础 URL，并且优先级最低，请不要向 RestApi 注解和 RestClient 的构造方法传递任何参数。

设置请求超时

[@RestApi](/user/RestApi)(baseUrl: 'http://localhost:8080/api/Report')
[@RequestTimeout](/user/RequestTimeout)(connectTimeout: 5000, sendTimeout: 5000, receiveTimeout: 5000)
abstract class ReportClient {
  [@GetRequest](/user/GetRequest)("/generate")
  [@RequestTimeout](/user/RequestTimeout)(sendTimeout: 15000, receiveTimeout: 30000)
  [@DioResponseType](/user/DioResponseType)(ResponseType.stream)
  Future<Response<ResponseBody>> getTask([@Queries](/user/Queries)() Map<String, dynamic> queries);
}