Flutter签名请求生成插件requests_signature_dart的使用

Flutter签名请求生成插件requests_signature_dart的使用

简介

requests_signature_dart 是一个用于在Flutter项目中实现HTTP请求签名和验证的插件。它可以帮助你在发送HTTP请求时，使用HMAC算法生成签名，并将其附加到请求头中，以确保请求的完整性和安全性。该插件特别适用于与后端系统（如.NET）进行通信时，确保请求的合法性。

安装

首先，你需要在项目的 pubspec.yaml 文件中添加 requests_signature_dart 依赖：

dependencies:
  requests_signature_dart: ^1.0.0

然后运行以下命令来安装依赖：

flutter pub get

使用示例

下面是一个完整的示例，展示了如何在Flutter项目中使用 requests_signature_dart 插件来为HTTP请求生成签名。

import 'package:requests_signature_dart/requests_signature_dart.dart';
import 'package:requests_signature_dart/src/client/requests_signature_options.dart';
import 'package:dio/dio.dart';

void main() {
  // 实例化Dio客户端
  final dio = Dio();

  // 定义签名选项
  final signatureOptions = RequestsSignatureOptions(
    clientId: 'your_client_id', // 你的唯一客户端ID
    clientSecret: 'your_client_secret', // 你的客户端密钥
    headerName: 'X-Request-Signature', // 签名头的名称
    signaturePattern: '{ClientId}:{Nonce}:{Timestamp}:{SignatureBody}', // 签名头的格式
    clockSkew: Duration(seconds: 30), // 时间偏移量（30秒）
    disableAutoRetryOnClockSkew: false, // 是否禁用时钟偏移自动重试
  );

  // 实例化拦截器
  final interceptor = RequestsSignatureInterceptor(
    signatureOptions,
    dio,
  );

  // 将拦截器添加到Dio客户端
  dio.interceptors.add(interceptor);

  // 发送带签名的GET请求
  dio.get('https://example.com/api/v1/data').then((response) {
    print('Response: ${response.data}');
  }).catchError((error) {
    print('Error: $error');
  });
}

签名头的构造

默认情况下，签名头的格式如下：

{ClientId}:{Nonce}:{Timestamp}:{SignatureBody}

其中：

• {ClientId}：客户端ID，由你配置。
• {Nonce}：每次请求生成的随机值（UUID/GUID）。
• {Timestamp}：请求发送时的时间戳，使用Unix Epoch时间（秒）。
• {SignatureBody}：Base-64编码的HMAC SHA256签名，签名的内容包括：
  • 随机数（Nonce）
  • 时间戳（Timestamp）
  • 请求方法（大写）
  • 请求协议（如 https）
  • 请求主机（如 example.org）
  • 请求路径（如 /api/v1/users）
  • 请求查询字符串（如 ?q=search）
  • 请求体（如果有的话）

自动重试机制

当客户端的时钟与服务器不同步时，插件会自动检测并尝试重新发送请求。具体来说，当客户端收到401或403状态码并且响应中包含 Date 头时，插件会比较服务器时间和客户端时间。如果时间差超过配置的 clockSkew，插件会调整时间并重新发送请求。你可以通过设置 disableAutoRetryOnClockSkew 为 true 来禁用此功能。

配置选项

• clockSkew：时间偏移量，默认为5分钟。表示时间戳在当前时间前后多少时间内仍然有效。
• headerName：签名头的名称，默认为 X-RequestSignature。
• signaturePattern：签名头的格式，默认为 {ClientId}:{Nonce}:{Timestamp}:{SignatureBody}。
• disableAutoRetryOnClockSkew：是否禁用时钟偏移自动重试，默认为 false。

进一步定制

你可以通过实现以下接口来自定义签名生成和验证的行为：

• ISignatureBodySourceBuilder：用于构建签名计算的源数据。
• ISignatureBodySigner：用于创建签名值。
• IRequestsSignatureValidationService：用于执行签名验证。

此外，你还可以通过自定义哈希算法来生成签名。例如，使用SHA256算法：

import 'package:requests_signature_dart/requests_signature_dart.dart';
import 'package:dio/dio.dart';
import 'package:cryptography/cryptography.dart';

void main() {
  final dio = Dio();

  // 自定义签名生成器
  var customSignatureBodySigner = HashAlgorithmSignatureBodySigner(hmacAlgorithm: DartHmac.sha256());

  // 实例化拦截器
  final interceptor = RequestsSignatureInterceptor(
    signatureOptions,
    dio,
    signatureBodySigner: customSignatureBodySigner,
  );

  // 将拦截器添加到Dio客户端
  dio.interceptors.add(interceptor);
}