Flutter RESTful API：Retrofit 配置指南

RESTful API（Representational State Transfer 表述性状态转移）是现代应用开发中常用的接口设计风格，而 Retrofit 是一个类型安全的 HTTP 客户端，能帮助开发者更高效地处理 API 请求。本文将详细介绍在 Flutter 项目中配置 Retrofit 的完整流程，包括依赖添加、接口定义、数据模型创建和实际请求示例。

准备工作

在开始配置 Retrofit 前，需要确保项目中已添加必要的依赖。在 pubspec.yaml 文件中添加以下内容：

dependencies:
  retrofit: ^4.0.0
  dio: ^5.0.0
  json_annotation: ^4.8.1

dev_dependencies:
  retrofit_generator: ^7.0.0
  build_runner: ^2.4.4
  json_serializable: ^6.7.0

创建数据模型

首先需要创建与 API 响应对应的 Dart 数据模型。例如，假设我们有一个获取用户信息的 API，返回如下 JSON 数据：

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}

我们可以创建一个 User 模型类，文件路径为 lib/models/user.dart：

import 'package:json_annotation/json_annotation.dart';

part 'user.g.dart';

@JsonSerializable()
class User {
  final int id;
  final String name;
  final String email;

  User({required this.id, required this.name, required this.email});

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
  Map<String, dynamic> toJson() => _$UserToJson(this);
}

定义 API 接口

接下来，创建一个 API 接口文件，路径为 lib/api/user_api.dart，使用 Retrofit 注解定义 API 方法：

import 'package:retrofit/retrofit.dart';
import 'package:dio/dio.dart';
import '../models/user.dart';

part 'user_api.g.dart';

@RestApi(baseUrl: "https://api.example.com/")
abstract class UserApi {
  factory UserApi(Dio dio, {String baseUrl}) = _UserApi;

  @GET("users/{id}")
  Future<User> getUser(@Path("id") int id);

  @POST("users")
  Future<User> createUser(@Body() User user);
}

生成代码

在终端中执行以下命令，生成 Retrofit 和 JSON 序列化相关的代码：

dart run build_runner build

执行成功后，会在接口文件和模型文件同目录下生成 .g.dart 文件，例如 user_api.g.dart 和 user.g.dart。

使用 Retrofit 发起请求

在需要调用 API 的地方，初始化 Dio 和 UserApi，然后发起请求。例如，在 lib/main.dart 中：

import 'package:dio/dio.dart';
import 'api/user_api.dart';
import 'models/user.dart';

void main() async {
  final dio = Dio();
  final api = UserApi(dio);

  try {
    final user = await api.getUser(1);
    print("User: ${user.name}, Email: ${user.email}");
  } catch (e) {
    print("Error: $e");
  }
}

高级配置

拦截器

可以通过 Dio 添加拦截器，处理请求头、日志等：

final dio = Dio()
  ..interceptors.add(LogInterceptor(responseBody: true))
  ..options.headers["Content-Type"] = "application/json";

错误处理

使用 try-catch 捕获 API 请求可能出现的错误：

try {
  final user = await api.getUser(1);
  // 处理成功响应
} on DioException catch (e) {
  // 处理 Dio 异常
  print("Dio Error: ${e.message}");
} catch (e) {
  // 处理其他异常
  print("Error: $e");
}

总结

通过以上步骤，我们完成了 Retrofit 在 Flutter 项目中的配置，实现了类型安全的 API 调用。使用 Retrofit 可以显著减少手动处理 HTTP 请求的 boilerplate 代码，提高开发效率。更多高级用法可以参考 Retrofit 和 Dio 的官方文档。