sc-business-lodash 使用指南

sc-business-lodash 是为公司业务场景定制的工具库，提供 HTTP 请求封装、认证、字典、缓存、消息通知、sei-base 数据源等功能。

安装

pnpm install sc-business-lodash

---

一、初始化配置

所有功能使用前需先调用 initConfig，通常在项目入口（main.ts）执行一次。

import { initConfig } from 'sc-business-lodash'
import router from './router'

initConfig({
  // 是否启用 sei 模式（切换接口路径、code 码、数据结构）
  isSei: true,

  http: {
    baseUrl: '/api',
    timeout: 10000,
  },

  auth: {
    tokenKey: 'token',       // localStorage 中存 token 的 key
    loginPage: '/login',     // 登录失效后跳转的路由
  },

  router: {
    jumpPush: (path) => router.push(path),
    jumpReplace: (path) => router.replace(path),
    jumpBack: () => router.back(),
  },

  alert: {
    successToastCallback: (msg) => ElMessage.success(msg),
    errorToastCallback: (msg) => ElMessage.error(msg),
    warningToastCallback: (msg) => ElMessage.warning(msg),
    startLoadingCallback: (text) => ElLoading.service({ text }),
    endLoadingCallback: (loading) => loading?.close(),
  },
})

isSei 模式说明

isSei: true 时，以下行为自动切换：

功能	platform 模式	sei 模式
登录接口	/platform/auth/login/public/pwdLogin	/sei/public/login
获取用户信息	/platform/auth/login/getUserInfo	/sei/user/public/getUserInfo
登出	/platform/auth/login/public/exit	/sei/logout
字典接口	/platform/resource/dictionary/dictTranslate	/sei/data/public/query
成功 code	"00000"	1
登录失效 code	"40003"	-2

---

二、HTTP 请求

import { $get, $post, $downloadPost, $upload } from 'sc-business-lodash'

// GET
const res = await $get({ url: '/user/list', params: { page: 1 } })

// POST
const res = await $post({ url: '/user/save', data: { name: '张三' } })

// 文件下载
await $downloadPost({ url: '/report/export', data: { id: 1 } })

// 文件上传
await $upload({ url: '/file/upload', formData: { file: fileObj } })

请求参数说明

参数	类型	说明
url	string	请求地址
data	any	请求体
params	any	URL 查询参数
method	string	请求方法，默认 GET
showToast	boolean | object	是否显示提示，默认 true
loadingToast	boolean | object	是否显示加载，默认 true
isCheckCode	boolean	是否检查业务 code，默认 true
isOriginalData	boolean	返回 axios 原始响应，需配合 isCheckCode: false
responseType	string	axios responseType
timeout	number	超时时间（ms）

---

三、认证

import { loginPassword, loginOut, getUserServer, getToken, isLogin } from 'sc-business-lodash'

// 登录（自动存 token 并拉取用户信息）
await loginPassword({ data: { username: 'admin', password: '123456' } })

// 登出
await loginOut()

// 判断是否已登录
if (isLogin()) { ... }

// 获取 token
const token = getToken()

验证码

import { handleGetSmsCodeImage, handleSendSmsCode } from 'sc-business-lodash'

// 获取图形验证码（sei 模式返回 blob）
const res = await handleGetSmsCodeImage({ width: 120, height: 40 })

// 发送短信验证码
await handleSendSmsCode({ mobile: '138xxxx0000' })

---

四、字典

import { createDict, getDictLabel } from 'sc-business-lodash'

// 加载字典（isSei=true 时自动走 sei 接口）
const dicts = await createDict(['APP_TYPE', 'sys_state'])
// dicts => { APP_TYPE: [{value, label},...], sys_state: [...] }

// 翻译字典值
const label = getDictLabel(dicts.APP_TYPE, 'web')
// => '网页应用'

// 多值翻译
const label = getDictLabel(dicts.APP_TYPE, ['web', 'app'], { joint: '/' })
// => '网页应用/移动应用'

---

五、sei-base 数据源

createSeiRequest 封装了 sei-base 的增删改查，适用于对接 /sei/data/public/query 和 /sei/data/public/save 接口。

import { createSeiRequest } from 'sc-business-lodash'
import type { SeiDataSource } from 'sc-business-lodash'

const seiDs: SeiDataSource = {
  head: { table: 'sys_user' },

  // 字典翻译（随查询请求一起发给后端）
  dict: { status: 'sys_state' },

  query: {
    fields: 'id,name,status,createTime',
    filter: { field: 'del_flag', op: '=', value: 0 },
    order: 'createTime desc',
  },

  option: {
    keyField: 'id',   // 主键字段，默认 'id'
  },

  save: {
    noSaveFields: ['createTime', 'updateTime'],
  },
}

const request = createSeiRequest(seiDs)

// 查询列表
const { rows, total } = await request.getList({ page: 1, size: 20 })

// 带额外过滤条件查询
const { rows } = await request.getList(
  { page: 1, size: 20 },
  { field: 'status', op: '=', value: 1 }
)

// 按主键查单条
const row = await request.getForm({ id: '123' })

// 新增
await request.add({ name: '张三', status: 1 })

// 编辑
await request.edit({ id: '123', name: '李四' })

// 删除
await request.delete({ id: '123' })

SeiDataSource 配置项

字段	类型	说明
head	object	必填，表/视图标识，如 { table: 'xxx' } 或 { view: 'xxx' }
dict	object	字典翻译配置，随查询请求发给后端
query.filter	any | any[]	固定过滤条件
query.order	string	排序，如 'createTime desc'
query.fields	string	查询字段，逗号分隔
option.keyField	string | true	主键字段名，true 时由服务端返回
save.noSaveFields	string | string[]	不参与保存的字段
save.alwaysSaveFields	string[]	强制保存的字段（无论是否变更）
webEvn.beforeQueryEvn	Function	查询前钩子，返回 false 可阻止请求
webEvn.afterQueryEvn	Function	查询后钩子

---

六、缓存管理

import { setLocalStorage, getLocalStorage, clearLocalStorage } from 'sc-business-lodash'

setLocalStorage('key', { name: '张三' })
const data = getLocalStorage('key')
clearLocalStorage('key')

---

七、消息提示

import { SuccessToast, ErrorToast, WarningToast, StartLoading, EndLoading } from 'sc-business-lodash'

SuccessToast('保存成功')
ErrorToast('请求失败')
WarningToast('请注意')

const loading = StartLoading('加载中...')
EndLoading(loading)

---

八、开发与发布

# 安装依赖
pnpm install

# 开发模式（监听文件变化自动构建）
pnpm run debug

# 构建
pnpm run build

# 构建并发布
pnpm run build:publish