Flutter hybrid project highway Pigeon

Earlier, we mentioned that Flutter uses BasicMessageChannel for native communication, which completely implements interface decoupling and communicates through protocols. However, one problem is that multiple terminals need to maintain a set of protocol specifications, which will inevitably lead to communication costs during collaborative development. Therefore, Flutter officially provides a solution such as Pigeon.

Pigeon exists to solve the development cost of multi-terminal communication. Its core principle is to generate multi-terminal codes through a set of protocols, so that multiple terminals only need to maintain a set of protocols, and other codes can be automatically generated by Pigeon, thus ensuring the unification of multiple terminals.

The official documentation is as follows.

https://pub.flutter-io.cn/packages/pigeon/install

Introduction

First, you need to introduce Pigeon in dev_dependencies:

 dev_dependencies :
 pigeon : ^ 1.0.15

Next, create a .dart file in the same directory as the Flutter lib folder, such as schema.dart, which is the communication protocol file.

For example, we need to unify an entity across multiple terminals: Book, as shown below.

 import 'package:pigeon/pigeon.dart' ;

 class Book {
 String ? title ;
 String ? author ;
 }

 @HostApi ( )
 abstract class NativeBookApi {
 List < Book? > getNativeBookSearch ( String keyword ) ;

 void doMethodCall ( ) ;
 }

This is our protocol file, where @HostApi represents the method of calling the native side from the Flutter side. If it is @FlutterApi, it represents the method of calling Flutter from the native side.

generate

Execute the following instructions to let Pigeon generate the corresponding code according to the protocol. The following configurations need to specify some file directories and package names and other information. We can save it to a sh file, so after updating, we only need to execute this sh file.

 flutter pub run pigeon \
 --input schema.dart \
 --dart_out lib/pigeon.dart \
 --objc_header_out ios/Runner/pigeon.h \
 --objc_source_out ios/Runner/pigeon.m \
 --java_out ./android/app/src/main/java/dev/flutter/pigeon/Pigeon.java \
 --java_package "dev.flutter.pigeon"

The important thing here is to import the schema.dart file as the protocol and then specify the output path of the Dart, iOS, and Android code.

Under normal circumstances, the generated code can be used directly.

The code generated by Pigeon is Java and OC, mainly to be compatible with more projects. You can convert it to Kotlin or Swift.

Using the above example, let's see how to perform cross-end communication based on the code generated by Pigeon.

First, in the Android code, an interface with the same protocol name, NativeBookApi, will be generated, corresponding to the protocol name marked by the HostApi annotation above. In the inherited class of FlutterActivity, create an implementation class of this interface.

 private class NativeBookApiImp ( val context : Context ) : Api .NativeBookApi {

 override fun getNativeBookSearch ( keyword : String? ) : MutableList < Api .Book > {
 val book = Api .Book ( ) .apply {
 title = "android"
 author = "xys$keyword"
 }
 return Collections.singletonList ( book )
 }

 override fun doMethodCall ( ) {
 context .startActivity ( Intent ( context , FlutterMainActivity :: class .java ) )
 }
 }

By the way, the engine is created using FlutterEngineGroup. If it is created in other ways, you can get the engine object in different ways.

 class SingleFlutterActivity : FlutterActivity ( ) {

 val engine : FlutterEngine by lazy {
 val app = activity .applicationContext as QDApplication
 val dartEntrypoint =
 DartExecutor .DartEntrypoint (
 FlutterInjector .instance ( ) .flutterLoader ( ) .findAppBundlePath ( ) , "main"
 )
 app .engines .createAndRunEngine ( activity , dartEntrypoint )
 }

 override fun configureFlutterEngine ( flutterEngine : FlutterEngine ) {
 super .configureFlutterEngine ( flutterEngine )
 Api .NativeBookApi .setup ( flutterEngine .dartExecutor , NativeBookApiImp ( this ) )
 }

 override fun provideFlutterEngine ( context : Context ) : FlutterEngine ? {
 return engine
 }

 override fun onDestroy ( ) {
 super .onDestroy ( )
 engine.destroy ( )
 }
 }

The core method to initialize Pigeon is the setup method in NativeBookApi, which passes in the engine and protocol implementation.

Next, let's see how to call this method in Flutter. Before Pigeon, we used Channel to create a String type protocol name to communicate. Now with Pigeon, these error-prone Strings are hidden and all become normal method calls.

In Flutter, Pigeon automatically creates the NativeBookApi class instead of the interface in Android, and generates the methods defined in the protocols such as getNativeBookSearch and doMethodCall in the class.

 List < Book? > list = await api .getNativeBookSearch ( "xxx" ) ;
 setState ( ( ) => _counter = "${list[0]?.title} ${list[0]?.author}" ) ;

It is very convenient to call it through await. It can be seen that after encapsulation through Pigeon, cross-end communication is completely encapsulated by the protocol, and various String processing is also hidden, which further reduces the possibility of manual errors.

optimization

In actual use, Flutter calls native methods to obtain data, and the native side processes the data and returns it to Flutter. Therefore, in the Android code generated by Pigeon, the implementation of the protocol function is a method with a return value, as shown below.

 override fun getNativeBookSearch ( keyword : String? ) : MutableList < Api .Book > {
 val book = Api .Book ( ) .apply {
 title = "android"
 author = "xys$keyword"
 }
 return Collections.singletonList ( book )
 }

There is nothing wrong with this method itself. If it is a network request, you can use OKHttp's success and fail callbacks to handle it, but what if you want to use a coroutine?

Since coroutines break callbacks, they cannot be used in functions generated by Pigeon. At this time, you need to modify the protocol and add an @async annotation to the method to mark it as an asynchronous function.

We modify the protocol and regenerate the code.

 @HostApi ( )
 abstract class NativeBookApi {
 @async
 List < Book? > getNativeBookSearch ( String keyword ) ;

 void doMethodCall ( ) ;
 }

At this time, you will find that in the implementation function of NativeBookApi, the function with return value has become void, and a result variable is provided to handle the transfer of return value.

 override fun getNativeBookSearch ( keyword : String? , result : Api .Result < MutableList < Api .Book >> ? )

This makes it very simple to use. Just plug the return value back through result.

With this method, we can use Pigeon and coroutines together, and the development experience will be instantly improved.

 private class NativeBookApiImp ( val context : Context , val lifecycleScope : LifecycleCoroutineScope ) : Api .NativeBookApi {
 override fun getNativeBookSearch ( keyword : String? , result : Api .Result < MutableList < Api .Book >> ? ) {
 lifecycleScope .launch {
 try {
 val data = RetrofitClient .getCommonApi ( ) .getXXXXList ( ) .data
 val book = Api .Book ( ) .apply {
 title = data .tagList .toString ( )
 author = "xys$keyword"
 }
 result? .success ( Collections .singletonList ( book ) )
 } catch ( e : Exception ) {
 e .printStackTrace ( )
 }
 }
 }

 override fun doMethodCall ( ) {
 context .startActivity ( Intent ( context , FlutterMainActivity :: class .java ) )
 }
 }

Coroutine+Pigeon YYDS.

Here we only introduce the scenario of Flutter calling Android. In fact, Android calling Flutter just changes the direction. The codes are similar, so I won’t go into details here. What about iOS? - I wrote Flutter, what does it have to do with iOS?

Disassembly

Now that we know how to use Pigeon, let’s take a look at what this “pigeon” actually does.

From a macro perspective, whether it is the Dart side or the Android side, three types of things are generated.

• Data entity class, such as the Book class above
• StandardMessageCodec, which is the transfer encoding class of BasicMessageChannel
• Protocol interface\class, such as NativeBookApi above

In Dart, the data entity will automatically generate encoding and decoding codes for you, so that the data you obtain is no longer the Object type in the Channel, but the type defined in the protocol, which greatly facilitates developers.

 class Book {
 String ? title ;
 String ? author ;

 Object encode ( ) {
 final Map < Object? , Object? > pigeonMap = < Object? , Object? > { } ;
 pigeonMap [ 'title' ] = title ;
 pigeonMap [ 'author' ] = author ;
 return pigeonMap ;
 }

 static Book decode ( Object message ) {
 final Map < Object? , Object? > pigeonMap = message as Map < Object? , Object? > ;
 return Book ( )
 ..title = pigeonMap [ 'title' ] as String ?
 ..author = pigeonMap [ 'author' ] as String ?;
 }
 }

In Android, similar operations are performed, which can be understood as translation into Java.

Below is Codec. StandardMessageCodec is the standard codec of BasicMessageChannel. The transmitted data needs to implement its writeValue and readValueOfType methods.

 class _NativeBookApiCodec extends StandardMessageCodec {
 const _NativeBookApiCodec ( ) ;
 @override
 void writeValue ( WriteBuffer buffer , Object ? value ) {
 if ( value is Book ) {
 buffer .putUint8 ( 128 ) ;
 writeValue ( buffer , value .encode ( ) ) ;
 } else {
 super .writeValue ( buffer , value ) ;
 }
 }
 @override
 Object ? readValueOfType ( int type , ReadBuffer buffer ) {
 switch ( type ) {
 case 128 :
 return Book .decode ( readValue ( buffer ) ! ) ;

 default :
 return super .readValueOfType ( type , buffer ) ;

 }
 }
 }

Similarly, the Dart and Android codes are almost the same and easy to understand. After all, they are a set of protocols and the rules are the same.

The following is the core of Pigeon. Let's see how the specific protocol is implemented. First, let's see how it is implemented in Dart. Since we call the code in Android from Flutter, according to the principle of Channel, we need to declare a Channel in Dart and process the data it returns.

If you are familiar with the use of Channel, then this code should be relatively clear.

Let's take a look at the implementation in Android. Android is the event handler, so it needs to implement the specific content of the protocol. This is the interface we implemented earlier. In addition, setMessageHandler needs to be added to handle the specific protocol.

The interesting part here is the encapsulation of the Reply class.

 public interface Result < T > {
 void success ( T result ) ;
 void error ( Throwable error ) ;
 }

As we said before, in Pigeon, asynchronous interfaces can be generated through @async. The implementation of this asynchronous interface is actually handled here.

Seeing this, you should almost understand how Pigeon works. To put it bluntly, it actually generates these codes through build_runner, doing all the dirty work by itself. What we see is actually the implementation and call of specific protocol classes.

Off topic

So, Pigeon is not something very advanced, but it is a very important idea of ​​Flutter mixing, or a guiding ideology of the Flutter team, which is to generate relevant code through "protocols" and "templates". Similar examples include JSON parsing, which is actually the case.

To say a little more, can the decoupling and modular operation between Android modules actually be handled in this way? Therefore, the simplest way leads to the same destination. In the end, the ideas in software engineering are actually similar. Everything changes, but ideas are eternal.