@realnation/builder-shared-sdk

一个为Vite模块联邦微前端设计的轻量级SDK，旨在简化Host（宿主应用）与Remote（远程模块）之间的通信和流程控制。

✨ 功能

- HTTP客户端共享: 提供统一的axios实例，自动处理鉴权Token，避免在每个Remote中重复配置。
- 全局事件总线: 一个简单的发布/订阅系统，用于在Host和Remotes之间或Remotes彼此之间进行解耦的通信。
- 动态流程控制: 一个极其灵活的事件驱动流程控制机制，允许Host动态注册回调，由任意Remote在特定时机触发。

📦 安装

``bash
npm install @realnation/builder-shared-sdk


or

yarn add @realnation/builder-shared-sdk

or

pnpm add @realnation/builder-shared-sdk
`

🚀 快速上手

$3

在您的Host应用启动时，配置共享的HTTP客户端。

`typescript
import { configureHttpClient, setAuthToken } from '@realnation/builder-shared-sdk';

// 登录后，从您的用户会话中获取Token
const userToken = 'your-jwt-token-here';
setAuthToken(userToken);

// 配置API基础URL和超时
configureHttpClient({
baseURL: 'https://api.example.com',
timeout: 15000,
});
`

$3

在任何Remote模块中，直接获取已配置好的axios实例来发起请求。

`typescript
import { getHttpClient } from '@realnation/builder-shared-sdk';

async function fetchSomeData() {
try {
const httpClient = getHttpClient();
const response = await httpClient.get('/data');
console.log(response.data);
} catch (error) {
console.error('Request failed:', error);
}
}
`

$3

SdkEventBus可用于在不同模块间传递消息，而无需直接依赖。

在Host或某个Remote中监听事件:

`typescript
import { getGlobalEventBus } from '@realnation/builder-shared-sdk';

const eventBus = getGlobalEventBus();

// 监听模块导航事件
const unsubscribe = eventBus.on('module:navigate', (payload) => {
console.log('Navigating to:', payload.path);
// 在这里执行路由跳转逻辑...
});

// 在组件卸载或不再需要时取消监听
// unsubscribe();
`

在另一个Remote中触发事件:

`typescript
import { getGlobalEventBus } from '@realnation/builder-shared-sdk';

const eventBus = getGlobalEventBus();

function onButtonClick() {
eventBus.emit('module:navigate', { path: '/new-page' });
}
`

🔗 动态流程控制 (Flow Control)

这是SDK的核心亮点之一，提供了一种比传统模块联邦更灵活的模块间协作方式。Host可以定义一组具名事件（例如 success, failure, nextStep），并将它们与具体的操作（例如加载下一个Remote模块）关联起来。Remote模块在完成其任务后，只需触发这些预定义的事件，而无需关心接下来会发生什么。

$3

Flow Control区分两种事件类型：

1. 系统事件 (System Events): 以sys:为前缀，由SDK或框架约定，用于处理通用的生命周期钩子。例如 sys:ready。这些事件不会被clearEvents()清除。
2. 自定义事件 (Custom Events): 不带前缀，由业务逻辑定义，例如 welcome:completed 或 profile:submitted。这些事件会被clearEvents()清除。

$3

1. Host注册事件: Host应用使用registerEvent注册系统事件和自定义事件的回调。
* 注册sys:ready来处理Remote模块加载完成后的显示逻辑。
* 注册自定义事件来编排业务流程。
2. Remote触发事件:
* Remote模块加载并初始化完成后，应立即触发sys:ready事件，通知Host可以将其UI插入DOM并显示。
* 在用户交互或内部状态改变后，触发相应的自定义事件。
3. 执行与回退:
* 如果Host注册了该事件，对应的回调函数将被执行。
* 如果Host没有注册该事件，emitEvent会执行一个可选的本地回退函数（最后一个函数类型的参数），确保Remote在独立运行时也能正常工作。
4. 清理: 在业务流程结束时，Host调用clearEvents()来清理所有自定义事件，而系统事件保持不变。

$3

#### 在Host中编排流程

`typescript
import { registerEvent, clearEvents } from '@realnation/builder-shared-sdk/flow';
import { loadRemoteModule, showRemote, hideRemote } from './remoteLoader'; // 假设的加载器

// 注册系统事件，用于显示已加载的模块
registerEvent('sys:ready', (remoteId) => {
console.log(Remote module [${remoteId}] is ready to be displayed.);
showRemote(remoteId);
});

// 注册自定义业务事件
registerEvent('welcome:completed', () => {
hideRemote('welcome'); // 隐藏旧模块
loadRemoteModule('user-profile'); // 加载新模块
});

registerEvent('profile:submitted', (userData) => {
hideRemote('user-profile');
loadRemoteModule('summary-view', { user: userData });
});

// 当整个业务流程结束时，清理自定义事件
function cleanupBusinessFlow() {
clearEvents();
}
`

#### 在Remote中触发事件

welcome-module (远程模块):

`typescript
import { emitEvent } from '@realnation/builder-shared-sdk/flow';
import React, { useEffect } from 'react';

function WelcomeComponent({ remoteId }) {
// 1. 组件挂载后，触发 sys:ready 事件
useEffect(() => {
emitEvent('sys:ready', remoteId, () => {
console.log(Standalone mode: [${remoteId}] is ready.);
});
}, [remoteId]);

const handleStartClick = () => {
// 2. 用户交互，触发自定义事件
emitEvent('welcome:completed', () => {
console.log('Standalone mode: Welcome journey would start here.');
});
};

return 开始;
}
`

user-profile-module (远程模块):

`typescript
import { emitEvent } from '@realnation/builder-shared-sdk/flow';

function UserProfileForm() {
const handleSubmit = (formData) => {
// 触发 'profile:submitted' 事件，并传递表单数据
emitEvent('profile:submitted', formData, () => {
console.log('In standalone mode: Form submitted locally.', formData);
// 在独立模式下可以导航到本地的下一页
});
};

// ... 表单逻辑
}
`

这种模式的优势在于：

- 高度解耦: Remote模块不关心下一个模块是什么，只关心在何时完成了自己的任务。
- 灵活编排: Host可以随时改变流程，例如在A/B测试中，通过注册不同的回调来加载不同的下一个模块，而无需修改任何Remote模块的代码。
- 易于测试: Remote模块可以独立开发和测试，只需为其emitEvent提供本地回退函数即可。

🛠️ API参考

$3

- setAuthToken(token: string | null): 设置全局JWT Token。
- setTokenResolver(resolver: () => string | null): (高级) 设置一个函数来动态解析Token，优先级高于setAuthToken。
- configureHttpClient(options: HttpClientOptions): 配置共享的axios实例。
- getHttpClient(): AxiosInstance: 获取配置好的axios实例。

$3

- getGlobalEventBus(): SdkEventBus: 获取全局事件总线实例。
- eventBus.on(name, handler): 监听一个事件。
- eventBus.emit(name, payload): 触发一个事件。
- eventBus.off(name, handler): 取消监听。

$3

- registerEvent(type: string, callback: Function): Host注册一个流程事件。以sys:为前缀的事件为系统事件，不会被clearEvents清除。
- removeEvent(type: string): 移除一个已注册的事件。
- clearEvents(): 移除所有非系统级的自定义事件。
- emitEvent(type: string, ...args: any[]): Remote触发一个流程事件。参数会透传给回调，如果最后一个参数是函数，则被视作本地回退callback。

🔧 构建

`bash
npm run build
`

该命令会使用tsc将src目录下的TypeScript源文件编译到dist`目录。