构建React Native插件化架构：基于Valtio的动态状态总线与Prettier的工程化约束

移动端架构

文章字数: 3.4k

阅读时长: 14 分

我们的React Native项目，一个金融数据分析工具，正变得越来越臃肿。最初的“一体化”设计，让行情图表、资讯流、交易模块等核心功能紧密耦合在主干代码中。每次迭代，不同业务线的团队都在同一个代码库里穿梭，合并冲突频发，发布周期也因此被一再拖延。一个模块的bug修复，需要整个应用进行回归测试和发版，成本高昂。我们急需一套解耦方案，将这些功能模块化、插件化，允许独立开发、测试，并由主应用动态集成。

这个问题的核心挑战有两个：

通信与状态同步： 主应用（Host App）和插件（Plugin）之间，以及插件与插件之间，需要一个低耦合、高性能的通信机制。插件需要能响应主应用的状态变化，也能将自身的状态和事件广播出去。
工程化一致性： 当多个团队在各自的仓库中开发插件时，如何保证代码风格、质量和依赖版本的一致性，避免集成时出现“千层饼”式的代码和难以追踪的问题。

初步构想是建立一个微内核架构。主应用作为内核，只负责提供渲染容器、路由、生命周期管理以及基础服务。所有业务功能都以插件形式存在。

graph TD
    subgraph Host App
        A[UI Container]
        B[Plugin Registry]
        C[State Bus]
    end

    subgraph Plugins
        P1[Chart Plugin]
        P2[News Plugin]
        P3[Trading Plugin]
    end

    A --> B
    B --> P1
    B --> P2
    B --> P3

    P1 <--> C
    P2 <--> C
    P3 <--> C
    A <--> C

    style Host App fill:#f9f,stroke:#333,stroke-width:2px
    style Plugins fill:#ccf,stroke:#333,stroke-width:2px

为了实现这个架构，我们需要谨慎地进行技术选型。对于状态总线，Redux的模式太重，需要为每个插件定义actions、reducers，模板代码繁多，不适合这种动态、松散的场景。Zustand更轻量，但我们想要的是一种更直观的、类似操作普通JavaScript对象的状态管理方式。Valtio，基于ES Proxy，允许直接修改状态对象并自动触发组件重渲染，这使其成为构建响应式状态总线的理想选择。它的API极其简单，几乎没有学习成本，正符合我们对插件开发“低侵入性”的要求。

对于工程化约束，答案几乎是唯一的：Prettier + Husky。Prettier负责代码格式的统一，而Husky则通过Git Hooks，在代码提交前强制执行Prettier，确保入库的每一行代码都符合规范。在多团队、多仓库的背景下，这种自动化约束是维持项目可维护性的生命线。

步骤一：定义插件契约与注册中心

一切始于契约。主应用和插件之间必须有一个清晰的接口定义。我们创建一个PluginContract.ts文件来定义这个契约。

// src/plugins/PluginContract.ts

import React from 'react';

/**
 * 插件暴露给主应用的接口定义
 */
export interface Plugin {
  // 插件的唯一标识符，用于注册和路由
  id: string;

  // 插件的显示名称，用于UI展示，如Tab标签
  name: string;

  // 插件的根组件，由主应用负责渲染
  component: React.ComponentType<any>;

  // 可选的初始化方法，在插件被加载时调用
  // 可以用于注册监听器、预加载数据等副作用
  initialize?: (context: PluginContext) => void;

  // 可选的销毁方法，在插件被卸载时调用
  // 用于清理资源，防止内存泄漏
  terminate?: () => void;
}

/**
 * 主应用提供给插件的上下文信息
 * 包含对共享状态总线的引用和其他服务
 */
export interface PluginContext {
  // 允许插件访问和修改共享状态
  stateBus: any; // 暂时用any，稍后会用Valtio的类型
  // 未来可以扩展，比如提供导航服务、API客户端等
  // navigation: NavigationService;
  // apiClient: ApiClient;
}

接着，我们构建一个简单的插件注册中心PluginRegistry。在真实项目中，这个注册表可能会从服务器动态获取，或者扫描本地的插件包。为了演示，我们先硬编码一个静态注册表。

// src/plugins/PluginRegistry.ts

import { Plugin } from './PluginContract';

// 引入具体的插件实现
// 在实际动态化方案中，这里会是动态加载
import { ChartPlugin } from './chart/ChartPlugin';
import { NewsPlugin } from './news/NewsPlugin';

class PluginRegistryService {
  private plugins: Map<string, Plugin> = new Map();

  constructor() {
    this.registerDefaultPlugins();
  }

  private registerDefaultPlugins() {
    // 模拟注册两个默认插件
    this.register(ChartPlugin);
    this.register(NewsPlugin);
    console.log('[PluginRegistry] Default plugins registered.');
  }

  public register(plugin: Plugin): void {
    if (this.plugins.has(plugin.id)) {
      console.warn(`[PluginRegistry] Plugin with id "${plugin.id}" is already registered. Overwriting.`);
    }
    this.plugins.set(plugin.id, plugin);
  }

  public getPlugin(id: string): Plugin | undefined {
    return this.plugins.get(id);
  }

  public getAllPlugins(): Plugin[] {
    return Array.from(this.plugins.values());
  }
}

// 使用单例模式，确保应用中只有一个注册中心实例
export const PluginRegistry = new PluginRegistryService();

步骤二：构建基于Valtio的状态总线

这是整个架构的核心。我们将创建一个Valtio proxy对象作为全局状态总线。这个总线将承载所有跨模块共享的状态。

// src/state/StateBus.ts

import { proxy } from 'valtio';

// 定义共享状态的结构
interface SharedState {
  // 当前激活的插件ID
  activePluginId: string | null;

  // 全局用户信息
  user: {
    id: string | null;
    name: string | null;
    isAuthenticated: boolean;
  };

  // 一个通用的数据载体，供插件之间传递数据
  // key可以是插件ID，避免命名冲突
  pluginPayloads: Record<string, any>;

  // 系统级别的状态，例如网络连接状态
  system: {
    isOnline: boolean;
  };
}

// 创建Valtio代理状态
// 这是整个应用唯一的真理之源 (Single Source of Truth)
export const stateBus = proxy<SharedState>({
  activePluginId: null,
  user: {
    id: null,
    name: null,
    isAuthenticated: false,
  },
  pluginPayloads: {},
  system: {
    isOnline: true,
  },
});

// 导出一个类型，方便在插件中使用
export type StateBusType = typeof stateBus;

// 为了调试，我们可以在开发模式下监听状态变化
if (__DEV__) {
  const { subscribe } = require('valtio');
  subscribe(stateBus, () => {
    console.log('[StateBus] State changed:', JSON.parse(JSON.stringify(stateBus)));
  });
}

这里的stateBus就是一个普通的JavaScript对象，但它被Valtio的proxy包裹。任何对stateBus属性的直接修改，例如 stateBus.activePluginId = 'chart'，都会被Valtio捕获，并自动通知所有订阅了该状态的React组件进行重渲染。这种设计极其简洁，插件无需分发action或调用setter函数，只需像操作本地变量一样操作stateBus。

步骤三：主应用的实现

主应用 App.tsx 的职责是渲染UI容器（比如底部的Tab导航），并根据stateBus中的activePluginId来动态渲染对应的插件组件。

// src/App.tsx

import React, { useEffect } from 'react';
import { SafeAreaView, View, Text, StyleSheet, TouchableOpacity } from 'react-native';
import { useSnapshot } from 'valtio';
import { stateBus, StateBusType } from './state/StateBus';
import { PluginRegistry } from './plugins/PluginRegistry';
import { Plugin, PluginContext } from './plugins/PluginContract';

const App: React.FC = () => {
  // 使用useSnapshot订阅stateBus的变化
  // 当stateBus的任何属性改变时，该组件会自动重渲染
  const snap = useSnapshot(stateBus);

  // 在应用启动时初始化所有插件
  useEffect(() => {
    const plugins = PluginRegistry.getAllPlugins();
    
    // 设置默认激活的插件
    if (plugins.length > 0 && !stateBus.activePluginId) {
      stateBus.activePluginId = plugins[0].id;
    }
    
    // 构建插件上下文
    const pluginContext: PluginContext = {
      stateBus: stateBus as StateBusType,
    };

    // 调用所有插件的initialize方法
    plugins.forEach(plugin => {
      if (plugin.initialize) {
        try {
          plugin.initialize(pluginContext);
        } catch (error) {
          console.error(`[HostApp] Failed to initialize plugin "${plugin.id}":`, error);
        }
      }
    });

    // 模拟用户登录
    setTimeout(() => {
      stateBus.user.isAuthenticated = true;
      stateBus.user.id = 'user-123';
      stateBus.user.name = 'Alice';
    }, 2000);

    return () => {
      // 应用关闭时，清理插件资源
      plugins.forEach(plugin => {
        if (plugin.terminate) {
          plugin.terminate();
        }
      });
    };
  }, []);

  const renderActivePlugin = () => {
    if (!snap.activePluginId) {
      return <Text style={styles.placeholder}>No active plugin</Text>;
    }
    const activePlugin = PluginRegistry.getPlugin(snap.activePluginId);
    if (!activePlugin) {
      return <Text style={styles.placeholder}>Plugin "{snap.activePluginId}" not found!</Text>;
    }
    const PluginComponent = activePlugin.component;
    return <PluginComponent />;
  };

  return (
    <SafeAreaView style={styles.container}>
      <View style={styles.header}>
        <Text style={styles.headerText}>
          Host App | User: {snap.user.isAuthenticated ? snap.user.name : 'Guest'}
        </Text>
      </View>
      <View style={styles.pluginContainer}>{renderActivePlugin()}</View>
      <View style={styles.tabBar}>
        {PluginRegistry.getAllPlugins().map(plugin => (
          <TouchableOpacity
            key={plugin.id}
            style={[styles.tabItem, plugin.id === snap.activePluginId && styles.activeTabItem]}
            onPress={() => {
              // 直接修改stateBus来切换插件，UI会自动响应
              stateBus.activePluginId = plugin.id;
            }}>
            <Text style={styles.tabText}>{plugin.name}</Text>
          </TouchableOpacity>
        ))}
      </View>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  // ... 样式定义 (省略)
});

export default App;

步骤四：插件的实现

现在，我们来看插件是如何实现的。以ChartPlugin为例，它需要展示图表，并且当资讯插件NewsPlugin发布了某个股票代码时，它需要接收并加载对应的图表。

// src/plugins/chart/ChartPluginComponent.tsx

import React from 'react';
import { View, Text, StyleSheet } from 'react-native';
import { useSnapshot } from 'valtio';
import { stateBus } from '../../state/StateBus';

export const ChartPluginComponent: React.FC = () => {
  // 订阅状态总线，只关心和自己相关的部分
  const { user, pluginPayloads } = useSnapshot(stateBus);
  const chartSymbol = pluginPayloads['news_selected_symbol'] || 'AAPL';

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Chart Plugin</Text>
      <Text>
        Rendering chart for: <Text style={styles.symbol}>{chartSymbol}</Text>
      </Text>
      <Text style={styles.userInfo}>
        Requested by: {user.name} ({user.id})
      </Text>
      {/* 在真实项目中，这里会是一个复杂的图表库 */}
    </View>
  );
};

const styles = StyleSheet.create({
  // ... 样式定义 (省略)
});

NewsPlugin则负责展示新闻列表，当用户点击某条新闻时，它会通过stateBus将股票代码广播出去。

// src/plugins/news/NewsPluginComponent.tsx

import React from 'react';
import { View, Text, StyleSheet, Button } from 'react-native';
import { stateBus } from '../../state/StateBus';

const newsItems = [
  { id: 1, title: 'Apple Inc. reaches new high', symbol: 'AAPL' },
  { id: 2, title: 'Microsoft reports strong earnings', symbol: 'MSFT' },
];

export const NewsPluginComponent: React.FC = () => {
  const handleNewsSelect = (symbol: string) => {
    console.log(`[NewsPlugin] Broadcasting symbol: ${symbol}`);
    // 直接修改stateBus，将选中的股票代码放入pluginPayloads
    // 任何订阅了此状态的组件（如ChartPlugin）都会自动更新
    stateBus.pluginPayloads['news_selected_symbol'] = symbol;
    // 顺便切换到图表插件，展示交互联动
    stateBus.activePluginId = 'chart';
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>News Plugin</Text>
      {newsItems.map(item => (
        <View key={item.id} style={styles.newsItem}>
          <Text>{item.title}</Text>
          <Button title={`View Chart for ${item.symbol}`} onPress={() => handleNewsSelect(item.symbol)} />
        </View>
      ))}
    </View>
  );
};

const styles = StyleSheet.create({
  // ... 样式定义 (省略)
});

最后，我们将这两个组件包装成符合Plugin契约的对象。

// src/plugins/chart/ChartPlugin.ts
import { Plugin } from '../PluginContract';
import { ChartPluginComponent } from './ChartPluginComponent';

export const ChartPlugin: Plugin = {
  id: 'chart',
  name: 'Charts',
  component: ChartPluginComponent,
  initialize: (context) => {
    console.log('[ChartPlugin] Initialized with bus state:', context.stateBus.system.isOnline);
  },
  terminate: () => {
    console.log('[ChartPlugin] Terminated.');
  }
};

// src/plugins/news/NewsPlugin.ts
import { Plugin } from '../PluginContract';
import { NewsPluginComponent } from './NewsPluginComponent';

export const NewsPlugin: Plugin = {
  id: 'news',
  name: 'News',
  component: NewsPluginComponent,
  initialize: () => {
    console.log('[NewsPlugin] Initialized.');
  }
};

至此，我们的插件化通信机制已经完成。NewsPlugin和ChartPlugin完全解耦，它们不知道对方的存在，唯一的交互媒介就是stateBus。这种模式极大地增强了系统的可扩展性。

步骤五：用Prettier和Husky强制实施工程纪律

架构的优雅需要工程纪律来维护。在项目根目录下，我们配置Prettier和Husky。

首先，安装依赖：
yarn add -D prettier husky lint-staged

然后，配置 package.json:

{
  "name": "react-native-plugin-app",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "android": "react-native run-android",
    "ios": "react-native run-ios",
    "start": "react-native start",
    "test": "jest",
    "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
    "prepare": "husky install"
  },
  "dependencies": {
    "react": "18.2.0",
    "react-native": "0.72.6",
    "valtio": "^1.11.2"
  },
  "devDependencies": {
    // ...
    "husky": "^8.0.0",
    "lint-staged": "^15.0.2",
    "prettier": "^3.0.3"
  },
  "lint-staged": {
    "**/*.{js,jsx,ts,tsx,json,md}": [
      "prettier --write"
    ]
  }
}

接着，创建Prettier的配置文件 .prettierrc.js:

// .prettierrc.js
module.exports = {
  arrowParens: 'avoid',
  bracketSameLine: true,
  bracketSpacing: true,
  singleQuote: true,
  trailingComma: 'all',
  printWidth: 100,
  tabWidth: 2,
};

最后，启用Husky：

运行 yarn prepare，这会创建 .husky 目录。
运行 npx husky add .husky/pre-commit "npx lint-staged"，这会创建一个 pre-commit 钩子。

现在，每当任何开发者（无论是开发主应用还是插件）试图提交代码时，lint-staged都会自动对暂存区的文件执行prettier --write。这从根本上杜绝了代码风格不一致的问题。一个常见的错误是，团队只在CI/CD流程中检查格式，但这太晚了，已经造成了不必要的代码审查开销和合并冲突。pre-commit钩子是真正的“安全左移”，在问题产生之前就将其解决。

架构的局限与未来迭代

这套基于Valtio和Prettier的插件化方案，解决了我们当前最棘手的解耦和协作问题，但它并非银弹。在真实项目中，还有几个悬而未决的挑战：

真动态化与热更新： 目前的插件注册是静态的。一个生产级的系统需要实现真正的动态加载，即从服务器拉取插件的JS Bundle并执行。这需要引入如Re.Pack之类的模块联邦方案，其配置和版本管理相当复杂，是下一个需要攻克的难关。
状态隔离与安全性： 全局stateBus虽然方便，但也存在风险。一个行为不当的插件可能会意外修改甚至清空属于其他插件的状态。未来的迭代需要考虑对stateBus进行封装，提供给每个插件一个带有命名空间或写权限限制的代理视图，以增强系统的鲁棒性。
插件依赖管理： 当插件自身也需要依赖第三方库时，版本冲突问题便会浮现。主应用和插件、插件和插件之间如何共享或隔离react, react-native等核心依赖，是一个需要精细设计的工程问题。目前我们的方案尚未触及这一层面。

React Native Valtio Prettier 架构设计状态管理

构建基于 OIDC 和 AWS SNS 的依赖项漏洞事件驱动告警管道

2023-10-27 DevSecOps

AWS SNS 依赖扫描 OpenID Connect GitHub Actions Terraform IaC

构建基于Buildah与Spinnaker的RAG混合检索服务自动化部署管道

2023-10-27 数据工程与存储

Buildah Spinnaker Qdrant Solr RAG GitOps