在 Flutter 中使用 http 插件进行 RESTful API 调用

一、Flutter 与 RESTful API 简介

（一）Flutter 概述

Flutter 是谷歌推出的一款开源 UI 框架，用于帮助开发者使用一套代码库，就能为移动、Web 和桌面等多平台构建高质量的原生用户界面。它采用 Dart 语言进行开发，拥有一套丰富的、可定制的 UI 组件库，能够快速实现各种复杂的界面设计。同时，Flutter 具备高性能和流畅的动画效果，为用户带来出色的体验。其热重载功能更是大大提高了开发效率，开发者可以在不重启应用的情况下，快速看到代码修改后的效果。

（二）RESTful API 概述

RESTful API（Representational State Transfer Application Programming Interface）是一种基于 HTTP 协议的软件架构风格，用于构建网络应用程序接口。它以资源为核心，每个资源都有对应的唯一标识符（URI）。客户端通过 HTTP 方法（如 GET、POST、PUT、DELETE 等）对这些资源进行操作。例如，GET 用于获取资源，POST 用于创建新资源，PUT 用于更新资源，DELETE 用于删除资源。RESTful API 具有简洁、可扩展、易于缓存等优点，在现代 Web 开发中被广泛应用。

二、http 插件介绍

（一）http 插件的功能与作用

在 Flutter 开发中，http 插件是官方推荐用于进行 HTTP 请求的库。它提供了简洁易用的 API，能够方便地发送各种类型的 HTTP 请求，并处理响应。通过 http 插件，开发者可以轻松地与 RESTful API 进行交互，获取数据或提交数据到服务器。例如，从服务器获取 JSON 格式的用户列表数据，或者将用户注册信息提交到服务器进行处理。

（二）安装与配置 http 插件

在 pubspec.yaml 文件中添加依赖 打开项目的 pubspec.yaml 文件，在 dependencies 部分添加以下内容：

http: ^0.13.4

这里的版本号 ^0.13.4 表示只要是大于等于 0.13.4 且小于 0.14.0 的版本都可以使用。你可以根据实际情况选择合适的版本。

获取依赖 在终端中进入项目目录，运行以下命令来获取依赖：

flutter pub get

这将下载 http 插件及其相关依赖，并将它们添加到项目中。

三、发送 GET 请求

（一）简单 GET 请求示例

假设我们有一个 RESTful API，用于获取一篇博客文章的列表，其 URL 为 https://example.com/api/blogs。我们可以使用以下代码发送 GET 请求并获取响应：

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

Future<List<dynamic>> fetchBlogs() async {
  final response = await http.get(Uri.parse('https://example.com/api/blogs'));

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

在上述代码中：

首先导入了 http 库和 dart:convert 库，dart:convert 库用于解析 JSON 数据。
fetchBlogs 函数是一个异步函数，它发送 GET 请求到指定的 URL。http.get 方法返回一个 Future<Response>，await 关键字用于等待这个 Future 完成，即等待响应返回。
检查响应的状态码，如果状态码为 200，表示请求成功，使用 jsonDecode 方法将响应体（通常是 JSON 格式的数据）解析为 Dart 对象并返回。如果状态码不为 200，则抛出异常。

（二）处理带有参数的 GET 请求

有时，我们需要在 GET 请求中传递参数。例如，我们可能只想获取特定分类的博客文章，这时可以在 URL 中添加参数。假设 API 支持通过 category 参数来筛选博客文章，示例代码如下：

Future<List<dynamic>> fetchBlogsByCategory(String category) async {
  final response = await http.get(Uri.parse('https://example.com/api/blogs?category=$category'));

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

在这个例子中，fetchBlogsByCategory 函数接受一个 category 参数，并将其拼接到 URL 中作为查询参数。这样，服务器就能根据这个参数返回相应分类的博客文章列表。

（三）处理响应头和响应体

除了获取响应体中的数据，有时我们还需要获取响应头的信息。http 插件的 Response 对象提供了访问响应头的方法。以下是一个示例，展示如何同时获取响应头和响应体：

Future<void> fetchBlogsWithHeaders() async {
  final response = await http.get(Uri.parse('https://example.com/api/blogs'));

  if (response.statusCode == 200) {
    print('Response Headers: ${response.headers}');
    final blogs = jsonDecode(response.body);
    print('Blogs: $blogs');
  } else {
    throw Exception('Failed to load blogs');
  }
}

在上述代码中，response.headers 返回一个包含响应头信息的 Map<String, String>。通过打印这个 Map，我们可以查看诸如 Content - Type、Date 等响应头字段。

四、发送 POST 请求

（一）简单 POST 请求示例

假设我们有一个用户注册的 API，URL 为 https://example.com/api/register，需要提交用户名和密码。可以使用以下代码发送 POST 请求：

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

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

  if (response.statusCode == 201) {
    print('User registered successfully');
  } else {
    throw Exception('Failed to register user');
  }
}

在这段代码中：

http.post 方法用于发送 POST 请求。
headers 字段设置了请求头，这里设置了 Content - Type 为 application/json; charset=UTF - 8，表示请求体的数据格式为 JSON 且字符编码为 UTF - 8。
body 字段通过 jsonEncode 方法将用户名和密码转换为 JSON 格式的字符串，并作为请求体发送。
检查响应状态码，如果为 201（表示资源已成功创建），则打印成功信息，否则抛出异常。

（二）处理复杂的 POST 请求体

如果我们的注册 API 还需要更多的用户信息，比如邮箱、年龄等，请求体将变得更加复杂。示例如下：

Future<void> registerUserWithDetails(String username, String password, String email, int age) async {
  final response = await http.post(
    Uri.parse('https://example.com/api/register'),
    headers: <String, String>{
      'Content - Type': 'application/json; charset=UTF-8',
    },
    body: jsonEncode(<String, dynamic>{
      'username': username,
      'password': password,
      'email': email,
      'age': age,
    }),
  );

  if (response.statusCode == 201) {
    print('User registered successfully');
  } else {
    throw Exception('Failed to register user');
  }
}

这里的请求体是一个包含更多字段的 JSON 对象，通过 jsonEncode 方法转换为字符串后发送。

（三）处理 POST 请求的响应

在发送 POST 请求后，服务器通常会返回一些信息，比如注册成功后的用户 ID 等。我们可以按照以下方式处理响应：

Future<Map<String, dynamic>> registerUserAndGetResponse(String username, String password) async {
  final response = await http.post(
    Uri.parse('https://example.com/api/register'),
    headers: <String, String>{
      'Content - Type': 'application/json; charset=UTF-8',
    },
    body: jsonEncode(<String, String>{
      'username': username,
      'password': password,
    }),
  );

  if (response.statusCode == 201) {
    return jsonDecode(response.body);
  } else {
    throw Exception('Failed to register user');
  }
}

在这个例子中，函数返回一个 Future<Map<String, dynamic>>，如果注册成功，将返回解析后的响应体数据，这个数据可能包含服务器返回的用户 ID 等信息。

五、发送 PUT 请求

（一）简单 PUT 请求示例

假设我们有一个 API 用于更新用户信息，URL 为 https://example.com/api/users/{id}，其中 {id} 是用户的唯一标识符。以下是发送 PUT 请求更新用户姓名的示例代码：

Future<void> updateUserName(int userId, String newName) async {
  final response = await http.put(
    Uri.parse('https://example.com/api/users/$userId'),
    headers: <String, String>{
      'Content - Type': 'application/json; charset=UTF-8',
    },
    body: jsonEncode(<String, String>{
      'name': newName,
    }),
  );

  if (response.statusCode == 200) {
    print('User name updated successfully');
  } else {
    throw Exception('Failed to update user name');
  }
}

在上述代码中：

http.put 方法用于发送 PUT 请求。
URL 中包含了用户 ID，将其拼接到 URL 中。
请求头设置为 application/json 格式。
请求体是包含新用户名的 JSON 对象。
检查响应状态码，如果为 200，表示更新成功，否则抛出异常。

（二）处理 PUT 请求的复杂更新

如果需要更新多个用户信息字段，比如邮箱和电话号码，代码可以如下编写：

Future<void> updateUserDetails(int userId, String newEmail, String newPhone) async {
  final response = await http.put(
    Uri.parse('https://example.com/api/users/$userId'),
    headers: <String, String>{
      'Content - Type': 'application/json; charset=UTF-8',
    },
    body: jsonEncode(<String, String>{
      'email': newEmail,
      'phone': newPhone,
    }),
  );

  if (response.statusCode == 200) {
    print('User details updated successfully');
  } else {
    throw Exception('Failed to update user details');
  }
}

这里的请求体包含了多个需要更新的字段，发送到服务器进行更新操作。

（三）处理 PUT 请求的响应

类似于 POST 请求，PUT 请求后服务器也可能返回一些信息，比如更新后的用户完整信息。我们可以这样处理响应：

Future<Map<String, dynamic>> updateUserAndGetResponse(int userId, String newName) async {
  final response = await http.put(
    Uri.parse('https://example.com/api/users/$userId'),
    headers: <String, String>{
      'Content - Type': 'application/json; charset=UTF-8',
    },
    body: jsonEncode(<String, String>{
      'name': newName,
    }),
  );

  if (response.statusCode == 200) {
    return jsonDecode(response.body);
  } else {
    throw Exception('Failed to update user name');
  }
}

如果更新成功，将返回解析后的响应体数据，包含更新后的用户信息。

六、发送 DELETE 请求

（一）简单 DELETE 请求示例

假设我们有一个 API 用于删除用户，URL 为 https://example.com/api/users/{id}。以下是发送 DELETE 请求删除用户的示例代码：

Future<void> deleteUser(int userId) async {
  final response = await http.delete(Uri.parse('https://example.com/api/users/$userId'));

  if (response.statusCode == 200) {
    print('User deleted successfully');
  } else {
    throw Exception('Failed to delete user');
  }
}

在这段代码中：

http.delete 方法用于发送 DELETE 请求。
URL 中包含要删除用户的 ID。
检查响应状态码，如果为 200，表示删除成功，否则抛出异常。

（二）处理 DELETE 请求的响应

DELETE 请求的响应通常比较简单，可能只是返回一个状态码表示操作是否成功。但有些服务器可能会返回一些额外信息，比如被删除的用户信息。以下是处理这种情况的示例：

Future<Map<String, dynamic>> deleteUserAndGetResponse(int userId) async {
  final response = await http.delete(Uri.parse('https://example.com/api/users/$userId'));

  if (response.statusCode == 200) {
    return jsonDecode(response.body);
  } else {
    throw Exception('Failed to delete user');
  }
}

如果删除成功且服务器返回了被删除用户的信息，将通过 jsonDecode 方法解析响应体并返回。

（三）错误处理与重试机制

在实际应用中，网络请求可能会因为各种原因失败，比如网络不稳定、服务器故障等。我们可以添加错误处理和重试机制来提高应用的稳定性。以下是一个带有重试机制的 DELETE 请求示例：

Future<void> deleteUserWithRetry(int userId, int maxRetries) async {
  int retries = 0;
  while (retries < maxRetries) {
    try {
      final response = await http.delete(Uri.parse('https://example.com/api/users/$userId'));
      if (response.statusCode == 200) {
        print('User deleted successfully');
        return;
      } else {
        print('Delete failed, status code: ${response.statusCode}');
      }
    } catch (e) {
      print('Delete request failed: $e');
    }
    retries++;
    await Future.delayed(const Duration(seconds: 2));
  }
  throw Exception('Failed to delete user after $maxRetries retries');
}

在这个代码中，deleteUserWithRetry 函数接受用户 ID 和最大重试次数作为参数。使用 while 循环进行重试，每次重试前等待 2 秒。如果成功删除用户（状态码为 200），则返回；如果达到最大重试次数仍未成功，则抛出异常。

七、处理 HTTP 响应状态码

（一）常见状态码及处理

2xx 状态码
- 200 OK：表示请求成功。在 GET 请求中，通常意味着数据成功获取；在 POST、PUT、DELETE 请求中，意味着操作成功执行。例如，在获取博客文章列表的 GET 请求中，如果状态码为 200，我们可以直接解析响应体获取文章数据。
- 201 Created：用于 POST 请求，表明资源已成功创建。如用户注册 API 返回 201，表示用户注册成功，可能还会在响应头的 Location 字段中返回新创建资源（用户）的 URL。
4xx 状态码
- 400 Bad Request：表示客户端请求有语法错误，服务器无法理解。比如在发送 POST 请求注册用户时，如果请求体格式不正确，服务器可能返回 400。此时，我们需要检查请求数据的格式是否符合 API 要求。
- 401 Unauthorized：意味着用户未认证。如果 API 需要身份验证，而请求中未提供有效的认证信息，就会返回此状态码。在这种情况下，应用可能需要提示用户登录或重新获取认证令牌。
- 404 Not Found：表示请求的资源不存在。例如，在发送 GET 请求获取特定 ID 的博客文章时，如果该文章不存在，服务器可能返回 404。我们可以在应用中显示相应的提示信息，告知用户资源未找到。
5xx 状态码
- 500 Internal Server Error：表示服务器内部错误。这通常不是客户端的问题，而是服务器端出现了异常。当遇到这种情况时，我们可以记录错误日志，并提示用户稍后重试。
- 503 Service Unavailable：意味着服务器暂时不可用，可能是因为服务器维护或过载。同样，我们可以记录错误并提示用户稍后重试。

（二）自定义状态码处理逻辑

在 Flutter 应用中，我们可以根据不同的状态码进行自定义的处理。例如，对于 401 Unauthorized 状态码，我们可以自动跳转到登录页面：

Future<List<dynamic>> fetchProtectedData() async {
  final response = await http.get(Uri.parse('https://example.com/api/protectedData'));

  if (response.statusCode == 200) {
    return jsonDecode(response.body);
  } else if (response.statusCode == 401) {
    // 跳转到登录页面
    // 这里假设我们有一个导航到登录页面的方法 navigateToLogin()
    navigateToLogin();
    throw Exception('Unauthorized, please log in');
  } else {
    throw Exception('Failed to load data, status code: ${response.statusCode}');
  }
}

在这个示例中，当状态码为 401 时，应用会跳转到登录页面，并抛出异常提示用户需要登录。

八、优化与安全考虑

（一）请求优化

缓存策略 为了减少不必要的网络请求，我们可以实施缓存策略。例如，对于一些不经常变化的数据（如配置信息、静态文本等），可以在本地缓存。在 Flutter 中，可以使用 shared_preferences 插件来实现简单的本地缓存。以下是一个示例，展示如何缓存 GET 请求的响应数据：

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

Future<List<dynamic>> fetchCachedBlogs() async {
  SharedPreferences prefs = await SharedPreferences.getInstance();
  String? cachedBlogs = prefs.getString('cachedBlogs');
  if (cachedBlogs!= null) {
    return jsonDecode(cachedBlogs);
  }

  final response = await http.get(Uri.parse('https://example.com/api/blogs'));

  if (response.statusCode == 200) {
    List<dynamic> blogs = jsonDecode(response.body);
    prefs.setString('cachedBlogs', jsonEncode(blogs));
    return blogs;
  } else {
    throw Exception('Failed to load blogs');
  }
}

在上述代码中，首先检查本地是否有缓存的博客文章数据。如果有，则直接返回缓存数据；如果没有，则发送网络请求获取数据，并将获取到的数据缓存到本地。

批量请求 当需要从服务器获取多个相关资源时，可以考虑将多个请求合并为一个。例如，如果我们需要获取用户信息和用户的订单列表，而这两个信息可以通过一个 API 端点获取，就应该使用这个端点，而不是分别发送两个请求。这样可以减少网络开销和延迟。

（二）安全考虑

HTTPS 在与服务器进行通信时，一定要使用 HTTPS 协议，以确保数据传输的安全性。HTTPS 会对数据进行加密，防止数据在传输过程中被窃取或篡改。在配置 API 服务器时，应该正确配置 SSL/TLS 证书。在 Flutter 应用中，http 插件默认支持 HTTPS 请求，无需额外配置。
身份验证与授权 对于需要保护的 API 端点，必须进行身份验证和授权。常见的身份验证方式有 Basic 认证、OAuth 等。例如，使用 OAuth 2.0 时，应用需要获取用户的授权令牌，并在每次请求时将令牌包含在请求头中。以下是一个使用令牌进行身份验证的 GET 请求示例：

Future<List<dynamic>> fetchProtectedDataWithToken(String token) async {
  final response = await http.get(
    Uri.parse('https://example.com/api/protectedData'),
    headers: <String, String>{
      'Authorization': 'Bearer $token',
    },
  );

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

在这个例子中，Authorization 头字段包含了 Bearer 类型的令牌，服务器可以根据这个令牌验证请求的合法性。

数据验证与过滤 在发送数据到服务器之前，一定要对数据进行验证，确保数据的格式和内容符合服务器的要求。同时，服务器端也应该对接收到的数据进行严格的过滤，防止 SQL 注入、XSS 攻击等安全漏洞。例如，在用户注册时，对用户名和密码进行长度和格式验证，在服务器端对输入的数据进行转义处理等。

通过以上优化和安全措施，可以提高 Flutter 应用与 RESTful API 交互的效率和安全性，为用户提供更好的体验。