@vlian/infrastructure

通用业务基础设施包，提供业务无关的通用能力，可以被多个业务模块复用。

特性

• 🎯 业务无关性：所有功能不绑定特定业务场景，通过配置适配不同场景
• ⚙️ 可配置性：通过配置参数适配不同业务需求
• 🧩 可组合性：按需使用，不强制全量引入
• 🔌 框架无关性：可以独立使用，也可以与框架集成
• 💻 纯逻辑层：不包含 UI 实现，只提供业务逻辑和 API
• 📦 TypeScript 支持：完整的类型定义，提供优秀的开发体验
• 🚀 高性能：内置缓存机制，支持并发控制，优化性能

安装

npm install @vlian/infrastructure
# 或
pnpm add @vlian/infrastructure
# 或
yarn add @vlian/infrastructure

核心模块

AuthManager（认证管理）

提供登录/登出、Token 管理、用户信息管理等核心认证能力。

import { AuthManager } from '@vlian/infrastructure';

const authManager = new AuthManager({
  storage: { strategy: 'local' },
  tokenKey: 'auth_token'
});

await authManager.login('username', 'password');
const isAuth = authManager.isAuthenticated();

PermissionManager（权限管理）

提供角色管理、权限点管理、权限检查等能力。

import { PermissionManager } from '@vlian/infrastructure';

const permissionManager = new PermissionManager({
  authManager,
  cacheEnabled: true
});

const canEdit = permissionManager.hasPermission('user:edit');
const isAdmin = permissionManager.hasRole('admin');

ThemeManager（主题管理）

提供主题切换、主题配置、主题持久化等能力。

import { ThemeManager } from '@vlian/infrastructure';

const themeManager = new ThemeManager({
  defaultTheme: 'light',
  enableCache: true
});

themeManager.setTheme('dark');
const currentTheme = themeManager.getTheme();

UserManager（用户管理）

提供用户信息获取/更新、用户设置管理等能力。

import { UserManager } from '@vlian/infrastructure';

const userManager = new UserManager({
  authManager,
  enableCache: true
});

const userInfo = await userManager.getUserInfo();
await userManager.updateUserInfo({ email: '[email protected]' });

NotificationManager（通知管理）

提供系统通知、消息通知、待办事项等能力。

import { NotificationManager } from '@vlian/infrastructure';

const notificationManager = new NotificationManager({
  notificationFetcher: async () => {
    const response = await fetch('/api/notifications');
    return response.json();
  },
  enableCache: true
});

const notifications = await notificationManager.getNotifications();
const unreadCount = await notificationManager.getUnreadCount();

DictionaryManager（数据字典）

提供字典数据获取、字典缓存、字典格式化等能力。

import { DictionaryManager } from '@vlian/infrastructure';

const dictionaryManager = new DictionaryManager({
  dictionaryFetcher: async (code) => {
    const response = await fetch(`/api/dictionaries/${code}`);
    return response.json();
  },
  enableCache: true
});

const statusDict = await dictionaryManager.getDictionary('status');
const label = await dictionaryManager.getDictionaryValue('status', 'active');

SystemConfigManager（系统配置）

提供配置获取/更新、配置缓存等能力。

import { SystemConfigManager } from '@vlian/infrastructure';

const systemConfigManager = new SystemConfigManager({
  configFetcher: async (key) => {
    const response = await fetch(`/api/config${key ? `/${key}` : ''}`);
    return response.json();
  },
  enableCache: true
});

const theme = await systemConfigManager.getConfig('theme');
await systemConfigManager.updateConfig('theme', 'dark');

快速开始

基础示例

import { AuthManager, PermissionManager } from '@vlian/infrastructure';
import { Storage, Logger } from '@vlian/framework';

// 初始化依赖
const storage = new Storage();
const logger = new Logger();

// 创建 Manager 实例
const authManager = new AuthManager({
  storage,
  logger,
  tokenKey: 'auth_token',
  refreshTokenKey: 'refresh_token'
});

const permissionManager = new PermissionManager({
  authManager,
  cacheEnabled: true
});

// 使用
await authManager.login('username', 'password');
const canEdit = permissionManager.hasPermission('user:edit');

文档

详细的文档请参考：

• 认证管理使用手册
• 权限管理使用手册
• 主题管理使用手册
• 用户管理使用手册
• 通知管理使用手册
• 数据字典使用手册
• 系统配置使用手册

依赖

• 必需依赖：@vlian/framework (^1.1.0)
• 开发依赖：TypeScript, SWC, Vitest

架构设计

本项目遵循以下核心原则：

1. 业务无关性：配置类型完全泛型化，由用户定义
2. 依赖注入：依赖 @vlian/framework，通过依赖注入解耦
3. 单一职责：每个模块职责单一，便于维护和测试
4. 方法复用：公共逻辑提取到工具模块，避免重复代码
5. 框架依赖明确：所有日志、监控、存储、状态管理、事件总线都使用 @vlian/framework 提供的服务
6. 可选依赖：日志、监控、事件可完全禁用，降低小项目使用成本
7. 实例隔离：支持实例隔离模式，避免 SSR/微前端中的全局单例争抢
8. 并发控制：支持串行队列和版本号机制，保证操作一致性

开发

# 安装依赖
pnpm install

# 构建
pnpm run build

# 开发模式（监听文件变化）
pnpm run dev

# 运行测试
pnpm run test

# 测试覆盖率
pnpm run test:coverage

许可证

MIT

更新日志

详细的更新日志请参考 CHANGELOG.md

贡献

欢迎提交 Issue 和 Pull Request！

相关链接

• GitHub
• 问题反馈