mirror of
https://github.com/ialley-workshop-open/uni-halo.git
synced 2026-09-12 16:40:40 +08:00
小莫唐尼
65 lines
3.5 KiB
Markdown
65 lines
3.5 KiB
Markdown
# 架构规范
|
|
|
|
## 1. 事实源与生成物(唯一事实源与投影)
|
|
|
|
配置的**事实源**是根目录的 `*.config.ts`,构建时投影为 JSON/d.ts。改投影不改源 = 改动丢失。
|
|
|
|
| 事实源(手改这里) | 生成物(禁止手改) | 生成者 |
|
|
|------------------|------------------|--------|
|
|
| `pages.config.ts` | `src/pages.json` | vite-plugin-uni-pages |
|
|
| `manifest.config.ts` | `src/manifest.json` | vite-plugin-uni-manifest |
|
|
| `src/tabbar/config.ts` | pages.json 的 tabBar 段 | 引入 pages.config.ts |
|
|
| 组件目录 `src/components/**` | `src/types/components.d.ts` | vite-plugin-uni-components |
|
|
| `src/pages/**` + `definePage` 宏 | `src/types/uni-pages.d.ts` | vite-plugin-uni-pages |
|
|
| `src/hooks/**`、vue/uni-app API | `src/types/auto-import.d.ts` | unplugin-auto-import |
|
|
|
|
页面路由配置只写在页面内的 `definePage` 宏里,不写进 pages.config.ts 的页面列表。
|
|
|
|
## 2. 平台接缝
|
|
|
|
- **条件编译是唯一的平台分支手段**(编译期能确定的场景):JS 用 `// #ifdef` / `// #endif`,模板用 `<!-- #ifdef -->` / `<!-- #endif -->`
|
|
- 运行时判断平台用 `uni.getSystemInfoSync().uniPlatform` 等 API,只用于编译期无法确定的场景
|
|
- 仅 H5 生效的行为(如 devServer 代理 `VITE_APP_PROXY_*`、eruda 调试面板)不需要写条件编译,其他端构建时天然剔除
|
|
- 小程序端 dev 也是 `build` command(无 devServer),不要在非 H5 端假设热更新代理可用
|
|
|
|
## 3. 校验只在真边界
|
|
|
|
以下边界的数据**不可信**,必须校验后才进业务层:
|
|
|
|
| 真边界 | 校验位置 |
|
|
|--------|---------|
|
|
| HTTP 响应 | `src/http` / alova 拦截器统一做,业务层不重复判空 |
|
|
| `uni.getStorageSync` 读出的数据 | 读取处判类型/结构 |
|
|
| URL 参数(onLoad options) | 页面入口处校验 |
|
|
| postMessage / 第三方 SDK 回调 | 回调入口处校验 |
|
|
|
|
组件 props、store 内部传递信任 TS 类型,**不**重复运行时校验。
|
|
|
|
## 4. 目录分层与职责
|
|
|
|
```
|
|
src/
|
|
├── pages/ # 页面(约定式路由,文件即路径;分包页面不放这里)
|
|
├── pages-demo/ # 分包目录(subPackages 配置,分包不能是 src/pages 的子目录)
|
|
├── components/ # 全局组件(fg- 前缀,easycom 自动注册)
|
|
├── layouts/ # 布局
|
|
├── api/ # API 接口定义
|
|
├── http/ # 请求封装(uni.request 为主;alova 为可选并行链路,拦截器中默认注释)
|
|
├── store/ # Pinia store(持久化用 pinia-plugin-persistedstate)
|
|
├── hooks/ # 组合式函数(auto-import,免 import)
|
|
├── tabbar/ # 底部导航(config.ts 为唯一配置源)
|
|
├── static/ # 静态资源(@img 别名指向 images 子目录)
|
|
├── service/ # openapi 生成目录(`pnpm openapi`,eslint 忽略,勿手改)
|
|
└── types/ # 类型声明(大部分为生成物,见第 1 节)
|
|
```
|
|
|
|
- 别名:`@` → `src/`;`@img` → `src/static/images`(vite 与 tsconfig 已对齐)
|
|
- 请求一律走 `src/http` 封装,业务代码不直接调 `uni.request`
|
|
- 服务端状态以接口为事实源,store 只放需要跨页共享/持久化的状态;凡不能从 store 重建的 UI 状态都是刷新后丢失的隐患
|
|
|
|
## 5. 环境变量
|
|
|
|
- env 文件统一在 `env/` 目录(vite.config.ts 的 `envDir`),不在项目根
|
|
- 变更部署相关变量(端口 `VITE_APP_PORT`、接口地址 `VITE_SERVER_BASEURL`、代理开关 `VITE_APP_PROXY_*` 等)改 env 文件,不在代码里硬编码
|
|
- `VITE_DELETE_CONSOLE=true` 时构建移除 console/debugger,提交前不需要手工删
|