搜索插件、代码仓与 APP 分类

插件详情v2.0.0

beyond_helpers

用于实现超越架构模式的实用工具

AndroidiOSWebmacOSWindowsLinux
近 30 天下载
68
喜欢数
1
Pub 分数
150

安装插件

flutter pub add beyond_helpers

插件介绍

基于插件公开信息、社区数据与项目使用情况整理的选型参考。

Beyond Helpers 是一个实用程序包,旨在支持在 Flutter 应用中实现超越架构模式。它提供了轻量级、可重用的函数和扩展,以简化状态管理、依赖注入以及跨平台的架构一致性。该包通过提供用于代码整洁组织、高效数据流和可扩展应用结构的工具,补充了 Beyond 框架的功能。该包注重跨平台兼容性,可在 Android、iOS、Web、macOS、Windows 和 Linux 上无缝运行。非常适合希望在其 Flutter 项目中采用结构化、可维护架构的开发者。

适合场景

  • 实现超越架构模式
  • 简化状态管理
  • 增强依赖注入工作流
  • 构建可扩展的 Flutter 应用程序
  • 支持跨平台开发

主要特点

  • 轻量级实用函数
  • 跨平台兼容性
  • 常用任务的扩展
  • 与Beyond框架的集成
  • 简洁、一致的代码结构

适合对象

  • 使用超越架构的开发者
  • 注重可维护代码的团队
  • 需要可扩展状态管理的项目
  • Flutter 应用针对多个平台
  • 采用结构化模式的工程团队

使用建议

  • 需要熟悉超越架构
  • 最好在更大的Beyond生态系统中使用
  • 有限的独立功能
  • 不适用于简单或小型应用
  • 依赖外部 Beyond 框架

原始 README

以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。

Beyond

Actions Status

An example app that demonstrates an approach to scalable Flutter app development

Most Flutter content that currently exists focuses on state management and I hope this can dig into other areas a bit more. Beyond just state management

I am open to feedback, suggestions, and discussions on how this approach can be improved.

It's important to note that this is not meant to prescribe how everyone should write Flutter apps nor that this is the best option for every project.

Example App Setup

  1. Get a free API key from https://locationiq.com/
  2. Open lib/service/config/config.dart and enter your API key

Beyond Helpers

Beyond Helpers is a collections of minor utilities to help with implementing this approach

Architecture Overview

The rest of this document describes how apps that use this approach are structured and why.

Goals

  • Simple
  • Clean
  • Testable
  • Consistent
  • Don't reinvent the wheel, use libraries when appropriate

Page

A Widget that takes up the entire view of your application and can be navigated to and from. Pages contain other Widgets that are used to compose UI.

ViewModel

A class that contains all the logic and local state for a Page or other component. Provides a way to interact with and react to that state. Every Page should have a ViewModel. Other UI components that are not Pages can also have ViewModels when needed. Powered by MobX. See more below about state management.

Service

A class that provides a way for the app to interact with something outside of its control. Examples are: web APIs, native device APIs, SDKs, and databases. Ideally services should hold minimal amounts of state.

Lets look two examples of Services in this project

Service Example 1: ApiService

The ApiService provides a way for our app to interact with the LocationIQ REST Api. When interacting with a REST Api there are a few things you need to do. Create Api models, serialize/deserialize JSON, handle authentication, etc. The Service should encapsulate most of that, and expose an interface that is easy to use and understand to the rest of the app.

Lets look at the public interface of this Service

String token;
Future<ApiResponse<String>> getAuthToken(String username, String password);
Future<ApiResponse<Place>> getPlace(double longitude, double latitude);
Future<ApiResponse<List<PointOfInterest>>> getPointsOfInterest(double longitude, double latitude, String type, {int radius = 500});
String getStaticMapImageUrl(String longitude, String latitude);

From the above its clear how to use this Service and its easy to know what data you get back. Anyone working on your app won't need to know the implementation details of the Service.

Another reason we abstract the API with a Service is for mocking during tests. It's very simple to use a mock that returns anything you want from the above methods and properties. This will be expanded on below in Testing.

Service Example 2: SharedPreferencesService

The SharedPreferencesService provides a way to for our app to interact with the native SharedPreferences/NSUserDefaults APIs on Android and iOS.

You may be thinking "Wait, isn't there an official package for this?" and you would be right. We are using that package here and we are not redeveloping its functionality.

Here is our SharedPreferencesService. We have only implemented what our app currently needs.

class SharedPreferencesService implements Startable {
  SharedPreferences prefs;

  @override
  Future start() async {
    prefs = await SharedPreferences.getInstance();
  }

  Future<bool> setString(String key, String value) {
    return prefs.setString(key, value);
  }

  String getString(String key) {
    return prefs.getString(key);
  }
}

Why wrap the SharedPreferences library in our own service? There are a few reasons.

First, to allow for better mocking and testing. Anything that interacts with things outside of your control (Services) should be mocked in most tests. For native Apis especially as there is no Android or iOS when running Flutter tests. If you try to use SharedPreferences during a test you will get MissingPluginException. Thats no good.

While you can use setMockMethodCallHandler to mock calls to the native platform, that requires you to have a pretty solid understanding of how the plugin makes native calls and what data it expects. These calls can change version to version without changes to the public API of the plugin.

Second, startup control. Some Services will require some asynchronous work before they are ready to be used. You can see that in the SharedPreferencesService above and also in the PackageInfoService. Creating our own classes allows us to standardize the startup of all these Services with a common interface (Startable) and lets us know for sure when the Service is ready to be used by the rest of the app.

Manager

A class that holds global state and provides ways to interact with and react to that state.

TODO

State Management

There are many articles and discussions on state management for Flutter so I will only touch on this briefly.

Lets define what state management is when it comes to writing a Flutter app.

State management is...

  • How the app interacts with data
  • How the app reacts to changes in data
  • How the app organizes code related to doing the above

If you look at the above statements and compare them to using StatefulWidgets and setState you will come to a few limitations when working on a large app.

  • App state and UI are tied closely together
  • Ties rebuilding UI to the same scope as your state
  • Makes it hard to separate UI code from "business logic"

The above can be challenging when building a large application. There are a few alternative approaches built into Flutter and many third party libraries that each have different ways of solving for this.

MobX is the library used for state management here and the below section will expand on why.

Why MobX?

There are a few primary reasons why MobX is the preferred choice for state management.

TODO

Service Location & Dependency Injection

For SL and DI we keep it simple. We have a ServiceLocator that contains all our singletons and prepares them for use by the rest of the app.

We also have a ViewModelFactory that is used to create instances of ViewModels and pass in parameters.

These 2 classes allow all our app's components to request what they need by constructor injection.

SL & DI Example 1: AuthManager

To understand what a class in our app depends on, just look at the final fields and constructor.

final ApiService _api;
final SharedPreferencesService _sharedPreferencesService;

AuthManager(this._api, this._sharedPreferencesService);

Here you can see the AuthManager requires the ApiService and the SharedPreferencesService. Easy. To provide these, just pass them in when the app starts up in our ServiceLocator.

AuthManager authManager;

ServiceLocator() {
  configService = ConfigService();
  packageInfoService = PackageInfoService();
  apiService = ApiService(configService, packageInfoService);
  sharedPreferencesService = SharedPreferencesService();
  authManager = AuthManager(apiService, sharedPreferencesService);
}

If you ever need the AuthManager to use another class, just pass it in and add it as another final field in the AuthManager.

SL & DI Example 2: ViewModels

ViewModels are created on demand when the Widgets that require them are created. Same as the AuthManager above, looking at the constructor tells you what is required to create it.

ViewModels can also have parameters that are not from our ServiceLocator. Below is our ParkDetailViewModel that requires a Park object to be passed in as well.

class ParkDetailViewModel {
  final ApiService _apiService;
  final Park _park;

  String get parkName => _park.name;

  String get distanceFrom => "You are ${_park.distance} meters away";

  ParkDetailViewModel(this._park, this._apiService);
}

As mentioned before, our ViewModelFactory is responsible for creating these ViewModels. Add to it as you build out your app.

class ViewModelFactory {
  final ServiceLocator _locator;

  ViewModelFactory(this._locator);

  LoginViewModel login() => LoginViewModel(_locator.authManager);

  HomeViewModel home() => HomeViewModel(
      _locator.authManager,
      _locator.apiService,
      _locator.locationService,
      _locator.navigationManager);

  ParkDetailViewModel parkDetail(Park park) =>
      ParkDetailViewModel(park, _locator.apiService);
}

You can see above that the HomeViewModel and LoginViewModel don't need any extra arguments, while ParkDetailViewModel needs the Park passed in.

Testing

Testing is very important in any app designed to scale. The below sections go into detail about the different types of testing I recommend for this approach.

Testing Setup

Before writing tests we setup mocks, stubs and configure our ServiceLocator for testing. Mockito is used for mocking, stubbing and validating interactions with mocks.

Mocks & Basic Stubs

Create mock classes for each class you plan to mock. This should mainly be Services.

Mocking services is very important since things outside of your control can alter the results of your tests despite code not changing. The large majority of tests should only test the code in your project, not Web APIs or native device APIs.

By default mocks will let you call any function or access any field, always retuning null. Setup some basic stubs that allow simple tests to run without having to specify common behavior in every test.

You can start small, only stubbing what you need to, and expand over time.

class MockSharedPreferencesService extends Mock implements SharedPreferencesService {}

class MockApiService extends Mock implements ApiService {}

void setupApiStubs(ApiService api) {
  when(api.getAuthToken(any, any))
      .thenAnswer((_) => Future.value(ApiResponse(200, data: "token")));
  when(api.getPlace(any, any)).thenAnswer(
    (_) => Future.value(
      ApiResponse(
        200,
        data: Place(
          lat: "42",
          lon: "42",
          displayName: "Place",
          address: Address(city: "city", road: "road", houseNumber: "42"),
        ),
      ),
    ),
  );
  when(api.getPointsOfInterest(any, any, any)).thenAnswer(
    (_) => Future.value(
      ApiResponse(
        200,
        data: [
          PointOfInterest(lat: "42", lon: "42", name: "POI", distance: 10)
        ],
      ),
    ),
  );
}

void setupSharedPreferencesStubs(SharedPreferencesService sharedPreferences) {
  when(sharedPreferences.setString(any, any))
      .thenAnswer((_) => Future.value(true));
}
TestServiceLocator

When integration or end to end testing it's handy to have your service locator setup with mocks. This lets you access components like ViewModels just as you do in your application, and takes care of passing around mock and real dependencies.

Here you can see us setting up our ServiceLocator with mocks for our Services and real implementations for our other components.

We also setup some basic stubs that can be used in most tests, as noted before.

class TestServiceLocator extends ServiceLocator {
  TestServiceLocator() : super.empty() {
    // Mocks
    sharedPreferencesService = MockSharedPreferencesService();
    apiService = MockApiService();
    locationService = MockLocationService();

    // Real
    authManager = AuthManager(apiService, sharedPreferencesService);
    viewModelFactory = ViewModelFactory(this);
    navigationManager = NavigationManager(viewModelFactory, authManager);

    // Basic stubbing useful for many tests
    // Can be overridden in specific tests as needed
    setupApiStubs(apiService);
    setupSharedPreferencesStubs(sharedPreferencesService);
    setupLocationStubs(locationService);
  }
}
Unit Testing: Managers

Unit testing is best suited to code you completely control and the more valuable code should be tested first. For this approach, Managers should be the priority to test.

Here is an example of our AuthManager tests that demonstrate how we use our mocks and validate behavior.

Take note of resetting the mocks per test and overriding the basic stubs with test specific stubs.

These tests are written as AAA (Arrange, Act, Assert), but feel free to structure the actual tests however you prefer.

void main() {
  // Mock dependencies
  MockApiService api;
  MockSharedPreferencesService sharedPreferences;

  // System under test
  AuthManager auth;

  // Create our mocks with basic stubs
  // Do this before every test to ensure fresh mocks
  setUp(() {
    api = MockApiService();
    sharedPreferences = MockSharedPreferencesService();

    setupApiStubs(api);
    setupSharedPreferencesStubs(sharedPreferences);
  });

  void createSystemUnderTest() {
    auth = AuthManager(api, sharedPreferences);
  }

  test('loadSavedLogin with no saved login results in logged out AuthState',
      () async {
    // Arrange
    createSystemUnderTest();

    // Act
    auth.loadSavedLogin();

    // Assert
    assert(auth.authState != null);
    assert(!auth.authState.isLoggedIn);
    assert(auth.authState.token == null);
  });

  // Other than the basic stubs, we can stub for a specific test as well
  // This stub is removed at the end of the test as we recreate mocks in setUp
  test('loadSavedLogin with saved login results in logged in AuthState',
      () async {
    // Arrange
    createSystemUnderTest();
    when(sharedPreferences.getString("loginToken")).thenReturn("token");

    // Act
    auth.loadSavedLogin();

    // Assert
    assert(auth.authState != null);
    assert(auth.authState.isLoggedIn);
    assert(auth.authState.token == "token");
  });
}
UI Integration Testing: Pages, Widgets, ViewModels
Pages & ViewModels

TODO

Widgets

TODO

Integration Testing: Services

TODO

End To End Testing

TODO

Code Style

Other than the structure mentioned in this document, Pedantic is a library that help enforces best practices for Dart code.

Configuration

TODO: Implement this section in example app

When building client side applications its important to be able to support them remotely. After a user installs an app there is basically no way to force them to update. I always suggest adding a way to remotely configure your app without pushing an update.

You should be able to do the following without releasing an client side update.

  • Change URLs for Web APIs
  • Change API keys
  • Enforce a minimum supported version

Dependencies

These are the libraries used for this approach to Flutter development. There are other libraries used in the example app, but these are the ones that are important and recommended for this approach.

所属分类

依赖

依赖清单 1 项

源码仓库

使用此插件的项目

暂无相关数据。