@spark-view/spark-utils

SPARK 核心工具库 - 提供能力系统、日志、权限和 HTTP 客户端

特性

• 🔌 能力系统 - 供需解耦的组件通信机制
• 📝 日志系统 - 多传输器、多级别日志
• 🔐 权限系统 - 统一的权限检查和过滤
• 🌐 统一请求层 - 基于拦截器的现代化请求系统
• 📡 文件加载器 - 基于时间戳的智能缓存
• 🎯 事件系统 - 类型安全的事件发布订阅

安装

pnpm add @spark-view/spark-utils

快速开始

1. 能力系统

import { defineCapability, provide, lookup } from '@spark-view/spark-utils'
import { useSparkComponent } from '@spark-view/spark-component'

// 定义类型安全的能力键
const USER_SERVICE = defineCapability<{ getUser(id: string): { id: string; name: string } }>('app:user-service')

// 提供能力（在父组件 setup 中）
const { provide: provideCapability } = useSparkComponent({ type: 'provider' })
provideCapability(USER_SERVICE, {
  getUser: (id) => ({ id, name: 'User' })
})

// 消费能力（任意深度子组件 setup 中）
const { consume } = useSparkComponent({ type: 'consumer' })
const service = consume(USER_SERVICE)  // 类型自动推断，null 表示未找到
service?.getUser('1')

特性:

• ✅ 能力树：通过 parent 链构建层级
• ✅ 就近查找：沿 parent 链向上查找
• ✅ 解耦设计：供需互不依赖
• ✅ 类型安全：完整 TypeScript 支持

2. 日志系统

import { Logger } from '@spark-view/spark-utils'

// 方式 1：简单字符串标签（用于简单脚本或独立模块）
const logger = Logger('MyModule')
logger.info('应用启动')
logger.error('错误', { code: 500 })

// 方式 2：从组件上下文获取应用层提供的 logger（推荐）
const { logger } = useSparkComponent({ type: 'my-comp' })
logger.info('组件初始化')  // 自动使用应用层配置的 logger

// 应用层提供 logger（在 main.ts 或 App.vue 中）
import { createLogger } from '@spark-view/spark-app'
const appLogger = createLogger('App', {
  level: 'info',
  enableRemote: true,  // 生产环境远程上报
  remoteEndpoint: '/api/logs'
})

// 在组件 setup 中通过 SPARK 能力系统提供
import { LOGGER, APP_SERVICES } from '@spark-view/spark-utils'
const { provide: provideCapability } = useSparkComponent({ type: 'app-root' })
// 方式 1：直接覆盖 logger
provideCapability(LOGGER, appLogger)
// 方式 2：通过 APP_SERVICES 提供（推荐，同时提供 router 等）
provideCapability(APP_SERVICES, { logger: appLogger, router: /* 路由实例 */ undefined })

特性:

• ✅ 多级别：debug、info、warn、error
• ✅ 应用层统一配置：全局日志级别、传输器、格式
• ✅ 继承支持：子组件自动继承应用层 logger
• ✅ 多种传输器：console、HTTP（远程上报）、custom
• ✅ 生产环境支持：远程日志上报、错误追踪

推荐架构：

1. 应用层（main.ts）创建全局 logger 并配置传输器
2. 通过 APP_SERVICES 或直接 provide('logger') 提供
3. 组件通过 useSparkComponent 获取 logger
4. 所有日志统一格式、统一管理

3. 权限系统

import { 
  createPermissionChecker, 
  createPermissionFilter,
  createFieldRenderHelper
} from '@spark-view/spark-utils'

// 权限检查
const checker = createPermissionChecker()
const canDelete = checker.canDelete(row)
const canEdit = checker.canEdit(row)

// 权限过滤
const filter = createPermissionFilter()
const deletableRows = filter.filterDeletableRows(rows)

// 字段渲染
const helper = createFieldRenderHelper()
const states = helper.computeFieldStates(fields, row)

4. 统一请求层

import { 
  createRequest,
  createAuthInterceptor,
  createStandardApiInterceptor
} from '@spark-view/spark-utils'

// 创建请求实例
const request = createRequest({
  baseURL: '/api',
  timeout: 10000
})

// 配置拦截器
request.interceptors.request.use(
  createAuthInterceptor(() => localStorage.getItem('token'))
)
request.interceptors.response.use(
  createStandardApiInterceptor()
)

// 发起请求
const users = await request.get('/users')
const newUser = await request.post<User>('/users', { name: 'John' })

特性:

• ✅ 拦截器系统：请求/响应双向拦截
• ✅ 自动重试：支持配置重试次数和延迟
• ✅ 内置缓存：GET 请求自动缓存
• ✅ 超时控制：基于 AbortController
• ✅ 9 个预设拦截a器：认证、租户、日志、错误处理等
• ✅ TypeScript 类型安全

完整指南: REQUEST_GUIDE.md

5. 文件加载器

import { createFileLoader } from '@spark-view/spark-utils'

// 创建文件加载器
const loader = createFileLoader({
  baseURL: '/config',
  storage: 'localStorage'
})

// 加载文件（带时间戳缓存）
const config = await loader.load('app.json', { timestamp: 123456 })

// 批量加载
const [rule, pageData] = await loader.loadMultiple([
  { url: 'rule.json', options: { timestamp: 123456 } },
  { url: 'pagedata.json', options: { timestamp: 789012 } }
])

特性:

• ✅ 时间戳缓存：前端带 timestamp，后端判断变化
• ✅ 自动降级：网络失败自动使用缓存
• ✅ 三种存储策略：localStorage/sessionStorage/memory
• ✅ 批量加载：Promise.all 并行加载
• ✅ 缓存统计：查看缓存命中率

6. 事件系统

import { createEventEmitter } from '@spark-view/spark-utils'

type MyEventMap = {
  'user:login': [user: { id: number; name: string }]
  'user:logout': []
}

const emitter = createEventEmitter<MyEventMap>()
emitter.on('user:login', (user) => console.log(user))
emitter.emit('user:login', { id: 1, name: 'Alice' })

核心模块

| 模块 | 说明 | |------|------| | Capability | 能力系统（Provider/Consumer） | | Logger | 日志系统（多级别、多传输器） | | Permission | 权限系统（检查器、过滤器、渲染助手） | | Request | 统一请求层（拦截a器、重试、缓存） | | FileLoader | 文件加载器（时间戳缓存、自动降级） | | EventEmitter | 事件发射器（类型安全） | | Data Types | 基础数据类型和权限接口 |

数据类型

// 基础数据行
type DataRow<T = unknown> = Record<string, T>

// 组件数据行（带权限）
type ComponentDataRow<T = unknown> = WithInstancePermission<DataRow<T>>

// 实例级权限
interface IInstancePermission {
  allowDelete?: boolean
  editableFields?: string[]
  hiddenFields?: string[]
  maskedFields?: string[]
}

// 模型级权限
interface IModelPermission {
  allowCreate?: boolean
  allowImport?: boolean
  allowExport?: boolean
}

依赖

无外部依赖（纯 TypeScript 实现）

开发命令

pnpm run typecheck   # 类型检查
pnpm run build       # 构建包

License

MIT