0.8.0: 契约副本刷齐并改为自动同步;未注册字段类型不再静默回落
契约副本(src/IShrimpType.ts)此前漂了一整代:停在旧的 json 类型, 缺 object / array / IFieldConfig.fields / IFieldConfig.item / parse / IPageResult.refs。 而本包自己的组件早就在读这些字段——FieldArray 读 field.item、FieldObject 读 fields、 FieldRelation 与 ShrimpTable 读 refs。等于组件在用、类型说没有。 接入方照这份副本理解 shrimp 能渲染什么,只会得出"结构化数据只有 json"的结论。 现在由 shrimp-server 的 postbuild 单向覆盖过来(它是契约真身), 本仓库另提供 npm run check:contract / sync:contract 手动比对与同步。 注释头不参与同步,它声明的是"我是副本",与契约正文是两回事。 VueAdmin.getFieldComponent:未注册类型仍回落成 string(类型词汇表是开放的, 消费侧放个 Field<X>.vue 就能扩,改成严格校验会当场打死 theseus 的 gesture/goodsList 和 hand 的 dropList/matterPointDropList),但按类型去重告警一次, 打印出现位置、已注册类型和两条修法。上面那个 json 就是这么静默活下来的。 resolveVue:内置组件表为空时报"本包没被 vite 正常转换、消费侧缺 optimizeDeps.exclude", 不再报"找不到 layout.vue"把人引去查文件路径。 README 重写成可照抄的接入模板 + 出错对照表 + "那几行为什么不能删"。 版本与 shrimp-server 归一到 0.8.0,删掉 @syncedFrom 这条手维护的版本标记。
This commit is contained in:
@@ -4,37 +4,153 @@ Shrimp 框架前端 —— 一种**经典解决方案**(不是框架本身),消
|
||||
|
||||
如果你想换 UI 库或者换前端技术栈,直接照 shrimp-server 的约定再写一份就行,不依赖本包。
|
||||
|
||||
## 安装
|
||||
shrimp-admin 是**源码 ship**(.ts + .vue 直接发),不带构建产物,由消费侧 Vite 编译。这省掉了框架的构建步骤,代价是**有几件事 npm 装完不会自动生效**,必须消费侧显式配 —— 下面的接入模板已经把它们全写进去了。
|
||||
|
||||
```bash
|
||||
npm i git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.3.0
|
||||
---
|
||||
|
||||
# 接入模板
|
||||
|
||||
> **整段抄,不要自己攒。** 标了「⚠️ 不能删」的行看起来多余,删掉的后果写在每行旁边;
|
||||
> 现存的 theseus-admin / hand-admin / bug-book 三个项目里,这些行一行不差全都在。
|
||||
|
||||
## 1. package.json
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"type": "module",
|
||||
"scripts": { "dev": "vite", "build": "vite build" },
|
||||
"dependencies": {
|
||||
"shrimp-admin": "git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.7.10",
|
||||
|
||||
// ⚠️ 不能删 —— 下面 6 个是 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"
|
||||
},
|
||||
"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-admin 是**源码 ship**(.ts + .vue 直接发),由消费侧 Vite 编译。
|
||||
服务端那侧另有一条硬约束:**shrimp-server 要求 Express 5**(它的兜底路由用了 `/*path` 具名通配,Express 4 只会当字面路径)。装成 4 的症状是能登录、能出菜单,但**所有** `POST /<moduleKey>/list` 都 404。
|
||||
|
||||
## 使用
|
||||
## 2. vite.config.ts
|
||||
|
||||
```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'],
|
||||
},
|
||||
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
|
||||
|
||||
```ts
|
||||
// main.ts
|
||||
import { createApp } from 'vue'
|
||||
import { createShrimpAdmin, App } from 'shrimp-admin'
|
||||
|
||||
// ⚠️ 不能删,且必须在 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',
|
||||
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')
|
||||
```
|
||||
|
||||
## 唯一约定: `sources` 路径后缀覆盖
|
||||
## 4. 每个业务模块一个薄壳 `src/shrimp/module/<key>.vue`
|
||||
|
||||
⚠️ **不能省。**后端有几个 moduleKey,这里就得有几个文件 —— 这**不是「覆盖」,是「注册」**:框架的内置兜底只兜自己的 login/layout/404,不认识你的业务模块,少一个那个菜单就点不开。
|
||||
|
||||
```vue
|
||||
<!-- src/shrimp/module/product.vue —— 后端 moduleKey === 'product' -->
|
||||
<template>
|
||||
<ShrimpTable moduleKey="product" />
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
// 字段、筛选、编辑全由后端 moduleInfo 声明,ShrimpTable 自动渲染,这里不写业务代码
|
||||
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']` |
|
||||
| `module component not found: module/<key>.vue`,菜单点不开 | 少了业务模块薄壳 | 补 `src/shrimp/module/<key>.vue`,模板第 4 节 |
|
||||
| 页面出来了但没样式,**图标巨大** | 没引 element-plus 基础样式 | main.ts 加两行 css,模板第 3 节 |
|
||||
| 能登录、菜单也有,但**所有列表都 404** | 服务端装的是 Express 4 | 服务端升到 `express@^5` |
|
||||
| `does not provide an export named 'default'`(dayjs / element-plus) | 依赖被装了两份 | 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` 单例会分裂成两个,消费侧拿到的和框架内部用的不是同一个。
|
||||
|
||||
## element-plus 的两行 css
|
||||
|
||||
`shrimp-admin/style` 只包含框架自己的覆盖样式与暗色变量(`fix.scss` / `dark.scss` 等),**不含** element-plus 本体的样式表。element-plus 是 peerDependency、由消费侧安装,它的基础样式自然也该由消费侧引 —— 框架替你引会锁死版本、也挡住你换主题。顺序不能反:覆盖必须在基础之后。
|
||||
|
||||
## 业务模块薄壳
|
||||
|
||||
框架靠 `sources` 里扫到的 `module/<key>.vue` 去 `registerRoute`。它没有别的途径知道你有哪些业务模块 —— 后端 moduleInfo 只告诉它「有个 key 叫 product」,渲染成哪个组件得你指定。壳里只有一行 `<ShrimpTable>`,但这一行就是那次指定。
|
||||
|
||||
# 唯一约定: `sources` 路径后缀覆盖
|
||||
|
||||
消费侧把所有要交给框架的 .vue 通过单个 `sources` 入口注入(`import.meta.glob` 必须由消费侧自己调用,vite 静态扫描相对调用文件)。框架按**文件路径后缀**匹配,同后缀消费侧优先,内置兜底。
|
||||
|
||||
@@ -130,7 +246,7 @@ function login() {
|
||||
|
||||
只要文件落在 `src/shrimp/components/login.vue`,被 `sources` 的 glob 扫到,框架的 `/login` 路由就会用你这份替换内置版本。
|
||||
|
||||
## 消费的契约
|
||||
# 消费的契约
|
||||
|
||||
参见 shrimp-server README `## 约定` 章节。本包消费以下条件契约:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user