Flutter后端通信插件endpoint_core的使用

Flutter后端通信插件endpoint_core的使用

Endpoint Core介绍

Endpoint Core 是一个强大的且灵活的 Dart 包，用于在 Flutter 应用程序中构建和管理 API 端点。它提供了一种结构化的方式来定义、认证并与 RESTful API 交互，利用流行的 Dio HTTP 客户端。

特性

• 易用的 API 端点定义
• 支持自定义数据模型
• 灵活的认证选项（Bearer Token, 自定义头部）
• 内置请求缓存，可自定义缓存选项
• 自动错误处理和解析
• 可定制的拦截器以进行日志记录、连接检查等
• Dio 扩展方法，用于常见任务
• 完全可测试的架构

安装

将 endpoint_core 添加到您的 pubspec.yaml 文件中：

dependencies:
  endpoint_core: ^1.0.0

然后运行：

flutter pub get

使用示例

定义自定义模型

首先，定义我们将用于 API 的的自定义模型：

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) {
    return User(
      id: json['id'],
      name: json['name'],
      email: json['email'],
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'name': name,
      'email': email,
    };
  }
}

定义包含自定义模型和缓存端点的 API

接下来，定义一个使用我们自定义 User 模型并且包含缓存端点的 API：

import 'package:endpoint_core/endpoint_core.dart';

class UserApi extends Endpoint {
  UserApi({
    required super.method,
    required super.url,
    super.validStatusCode,
    super.defaultAuthOptions,
    super.cacheOptions,
  });

  @override
  String get domainUrl => "https://api.example.com";

  static Map<String, ApiEndpoint> endpoints() =&gt; {
    "getUsers": UserApi(
      method: "GET",
      url: "/users",
      validStatusCode: 200,
      defaultAuthOptions: EndpointAuthOptions.bearerToken(
        token: "your-token-here",
        unauthorizedStatusCodes: [401, 403],
        onUnauthorizedCallback: (_) {
          // 处理未授权访问
        },
      ),
      cacheOptions: CacheOptions(cacheDuration: Duration(minutes: 5)),
    ),
    "getUserById": UserApi(
      method: "GET",
      url: "/users/{id}",
      validStatusCode: 200,
      cacheOptions: CacheOptions(cacheDuration: Duration(hours: 1)),
    ),
    "createUser": UserApi(
      method: "POST",
      url: "/users",
      validStatusCode: 201,
    ),
    "updateUser": UserApi(
      method: "PUT",
      url: "/users/{id}",
      validStatusCode: 200,
    ),
  };
}

使用 API 与自定义模型和 缓存

以下是如何使用 API 并利用自定义模型和缓存的例子：

void main() async {
  final api = UserApi.endpoints();
  
  // 获取所有用户（缓存 5 分钟）
  final users = await api["getUsers"]!.call<List<User>>(
    map: (data) => (data as List).map((json) => User.fromJson(json)).toList(),
  );
  print("All users: $users");
  
  // 根据 ID 获取特定用户（缓存 1 小时）
  final user = await api["getUserById"]!.call<User>(
    pathParameters: {"id": "123"},
    map: (data) => User.fromJson(data),
  );
  print("User with ID 123: $user");
  
  // 创建新用户（不缓存)
  final newUser = await api["createUser"]!.call<User>(
    data: User(id: 0, name: "John Doe", email: "john@example.com").toJson(),
    map: (data) => User.fromJson(data),
  );
  print("Newly created user: $newUser");
  
  // 更新用户（不缓存）
  final updatedUser = await api["updateUser"]!.call<User>(
    pathParameters: {"id": "123"},
    data: {"name": "Jane Doe"},
    map: (data) => User.fromJson(data),
  );
  print("Updated user: $updatedUser");
}

工作与缓存端点

当处理缓存端点时，请注意以下几点：

1. CacheOptions 在端点定义中确定响应将在多长时间内被缓存。
2. 缓存的响应会在缓存持续时间内自动返回给后续调用。
3. 可以通过设置 ignoreCache 为 true 强制刷新请求：

final freshUserData = await api["getUserById"]!.call<User>(
  pathParameters: {"id": "123"},
  map: (data) => User.fromJson(data),
  ignoreCache: true, // 这将忽略任何缓存的数据 并做出新鲜请求
);

自定义认证

可以使用自定义认证选项：

final customAuthOptions = CustomHeaderTokenAuthOptions(
  headerName: "X-API-Key",
  token: "your-api-key-here",
  unauthorizedStatusCodes: [401],
  onUnauthorizedCallback: (_) {
    // 处理未授权访问
  },
);

final result = await api["someEndpoint"]!.call(
  authOptions: customAuthOptions,
  // 其他参数...
);

使用拦截器

包中提供了几个内置拦截器：

• AuthInterceptor: 处理认证
• CacheInterceptor: 管理请求缓存
• ConnectionChecker: 检查网络连接
• RequestLogger: 日志请求和 响应详情

可以在定义 API 时添加自定义拦截器：

class MyApi extends Endpoint {
  MyApi({
    // ... 其他参数
  }) : super(
    interceptorsors: [MyCustomInterceptor()],
  );

  // ... 其余类
}

自定义缓存行为

如果需要更多缓存行为控制，可以实现自定义 CacheInterceptor：

class CustomCacheInterceptor extends CacheInterceptor {
  CustomCacheInterceptor({required super.validStatusCode});

  @override
  Future<void> onResponse(Response response, ResponseInterceptorHandler handler) async {
    // 自定义缓存逻辑在这里
    // 例如，你可能想要基于自定义头部缓存：
    final customCacheDuration = response.headers.value('X-Cache-Duration');
    if (customCacheDuration != null) {
      final duration = Duration(seconds: int.parse(customCacheDuration));
      // 实现自定义缓存逻辑，使用这个持续时间
    }

    super.onResponse(response, handler);
  }
}

// 然后在定义 API 时使用这个自定义拦截器：
class UserApi extends Endpoint {
  UserApi({
    // ... 其他参数
  }) : super(
    interceptorsors: [CustomCacheInterceptor(validStatusCode: 200)],
  );

  // ... 其余类
}

Dio 扩展

包提供了有用的 Dio 扩展：

final dio = Dio();

// 向所有请求添加授权头
dio.addAuthorizationInterceptor('your-token-here');

// 向所有请求添加自定义头
dio.addCustomHeader('X-Custom-Header', 'custom-value');

// 检查响应是否成功
if (response.isSuccessful) {
  // 处理成功响应
}

// 获取友好的错误消息
print(dioError.friendlyMessage);