shrimp-admin/README.md

shrimp-admin

Shrimp 框架前端 —— 一种经典解决方案(不是框架本身),消费 shrimp-server 暴露的 ShrimpServer 路由契约 + ShrimpTable 数据形状契约,基于 Vue 3 + Element Plus 实现一套可直接用的后台壳。

如果你想换 UI 库或者换前端技术栈,直接照 shrimp-server 的约定再写一份就行,不依赖本包。

shrimp-admin 是源码 ship(.ts + .vue 直接发),不带构建产物,由消费侧 Vite 编译。这省掉了框架的构建步骤,代价是有几件事 npm 装完不会自动生效,必须消费侧显式配 —— 下面的接入模板已经把它们全写进去了。

---

接入模板

整段抄,不要自己攒。 标了「⚠️ 不能删」的行看起来多余,删掉的后果写在每行旁边; 现存的 theseus-admin / hand-admin / bug-book 三个项目里,这些行一行不差全都在。

1. package.json

{
    "type": "module",
    "scripts": { "dev": "vite", "build": "vite build" },
    "dependencies": {
        "shrimp-admin": "git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.8.4",

        // ⚠️ 不能删 —— 下面 7 个是 shrimp-admin 的 peerDependencies,
        // 必须由消费侧显式装进自己的 dependencies,不能指望 npm 提升碰巧能 import 到
        "vue": "^3.5.0",
        "vue-router": "^4.5.0",
        "vue-i18n": "^9.14.0",
        "axios": "^1.7.0",
        "element-plus": "^2.10.0",
        "@element-plus/icons-vue": "^2.3.0",
        "xlsx": "^0.18.5"          // ⚠️ 不能删 —— ShrimpTable 的导入/导出按钮直接 import 它,少了 vite 起不来
    },
    "devDependencies": {
        "@vitejs/plugin-vue": "^5.2.0",
        "sass-embedded": "^1.80.0",     // ⚠️ 不能删 —— shrimp-admin/style 是 .scss
        "typescript": "^5.6.0",
        "vite": "^6.0.0"
    }
}

服务端那侧另有一条硬约束:shrimp-server 要求 Express 5(它的兜底路由用了 /*path 具名通配,Express 4 只会当字面路径)。装成 4 的症状是能登录、能出菜单,但所有 POST /<moduleKey>/list 都 404。

2. vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
    plugins: [vue()],
    optimizeDeps: {
        // ⚠️ 不能删 —— 删了整页白屏,报 resolveVue: components/layout.vue not found in sources
        exclude: ['shrimp-admin'],
        // ⚠️ 也不能删 —— 上面这行让 vite 的依赖扫描停在本包门口,看不见本包 import 的
        // element-plus / xlsx。消费侧 src/ 下如果没有自己的业务 .vue 顺手 import 到它们,
        // 它们就一次都没被预打包,内部的 CJS 依赖(dayjs)原样送进浏览器 → 整页白屏,
        // 控制台只有一行 does not provide an export named 'default'。列的就是下面那份 peer 清单
        include: ['vue', 'vue-router', 'vue-i18n', 'axios', 'element-plus', '@element-plus/icons-vue', 'xlsx'],
    },
    resolve: {
        // ⚠️ 不能删 —— 删了 element-plus 与 shrimp-admin 各带一份 vue/dayjs,互操作错位
        dedupe: ['vue', 'vue-i18n', 'vue-router', 'element-plus', 'dayjs'],
    },
    server: {
        // 开发期后台接口由 vite 转发,前端一律走相对路径,不注入任何后端地址
        proxy: { '/admin-api': { target: 'http://127.0.0.1:8080', changeOrigin: true } },
    },
})

3. src/main.ts

import { createApp } from 'vue'

// ⚠️ 不能删,且必须在 shrimp-admin/style 之前 ——
// 删了页面能出来但整个掉样式,最显眼的症状是图标被撑到巨大
import 'element-plus/dist/index.css'
import 'element-plus/theme-chalk/display.css'
import 'shrimp-admin/style'

import { createShrimpAdmin, App } from 'shrimp-admin'
import zhCn from './locales/zh-cn.json'
import en from './locales/en.json'

const app = createApp(App)
app.use(createShrimpAdmin({
    config: {
        API_URL: '/admin-api',   // 相对路径,由 vite proxy 转发
        TIMEOUT: 10000,
    },
    locales: { 'zh-cn': zhCn, en },
    // ⚠️ import.meta.glob 必须写在消费侧的文件里(vite 静态扫描相对本文件),
    // 不能封装成函数从别处调
    sources: import.meta.glob('./shrimp/**/*.vue'),
}))
app.mount('#app')

4. 业务模块:默认什么都不用写

后端声明了几个 moduleKey,前端就自动有几个菜单、几张表 —— 字段、筛选、可用操作全在 moduleInfo 里,内置的 module/_default.vue 拿 moduleKey 渲染出来就是了。不需要为每个模块建文件。

只在有真实增量时才写 src/shrimp/module/<key>.vue 覆盖它(加列插槽、换布局、塞额外操作):

<!-- src/shrimp/module/product.vue —— 后端 moduleKey === 'product' -->
<template>
    <ShrimpTable moduleKey="product">
        <template #column-price="{ row }">
            <span :class="row.price > 1000 ? 'is-expensive' : ''">￥{{ row.price }}</span>
        </template>
    </ShrimpTable>
</template>

<script setup lang="ts">
// 字段、筛选、编辑仍由后端 moduleInfo 声明,这里只加自己那点增量
import { ShrimpTable } from 'shrimp-admin'
</script>

内置的 login.vue / layout.vue / 404.vue 同理,一个都不用写(见下面「唯一约定」)。

---

出错对照表

接入时按症状反查,不必先懂原理。

你看到的	病因	改哪
resolveVue: components/layout.vue not found in sources,整页白屏	shrimp-admin 被 vite 预打包了	vite.config optimizeDeps.exclude: ['shrimp-admin']
Failed to resolve import "xlsx",vite 起不来	少装 peerDependency xlsx	npm i xlsx,模板第 1 节
页面出来了但没样式,图标巨大	没引 element-plus 基础样式	main.ts 加两行 css,模板第 3 节
编辑器报 找不到 'shrimp-admin/style' 的副作用导入的模块或类型声明	本包低于 v0.8.6:./style 导出没有 types 条件,开了 noUncheckedSideEffectImports 的项目解不出类型	升到 v0.8.6
能登录、菜单也有,但所有列表都 404	服务端装的是 Express 4	服务端升到 express@^5
does not provide an export named 'default'(dayjs),整页白屏	element-plus 从没被预打包过,它的 CJS 依赖被原样送进浏览器	vite.config optimizeDeps.include,模板第 2 节
does not provide an export named 'default'(其他包)	依赖被装了两份	vite.config resolve.dedupe,模板第 2 节

验收: 必须在浏览器里打开页面

vite build 通过、curl 打接口通,都不算接入完成。上表前三行全部逃得过构建和接口测试:

• dev 用 esbuild 预打包、build 用 rollup,是两套转换管线。rollup 正确处理 node_modules 里的 import.meta.glob,所以第 1 行的问题在 vite build 下一路绿灯,只在 dev 复现。
• 样式和路由注册只在浏览器运行时才成立,接口测试根本不经过它们。

那几行为什么不能删

optimizeDeps.exclude: ['shrimp-admin']

Vite dev 默认用 esbuild 把 node_modules 里的裸导入预打包成 node_modules/.vite/deps/shrimp-admin.js。两个后果:

• 框架的内置组件表靠 import.meta.glob('./{components,module}/**/*.vue') 收集,这是 Vite 编译期宏,esbuild 不认识,会原样抄进产物;等它在 .vite/deps/ 目录下才被展开时,那个目录里一个 .vue 都没有 → 内置表变成空对象 {} → 内置兜底全部落空。
• 预打包等于复制出第二份模块实例,vueAdmin 单例会分裂成两个,消费侧拿到的和框架内部用的不是同一个。

optimizeDeps.include: [...]

上面那条 exclude 的代价:vite 的依赖扫描从 index.html 顺着消费侧的源码走,走到 shrimp-admin 就停了 —— 被 exclude 的包不进扫描,所以框架 import 了什么,vite 一无所知。

以前这不出事:消费侧总要写几个业务模块 .vue,里面顺手 import { ElMessage } from 'element-plus',扫描器照样摸得到。而从 v0.8.4 起模块壳可以一个都不写(见「业务模块」一节),于是完全可能出现消费侧 src/ 里没有任何一处 import element-plus —— 它整包从未被预打包,所有 element-plus/es/** 被原样送给浏览器,其中的 import dayjs from 'dayjs' 指向一个 CJS 文件,当场炸:

The requested module '/node_modules/dayjs/dayjs.min.js' does not provide an export named 'default'

整页白屏,控制台就这一行,vite build(rollup)一路绿灯。

不要顺着报错一个个补 dayjs、dayjs/plugin/customParseFormat…… 那是在追症状,换个 element-plus 版本要重列一遍。也不要用 optimizeDeps.entries 指向 node_modules/shrimp-admin/src/** —— 扫描器不认 node_modules 里的入口 glob,实测加了等于没加(.vite/deps/_metadata.json 里仍然只有 vue)。

正确的做法是把本包用到的运行时依赖点名列出,那份清单就是下面 peerDependencies 本身 —— 消费侧本来就得装它们,这里只是再说一句「请预打包」。

element-plus 的两行 css

shrimp-admin/style 只包含框架自己的覆盖样式与暗色变量(fix.scss / dark.scss 等),不含 element-plus 本体的样式表。element-plus 是 peerDependency、由消费侧安装,它的基础样式自然也该由消费侧引 —— 框架替你引会锁死版本、也挡住你换主题。顺序不能反:覆盖必须在基础之后。

xlsx

ShrimpTable 的导入/导出按钮是静态 import * as XLSX from 'xlsx',不是按需加载 —— 就算你的后台从不点那两个按钮,模块解析也绕不过去。它是 peerDependency 而不是 dependency,理由和 element-plus 一样:版本该由消费侧定。

唯一约定: sources 路径后缀覆盖

消费侧把所有要交给框架的 .vue 通过单个 sources 入口注入(import.meta.glob 必须由消费侧自己调用,vite 静态扫描相对调用文件)。框架按文件路径后缀匹配,同后缀消费侧优先,内置兜底。

项目/
└── src/shrimp/                       消费侧目录,可任意命名
    ├── components/
    │   ├── login.vue                 覆盖框架内置 login 页
    │   ├── layout.vue                覆盖整体布局壳
    │   └── fields/
    │       └── FieldRelativeTime.vue 注册字段类型 relativeTime
    └── module/
        ├── product.vue               覆盖业务模块 product 的默认表格
        ├── _default.vue              覆盖「所有没单独写壳的模块」用的那份
        └── user/
            └── orders.vue            子模块,parent=user

module/ 下一个文件都没有也能跑 —— 那时每个模块都落到内置的 module/_default.vue。

覆盖颗粒度只在这几个入口

框架内 .vue 之间的 peer 引用是硬编码静态 import,override 颗粒度就停在下面这几类入口,不会一路传递下去:

入口	后缀	说明
router targets	components/login.vue、components/layout.vue、components/404.vue	vue-router 三个根级路由组件
module routes	module/<key>.vue、module/<parent>/<sub>.vue、module/_default.vue	走 registerRoute 的业务模块/子模块;都没写就用内置 _default
field registry	components/fields/Field<X>.vue	字段类型注册表(文件名首字母小写 = type 键)
顶栏	components/userbar.vue	右上角那一条(语言、全屏、用户菜单),整体替换

表里没有的路径不会被覆盖,而且不报错——写了个 components/topbar.vue 放进 sources,框架照样用内置那份,页面正常打开、你的文件被静默忽略。想换更细的部件就在消费侧的 layout.vue 里自己组装,框架不代理 peer 切换。

字段类型注册

components/fields/Field<X>.vue 自动注册类型 <x>(首字母小写):

文件	type 注册键
FieldString.vue	string
FieldRelativeTime.vue	relativeTime
你自己的 FieldMyType.vue	myType

后端 moduleInfo 里 field.type === 'myType' 时就用你这个组件。

内置类型以 src/components/fields/ 目录为准,当前是: array / boolean / date / number / object / password / relation / relativeTime / select / string / tab / textarea。其中 relativeTime 是本实现独有的,shrimp-server 的 ShrimpFieldTypes 里没有。

没有 json。 后端发一个没注册的 type 过来不会报错,getFieldComponent 静默回落成 string 渲染,只在控制台留一条 warning——列照样出、内容不对。字符串数组要用 array + item,嵌套对象用 object + fields。

业务模块

module/<key>.vue 命中 moduleKey === '<key>' 的路由,自动作为内容页。子表用嵌套目录(module/<parent>/<sub>.vue)。没写的模块落到 module/_default.vue,消费侧写一份同名文件即可整体换掉那个默认。

例子: 覆盖 login 页

<!-- src/shrimp/components/login.vue -->
<template>
    <div class="custom-login">
        <h2>{{ vueAdmin.adminConfig.title || 'Admin' }}</h2>
        <el-form :model="form" :rules="rules" @keyup.enter="login">
            <el-form-item prop="user">
                <el-input v-model="form.user" :placeholder="$t('login.userPlaceholder')" />
            </el-form-item>
            <el-form-item prop="password">
                <el-input v-model="form.password" :placeholder="$t('login.PWPlaceholder')" show-password />
            </el-form-item>
            <el-button type="primary" :loading="info.islogin" @click="login">
                {{ $t('login.signIn') }}
            </el-button>
        </el-form>
    </div>
</template>

<script lang="ts" setup>
import { reactive, computed } from 'vue'
import { useI18n } from 'vue-i18n'
import { vueAdmin } from 'shrimp-admin'

const { t } = useI18n()
const info = reactive({ islogin: false })
const form = reactive({ user: '', password: '' })
const rules = computed(() => ({
    user: [{ required: true, message: t('login.userError'), trigger: 'blur' }],
    password: [{ required: true, message: t('login.PWError'), trigger: 'blur' }],
}))

function login() {
    info.islogin = true
    vueAdmin.fetchLogin({ username: form.user, password: form.password })
        .then(async (data: any) => {
            vueAdmin.token = data.token
            await vueAdmin.loadUserInfo()
            vueAdmin.router.push(vueAdmin.getFirstMenuPath())
        })
        .catch((e: any) => console.warn('[Login]', e.message))
        .finally(() => { info.islogin = false })
}
</script>

只要文件落在 src/shrimp/components/login.vue,被 sources 的 glob 扫到,框架的 /login 路由就会用你这份替换内置版本。

消费的契约

参见 shrimp-server README ## 约定 章节。本包消费以下条件契约:

• ShrimpTable: list 响应 {list,total,page,pageSize,totalPages} / 字段 type 枚举 / populate ${key}_label
• ShrimpServer: HTTP 路由 / JWT Bearer / IUserAccessor 返回的 powers