faraday 3.0.0

g_faraday command-line application.

Faraday_CLI

faraday_cli(以下简称cli)是配合g_faraday进行模块化混合应用开发的命令行程序,帮助我们减少部分重复性工作让开发更高效

Features

• Generate Common&Entry interface
• Package iOS&Android framework/aar

Why

桥接方法

进行混合应用开发通常会有以下需求。有一个功能在ios/android两端已经实现，在flutter层需要调用，这时候就需要在flutter层来定义接口，然后在两端分别实现。下面我们来看一段代码示例

class EncryptUtils {

    // 加密
    static Future<String> encrypt(String content, Map<String, dynamic> options) {
        return FaradayCommon.invokeMethod('SomeFeature#encrypt', {'content': content, 'options': options});
    }

    // 解密
    static Future<String> decrypt(String encryptedContent, Map<String, dynamic> options) {
        return FaradayCommon.invokeMethod('SomeFeature#decrypt', {'encryptedContent': encryptedContent, 'options': options});
    }
}

以上，我们在flutter中定义了加密和解密2个方法，接下来我们需要分别在ios/android的FaradayCommon中来实现代码如下(仅swift，kotlin类似)

func handle(_ name: String, _ arguments: Any?, _ completion: @escaping (_ result: Any?) -> Void) -> Void {
    if (name == "SomeFeature#encrypt") {
        guard let content = args?["content"] as? String else {
                fatalError("Invalid argument: content")
        }
        let options = args?["options"] as? [String, Any]

        // 使用以上参数来调用原生加密方法
    } else if (name = "SomeFeature#decrypt") {
        guard let encryptedContent = args?["encryptedContent"] as? String else {
                fatalError("Invalid argument: encryptedContent")
        }
        let options = args?["options"] as? [String, Any]

        // 使用以上参数来调用原生解密方法
    }
    ...
}

仔细看上述代码实现就会发现有很多重复代码片段，因此cli提供了对应的生成工具来实现代码生。(具体命令请见下述示例)

路由注册

flutter中一个典型的路由注册如下

// flutter
Map<String, RouteFactory> routes = {
    'first_page': (RouteSettings settings) => CupertinoPageRoute(
        builder: (context) => FirstPage(0), settings: settings),
    'home': (RouteSettings settings) => CupertinoPageRoute(
        builder: (context) => HomePage(settings.arguments), settings: settings),
    'flutter_tab_2': (RouteSettings settings) => CupertinoPageRoute(
        builder: (context) => HomePage(settings.arguments), settings: settings),
    'flutter_tab_1': (RouteSettings settings) => CupertinoPageRoute(
        builder: (context) => EmbeddingPage(0), settings: settings),
  };

// swift

enum FaradayRoute {
    // ---> enum
    // ---> enum MainTabPage
    case first_page
    case home(Int id)
    case flutter_tab_2(String name)
    case flutter_tab_1
}

上面的例子可以看出我们在3端需要定义很多常量字符串,如果任由开发者手动输入，ide没有任何提醒，那会非常容易出错。(具体命令下述会有相关示例)

打包集成

ios

官方集成方案一共有3种，其中2中需要ios开发者本地由flutter开发环境，还有一种需要获取被人打包好的framework。这种开发体验对一个稍具规模的ios开发团队来说并不是特别友好。我们将采用 pod 私有库的方式在团队成员之间共享打包产物。同时对CI/CD流程提供支持

android

android 官方方案对比ios来说，使用aar方式集成非常友好，只需要将编译产物放到大家都可以访问到的地址即可

How

前置准备条件

• 安装faraday cli

pub global active faraday

# print version
faraday version

• 准备文件服务器

为了无感集成flutter模块至现有的ios和android工程，需要一个所有团队成员均可访问的文件服务器(支持文件上传下载)来存储编译产物(ios为cocoapods framework，android 为maven仓库)

如果暂时没有文件服务器可以下载 simple-http-server.py启动一个用于测试的文件服务器。需要安装python3

• cocoapods private spec

ios选择使用cocoapods来集成，为了让native开的同学无感我们需要创建私有repo。 具体步骤参见 Private Pods

配置文件

• ios native 项目中添加2个空文件

新建2个空文件用来生成 桥接方法和路由 的模版代码，建议文件名 FaradayCommon.swift、FaradayRoute.swift

• android native 项目中添加2个空文件

建议文件名 FaradayCommon.kt、FaradayRoute.kt

• flutter module 项目根目录下创建.faraday.json文件

cli主要作用就是为ios和android生成模版代码，所以在一切工作开始之前我们需先告诉cli相应文件的具体位置。

{
  "ios-common": "/path/to/FaradayCommon.swift", // 上面2步新建的文件路径
  "ios-route": "/path/to/FaradayRoute.swift",
  "android-common": "/path/to/FaradayCommon.kt",
  "android-route": "/path/to/FaradayRoute.kt"
}

版本控制工具请忽略此文件 每个开发者的 .faraday.json 文件都需要根据自己的需要配置添加

• pubspec.yaml

修改flutter module项目下的pubspec.yaml文件， 添加以下配置

...

version: 0.2.1-dev.0

####################################################
faraday:
  static_file_server_address: "http://localhost:8000" # 前置条件中的静态文件服务器
  pod_repo_name: "faraday" # 前置条件中的 private pod spec name
####################################################

environment:
  sdk: ">=2.9.0 <3.0.0"

...

初始化

cd [your_flutter_module]

faraday init

初始化完成以后查看lib/src/debug目录

同时在lib/src/目录下会生成routes.dart文件，用来定义flutter侧的路由定义。如果一切正常说明初始化正常

集成

初始化完成以后，我们分别在3端来集成faraday

flutter

import 'src/debug/debug.dart';
import 'src/routes.dart';

....

// debugMessage 每次打包都会更新称最新版本号，可以添加一个banner显示
debugPrint(debugMessage);

// 可以使用 CupertinoApp、MaterialApp、WidgetsApp 或者 Navigator 均可
CupertinoApp(onGenerateRoute: (_) => faraday.wrapper(routeFactory));

iOS端产物说明

• protocol FaradayCommonHandler { }

自动根据flutter端的common方法定义来生成接口定义，我们需要实现他，一般可以直接用 AppDelegate 实现

extension AppDelegate: FaradayCommonHandler {
...
}

• enum FaradayRoute { }

根据flutter端的路由信息来生成对应的枚举 使用方式 大概如下

let vc = FaradayRoute.demoPage.viewController()
navigationController?.push(viewController: vc)
...
}

android和iOS类似这里就不在赘述

添加一个桥接方法

g_faraday提供了2个注解@common和@ignore。当一个类被@common注解时，这个类中所包含的所有符合条件的方法都会在native侧生成相应的接口类

何为符合条件的方法 如果一个方法为 静态方法而且参数和返回值都可以序列化成json，那么就是一个符合条件的方法 如果一个符合条件的方法，不需要生成native接口，那么只需要用@ignore注解此方法即可

执行下面的命令，应该可以看到对应的文件生成了相应的方法

cd [your_flutter_module]

faraday generate

添加一个路由

当一个flutter页面需要从native打开是需要以下两步来操作

• 用@entry注解你当前页面的class

• 添加faraday静态方法

// 声明路由

@entry
class DemoPage extends StatefulWidget {

    static Route faraday(int id) => CupertinoPageRoute(
        builder: (ctx) => DemoPage(status),
      );

    ....
}

执行

faraday generate

在对应的route文件和routes.dart文件中，会根据faraday方法的签名，自动生成对应路由

如果有路由只需要生成flutter侧，不需要从native打开，那么可以考虑使用@flutterEntry进行注解

打包发布

faraday对flutter build命令进行封装，可以用以下命令快速打包发布

faraday tag --no-release

FAQ

1. 如何选择faraday版本？

根据Module项目是否支持null-safety分为两种情况

1. 不支持null-safety, 请使用版本1.2.7, 后续版本将不再维护非null-safety的项目

2. 支持null-safety, 请使用版本2.0.7及以上版本，需要dart version 2.15.1及以上版本，该版本dart对应flutter版本为2.8.1

LICENSE

faraday_cli is released under the MIT license. See LICENSE for details.