Flutter深度链接远程过程调用插件deeplink_rpc的使用

Flutter深度链接远程过程调用插件deeplink_rpc的使用

简介

deeplink_rpc 是一个基于Dart编写的通过深度链接进行远程过程调用（RPC）的库。它专门用于Flutter移动应用（iOS/Android）。

协议

深度链接编码器

深度链接消息会被附加到深度链接URI中。因此，可用的格式有一些限制。

为了使其正常工作，消息被编码为：

                     +--------------+   +------+   +--------+
method_payload :     | Json Message |-> | gzip |-> | base64 |
                     +--------------+   +------+   +--------+

Deeplink Url : `<scheme>://<host>/<method_name>/<method_payload>`

示例：

                     +--------------------------+      +----------------------------------------------------------------+
method_payload :     | { "param1" : "a_value" } |----> | "H4sIAAAAAAAAA6tWUCpILErMNVRSsFJQSowvS8wpTVVSqAUAhIgKchgAAAA=" |
                     +--------------------------+      +----------------------------------------------------------------+

Deeplink Url : `scheme://host/a_method/H4sIAAAAAAAAA6tWUCpILErMNVRSsFJQSowvS8wpTVVSqAUAhIgKchgAAAA=`

请求格式化

请求的有效载荷被封装在 <a href="https://www.jsonrpc.org/specification" rel="ugc">JSON-RPC 2.0</a> 消息中。

{
  "id": Number,                     // 唯一的客户端生成整数，用于标识请求
  "replyUrl": String,               // 发送调用结果的深度链接URL。这应该是一个由DApp处理的深度链接URL。
  "params": {
    "origin": {
      "name": String,               // 可读标识符，表示DApp
      "url": String | undefined,    // DApp的URL
      "logo": Base64 | undefined,   // DApp的Logo
    },
    "version": 2,                   // DApp API版本
    "payload": Object,              // 方法参数
  }
}

成功响应格式化

{
  "id": Number,                     // 请求标识符
  "result":  Object,                // 结果有效载荷
}

失败响应格式化

{
  "id": Number,                     // 请求标识符
  "failure": {
    "code": Number,                 // 错误代码
    "message": String | undefined,  // 错误描述
    "data": Object | undefined,     // 错误数据
  },
}

使用方法

服务器 - 监听传入的请求

/// 1. 启用您的应用程序的深度链接（https://docs.flutter.dev/development/ui/navigation/deep-linking）

/// 2. 声明深度链接-RPC接收器
/// 当接收到RPC调用 <scheme>://a_rpc_command/<payload> 时，有效载荷被解码并传输给 `handle` 方法。
final _deeplinkRpcReceiver = DeeplinkRpcRequestReceiver()
    ..registerHandler(
      DeeplinkRpcRequestHandler(
        route: const DeeplinkRpcRoute('a_rpc_command'),
        handle: (request) {
            log('Command received');
        }
      ),
    );


class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'DeeplinkRPC Demo',
      home: const SendForm(),
      onGenerateRoute: (settings) {
        /// 3. 监听传入的深度链接请求
        if (_deeplinkRpcReceiver.handleRoute(settings.name)) return;

        // ... 进行其他路由生成操作
        return null;
      },
    );
  }
}

客户端 - 发送请求并监听响应

/// 1. 启用您的应用程序的深度链接（https://docs.flutter.dev/development/ui/navigation/deep-linking）
/// 这对于接收响应是必要的。

/// 2. 声明深度链接-RPC客户端
/// 当接收到RPC调用 <scheme>://a_rpc_command/<payload> 时，有效载荷被解码并传输给 `handle` 方法。
final _deeplinkRpcClient = DeeplinkRpcClient();

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'DeeplinkRPC Demo',
      onGenerateRoute: (settings) {
        /// 3. 监听传入的深度链接请求
        if (_deeplinkRpcClient.handleRoute(settings.name)) return;

        // ... 进行其他路由生成操作
        return null;
      },
      home: Scaffold(
        floatingActionButton: FloatingActionButton(
          child: const Icon(Icons.send),
          onPressed: () async {
            final response = await _deeplinkRpcClient.send(
              timeout: const Duration(seconds: 5),
              request: DeeplinkRpcRequest(
                requestUrl: 'serverapp://server.app/request_endpoint',
                replyUrl: 'clientapp://client.app/reply_endpoint',
                params: {
                  'param1': 'value1',
                  'param2': 'value2',
                },
              ),
            );

            response.map(
              failure: (failure) {
                log(
                  'RPC request failed',
                  error: failure,
                );
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(
                      content: Text(failure.message ?? "An error occured")),
                );
              },
              success: (result) {
                log(
                  'RPC request succeed : ${json.encode(result)}',
                );
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text(json.encode(result))),
                );
              },
            );
          },
        ),
        body: const SafeArea(
          child: Padding(
            padding: EdgeInsets.all(8.0),
            child: Center(
              child: Text('Client example'),
            ),
          ),
        ),
      ),
    );
  }
}

示例代码

以下是完整的示例代码，展示了如何使用 deeplink_rpc 插件。

/// SPDX-License-Identifier: AGPL-3.0-or-later
import 'dart:convert';

import 'package:deeplink_rpc/deeplink_rpc.dart';
import 'package:flutter/material.dart';
import 'package:logging/logging.dart';

void main() {
  runApp(MyApp());
}

final _deeplinkRpcClient = DeeplinkRpcClient();

class MyApp extends StatelessWidget {
  MyApp({super.key});

  final _messengerKey = GlobalKey<ScaffoldMessengerState>();
  final _logger = Logger('Example app');

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      scaffoldMessengerKey: _messengerKey,
      title: 'DeeplinkRPC Demo',
      onGenerateRoute: (settings) {
        if (_deeplinkRpcClient.handleRoute(settings.name)) return;
        return null;
      },
      home: Scaffold(
        floatingActionButton: FloatingActionButton(
          child: const Icon(Icons.send),
          onPressed: () async {
            final response = await _deeplinkRpcClient.send(
              timeout: const Duration(seconds: 5),
              request: DeeplinkRpcRequest(
                requestUrl: 'serverapp://server.app/request_endpoint',
                replyUrl: 'clientapp://client.app/reply_endpoint',
                params: {
                  'param1': 'value1',
                  'param2': 'value2',
                },
              ),
            );

            response.map(
              failure: (failure) {
                _logger.severe(
                  'RPC request failed',
                  failure,
                );
                _messengerKey.currentState?.showSnackBar(
                  SnackBar(
                    content: Text(failure.message ?? 'An error occured'),
                  ),
                );
              },
              success: (result) {
                _logger.info(
                  'RPC request succeed : ${json.encode(result)}',
                );
                _messengerKey.currentState?.showSnackBar(
                  SnackBar(content: Text(json.encode(result))),
                );
              },
            );
          },
        ),
        body: const SafeArea(
          child: Padding(
            padding: EdgeInsets.all(8),
            child: Center(
              child: Text('Client example'),
            ),
          ),
        ),
      ),
    );
  }
}