Flutter网络注解请求插件flutter_annotation_http的使用

Flutter网络注解请求插件flutter_annotation_http的使用

简介

flutter_annotation_http 是一个基于注解的 HTTP 请求库，它允许开发者通过简单的注解来定义 API 接口，从而简化网络请求的实现。本文将详细介绍如何使用 flutter_annotation_http 来处理常见的网络请求场景。

示例代码详解

1. 导入必要的依赖

首先，我们需要导入 flutter_annotation_http 和 http 库：

import 'dart:convert';

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

2. 定义API接口（基本用法）

我们可以通过注解来定义 API 接口，并指定基础 URL、参数和头信息：

// 定义API接口
[@Endpoint](/user/Endpoint)(
  baseUrl: 'https://jsonplaceholder.typicode.com', // 基础URL
  parameters: {'x-app-platform': 'ios'},          // 默认参数
  headers: {'x-lang-platform': 'Dart'},           // 默认头信息
)
abstract class JsonPlaceholderApi {
  factory JsonPlaceholderApi() => _$JsonPlaceholderApiImpl();

  // GET 请求：获取待办事项列表
  [@GET](/user/GET)('/todos')
  Future<List<TodoModel>> getTodos({String? title});

  // POST 请求：创建待办事项
  [@POST](/user/POST)('/todos')
  Future<TodoModel> createTodo(AddTodo data);
}

说明：

• [@Endpoint](/user/Endpoint) 注解用于定义 API 的基础配置。
• [@GET](/user/GET) 和 [@POST](/user/POST) 分别表示 GET 和 POST 请求。
• 参数可以通过方法参数传递，例如 title。

3. 自定义请求头

可以为特定请求添加自定义头信息或路径变量：

// 使用自定义头信息
[@PATCH](/user/PATCH)('/todos/{id}', headers: {'x-user-tag': '1'})
Future<TodoModel> patchTodo(String title);

[@PATCH](/user/PATCH)('/todos/{id}')
Future<TodoModel> patchTodo(@RequestHeader(name: 'x-user-type') String type);

说明：

• headers 属性可以在方法级别设置默认头信息。
• @RequestHeader 可以动态传入头信息。

4. 路径变量

当需要动态传入路径时，可以使用 [@PathVariable](/user/PathVariable) 注解：

[@GET](/user/GET)('/todos/{id}')
Future<TodoModel> getTodo([@PathVariable](/user/PathVariable)() String id);

说明：

• {id} 表示路径中的占位符，[@PathVariable](/user/PathVariable) 用于绑定实际值。

5. 自定义编码

如果需要对请求体进行自定义编码，可以使用 [@JsonObject](/user/JsonObject) 和 [@RequestBody](/user/RequestBody) 注解：

// 定义待办事项数据模型
[@JsonObject](/user/JsonObject)()
class AddTodo {
  final String title;
  final String body;
  final int userId;

  AddTodo({required this.title, required this.body, required this.userId});

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

// 定义更新请求
[@PUT](/user/PUT)('/todos/{id}', consume: RequestMapping.jsonHeader)
Future<TodoModel> updateTodo([@RequestBody](/user/RequestBody)(_todoToJson) AddTodo data);

Map _todoToJson(AddTodo todo) => todo.toJson();

说明：

• [@JsonObject](/user/JsonObject) 表示该类需要序列化。
• _todoToJson 是一个自定义的 JSON 编码函数。

6. 文件上传

支持多部分表单上传文件：

[@Multipart](/user/Multipart)('/upload', timeout: 60 * 1000)
Future<void> upload(String from,
    @FilePart(filename: 'image', contentType: 'image/jpeg') String imagePath);

说明：

• [@Multipart](/user/Multipart) 表示这是一个多部分表单请求。
• @FilePart 用于指定文件路径和 MIME 类型。

7. 原始响应

如果需要直接获取原始响应（如 JSON、二进制流等），可以使用以下方式：

[@DELETE](/user/DELETE)('/todos/{id}')
Future<http.Response> deleteTodo([@PathVariable](/user/PathVariable)() int id);

[@GET](/user/GET)('/bytes/{n}', produce: RequestMapping.byteHeader)
Future<Uint8List> runBytes([@PathVariable](/user/PathVariable)() int n);

[@GET](/user/GET)('/json', produce: RequestMapping.jsonHeader)
Future<Map> getJson();

[@GET](/user/GET)('/robots.txt', produce: RequestMapping.textHeader)
Future<String> getRobotsTxt();

说明：

• produce 属性用于指定响应类型。
• 返回值可以直接是 http.Response 或其他格式。

8. HTTP 链路

支持链式调用：

factory JsonPlaceholderApi([HttpChain? chain]) => _$JsonPlaceholderApiImpl(chain);

9. 取消请求

支持取消请求功能：

[@GET](/user/GET)('/status')
Future<void> cancelRequest(CancelToken cancelToken);

说明：

• CancelToken 可以用于手动取消请求。

完整示例代码

以下是一个完整的示例代码，展示了如何使用 flutter_annotation_http 来处理网络请求：

import 'dart:convert';

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

// 定义待办事项模型
[@JsonObject](/user/JsonObject)()
class TodoModel {
  final int userId;
  final int id;
  final String title;
  final bool completed;

  TodoModel({
    required this.userId,
    required this.id,
    required this.title,
    required this.completed,
  });

  factory TodoModel.fromJson(Map<String, dynamic> json) {
    return TodoModel(
      userId: json['userId'],
      id: json['id'],
      title: json['title'],
      completed: json['completed'],
    );
  }
}

// 定义新增待办事项模型
[@JsonObject](/user/JsonObject)()
class AddTodo {
  final String title;
  final String body;
  final int userId;

  AddTodo({required this.title, required this.body, required this.userId});

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

// 定义API接口
[@Endpoint](/user/Endpoint)(
  baseUrl: 'https://jsonplaceholder.typicode.com',
  parameters: {'x-app-platform': 'ios'},
  headers: {'x-lang-platform': 'Dart'},
)
abstract class JsonPlaceholderApi {
  factory JsonPlaceholderApi() => _$JsonPlaceholderApiImpl();

  [@GET](/user/GET)('/todos')
  Future<List<TodoModel>> getTodos({String? title});

  [@POST](/user/POST)('/todos')
  Future<TodoModel> createTodo(AddTodo data);

  [@PATCH](/user/PATCH)('/todos/{id}', headers: {'x-user-tag': '1'})
  Future<TodoModel> patchTodo(String title);

  [@GET](/user/GET)('/todos/{id}')
  Future<TodoModel> getTodo([@PathVariable](/user/PathVariable)() String id);

  [@PUT](/user/PUT)('/todos/{id}', consume: RequestMapping.jsonHeader)
  Future<TodoModel> updateTodo([@RequestBody](/user/RequestBody)(_todoToJson) AddTodo data);

  [@Multipart](/user/Multipart)('/upload', timeout: 60 * 1000)
  Future<void> upload(String from,
      @FilePart(filename: 'image', contentType: 'image/jpeg') String imagePath);

  [@DELETE](/user/DELETE)('/todos/{id}')
  Future<http.Response> deleteTodo([@PathVariable](/user/PathVariable)() int id);
}

void main() async {
  // 初始化API实例
  var api = JsonPlaceholderApi();

  // 获取待办事项列表
  var todos = await api.getTodos(title: 'buy groceries');
  print('Todos: $todos');

  // 创建待办事项
  var newTodo = await api.createTodo(AddTodo(
    title: 'Learn flutter_annotation_http',
    body: 'It is very easy to use!',
    userId: 1,
  ));
  print('New Todo: $newTodo');

  // 更新待办事项
  var updatedTodo = await api.patchTodo('Updated Title');
  print('Updated Todo: $updatedTodo');

  // 获取单个待办事项
  var singleTodo = await api.getTodo(newTodo.id.toString());
  print('Single Todo: $singleTodo');

  // 删除待办事项
  var response = await api.deleteTodo(newTodo.id);
  print('Delete Response: $response');
}