更新记录
1.0.0(2026-11-19) 下载此版本
工程架构从零搭建至首个稳定形态:对标 vue-admin-template 分层思想,以 uni-app x 技术栈 + 梦曦插件系(ux-router / ux-pinia / mx-request / ux-storage / ux-utils)完整落地,Web 端全链路验证通过。
平台兼容性
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | × | × | √ |
unix-architecture 使用说明
面向:第一次接手本模板的开发者,以及按本模板写代码的 AI 助手。 版本:1.1.0(
manifest.jsonversionName 1.1.0 / versionCode 110) 本文所有写法均取自仓库现有代码,示例可直接复制运行。
1. 这是什么
一套 uni-app x 工程架构模板:把 api / stores / router / utils / pages 五层拆开,每层职责单一、依赖单向,全局装配只在 main.uts 一处发生。底层由梦曦插件系承载:
| 插件 | 版本 | 在本项目中的角色 |
|---|---|---|
ux-router |
0.8.2 | 命名路由 + 全局守卫链 + 导航拦截 |
ux-pinia |
0.2.0 | class 式状态管理(免挂载) |
mx-request |
0.1.0 | 网络请求、拦截器、取消、错误分类 |
ux-storage |
0.1.0 | 异步持久化(token 落盘) |
ux-utils |
0.2.0 | toast / modal 全端一致封装 |
m-ui-x |
0.1.0 | 11 个基础 UI 组件(easycom 免注册) |
适用:需要登录鉴权的多端应用起步工程、需要一套「AI 也不会写歪」的强制分层规范。 不适用:纯静态展示页(这套分层对单页项目偏重)。
2. 环境要求
- HBuilderX 5.34+(uni-app x 编译器随 HBuilderX 分发,不单独安装)
- Node.js(仅在需要本地跑
vite/ 文档站时用到) - Git
⚠️ 仓库根
README.md开头写的是「HBuilderX 5.26」,而docs/src/guide/getting-started.md、faq.md与CHANGELOG的实测结论都是 5.34。以 5.34 为准——1.1.0 的多项修复(get<string>显式泛型、guardRoute(null, null))就是 5.34 编译器的要求。
3. 五分钟跑起来
3.1 导入工程
HBuilderX → 文件 → 导入 → 从本地目录导入,选中工程根目录。不要只导入 pages/ 子目录,main.uts、uni_modules/、vite.config.ts 都在根上。
3.2 改后端地址(唯一一处)
config/index.uts:
export const settings: AppSettings = {
appName: 'unix-architecture',
baseURL: 'http://127.0.0.1:3210', // ← 只改这一行
timeout: 15000
}
3.3 没有后端时先起 mock
模板约定三个接口,任意 mock 服务(或自己写 20 行 Node)满足即可:
| 接口 | 方法 | 请求 | 响应 |
|---|---|---|---|
/user/login |
POST | { username, password } |
{ token } |
/user/info |
GET | Authorization: Bearer <token> |
{ name, avatar },无 token 返回 401 |
/user/logout |
POST | — | 任意 |
CORS 需放行 Authorization 请求头,否则 Web 端登录后拉用户信息会 401。
3.4 运行
HBuilderX 内直接「运行 → 运行到浏览器」。命令行方式(路径按本机 HBuilderX 安装位置调整):
# Windows
D:\HBuilderX\cli.exe launch web --project <项目绝对路径>
D:\HBuilderX\cli.exe logcat web --project <项目绝对路径> --mode lastBuild
# macOS / Linux
/Applications/HBuilderX.app/Contents/MacOS/cli launch web --project <项目绝对路径>
3.5 自测登录闭环(30 秒验收)
- 冷启动访问首页 → 无 token,自动跳到
/pages/login/login; - 登录页已预填
admin / 123456,点「登录」→ 回首页并显示「欢迎,xxx」; - 首页点「退出登录」→ 确认弹窗 → 回登录页。
三步走通,说明网络层(Bearer 注入)→ 状态层(class store)→ 路由层(守卫链)→ UI 层(m-button/loading) 全链路正常。任何一步卡住,直接查第 12 节排错表。
4. 目录地图
├── main.uts # 唯一装配点:app.use(router) + initRequest() + setupPermission()
├── App.uvue # 应用生命周期(Android 双击返回退出)
├── pages.json # 页面静态注册(新增页面要在这里加一行)
├── manifest.json # 应用信息;vapor: true / styleIsolationVersion: 2
├── vite.config.ts # routeGen 插件:生成路由表与 d.ts
├── platformConfig.json # 当前仅 APP-ANDROID
│
├── api/ # 接口层
│ ├── types.uts # DTO 唯一事实源(LoginResult / UserInfo)
│ └── user.uts # login / getInfo / logout
├── stores/ # 状态层
│ ├── index.uts # useXxxStore 统一出口
│ ├── types.uts # 转发 store class 类型
│ └── modules/user.uts # UserStore class
├── composables/ # 组合式函数
│ ├── useLoading.uts
│ └── types.uts # LoadingState
├── components/AppLogo/ # 自有组件(easycom)
├── router/
│ ├── index.uts # createRouter
│ ├── permission.uts # 白名单 + token + getInfo + 重定向
│ └── routes.gen.uts # ⚠ 自动生成,勿手改
├── utils/
│ ├── request.uts # initRequest:全局配置 + 双拦截器
│ └── auth.uts # token 内存缓存 + 异步落盘
├── config/index.uts # 全局唯一配置源
├── pages/index|login/ # 页面
├── types/ # 插件生成的 d.ts
├── uni_modules/ # 6 个插件
├── docs/ # VitePress 文档站
└── .trae/ # AI 规则 / 技能 / 任务文档(随仓库分发时可能被裁剪)
分层职责与禁令
| 层 | 只做 | 绝对不做 |
|---|---|---|
pages/ |
组装 UI、调 store / composable | 直接 uni.request、碰裸 JSON、写全局副作用 |
composables/ |
横切 UI 状态(loading 等) | 承载业务数据 |
stores/ |
业务状态 + 动作 | 引用组件、写请求细节 |
api/ |
请求转发、路径收敛、DTO 还原 | 写业务判断、弹 toast |
utils/ |
全局能力(request / auth) | 依赖页面或 store |
config/ |
常量与配置 | 任何运行时逻辑 |
5. 核心调用链
页面(.uvue)
→ composables/useXxx 横切 UI 状态(loading / 表单校验态)
→ stores/modules/* 业务状态与动作
→ api/<domain>.uts DTO 还原(JSON.parse<T>)
→ utils/request.uts 拦截器:Bearer 注入 + 统一错误 toast
→ mx-request → uni.request
记住一条就够:从上往下调用,绝不反向。页面不认识 mx-request,store 不认识组件。
6. 五个高频开发动作
6.1 新增一个业务页面(三个动作缺一不可)
# ① 建文件
pages/order/order.uvue
// ② pages.json 里注册(路由表由 vite 插件生成,pages.json 不会自动写)
{
"path": "pages/order/order",
"style": { "navigationBarTitleText": "订单" }
}
<!-- ③ 页内声明编译宏 -->
<script setup lang="uts">
defineUniPage({
name: 'order', // 生成到 router/routes.gen.uts 的 name
title: '订单'
})
</script>
新页面默认需要登录(白名单制)。免登录页面去
router/permission.uts的whiteList里加路径。
6.2 新增一个接口
第一步永远是 DTO——写到 api/types.uts 同一个文件里(不要建 api/types/ 子目录,见 9.1):
// api/types.uts 追加
export type OrderItem = {
id: string
amount: number
}
// api/order.uts 新建
import { request } from '@/uni_modules/mx-request'
import type { OrderItem } from './types.uts'
export function getOrderList(): Promise<OrderItem[]> {
return request<UTSJSONObject>({
url: '/order/list',
method: 'GET'
}).then((res): OrderItem[] => {
const dto = JSON.parse<OrderItem[]>(JSON.stringify(res.data))
if (dto == null) {
throw new Error('[api] getOrderList 响应解析失败')
}
return dto
})
}
三个要点:request<UTSJSONObject> 只做静态标注、每个调用点内联 JSON.parse<具体类型>、解析失败立即 throw。
6.3 新增一个 store 模块
// stores/modules/order.uts
import { reactive } from 'vue'
import { defineStore, PiniaStoreBase } from '@/uni_modules/ux-pinia'
import { getOrderList } from '@/api/order.uts'
import type { OrderItem } from '@/api/types.uts'
export type OrderState = {
list: OrderItem[]
total: number
}
export class OrderStore extends PiniaStoreBase {
state: OrderState = reactive<OrderState>({ list: [], total: 0 })
constructor() {
super()
this.bindState(this.state) // $patch / $reset / $subscribe 的前提,漏写必出问题
}
async loadAction(): Promise<void> {
const data = await getOrderList()
this.state.list = data
this.state.total = data.length
}
}
export const useOrderStore = defineStore<OrderStore>('order', (): OrderStore => new OrderStore())
// stores/index.uts 追加一行
export { useOrderStore } from './modules/order.uts'
// stores/types.uts 追加一行
export type { OrderStore } from './modules/order.uts'
用法:
const store = useOrderStore()
console.log(store.state.total) // 直接读写,没有 .value
await store.loadAction()
模板事件绑定 method 必须带括号:@click="store.loadAction()"。
6.4 新增一个组合式函数
// composables/useCounter.uts —— 函数直接按路径导入,无聚合出口
export function useCounter() {
const count = ref(0)
const inc = (): void => { count.value++ }
return { count, inc }
}
类型放 composables/types.uts(同样单文件收敛)。useLoading 的 run 只接收 () => Promise<void>——需要带返回值的加载态,另写 useTask<T>,不要给它加泛型(UTS 类型属性方法不支持泛型)。
6.5 新增一个业务组件
components/OrderCard/OrderCard.uvue
easycom 自动识别,模板里直接 <OrderCard />,无需 import / 注册。组件内只管自身样式,外边距交给调用方外层的 view。
7. 鉴权与路由
7.1 token 的读写
import { getToken, setToken, removeToken, ensureAuthReady } from '@/utils/auth.uts'
getToken() // 同步读内存缓存
setToken(token) // 内存立即生效 + ux-storage 异步落盘(失败只记日志)
removeToken() // 清内存 + 清持久层
await ensureAuthReady() // 冷启动时等持久层恢复完,再读 getToken()
不要在页面里直接读 ux-storage 存 token,也不要绕过 utils/auth.uts。
7.2 守卫流程(router/permission.uts)
await ensureAuthReady()
├─ 有 token
│ ├─ 去登录页 → 重定向首页
│ ├─ store 里已有用户名 → 放行
│ └─ 没有用户信息 → await getInfoAction()
│ ├─ 成功 → 放行
│ └─ 失败 → resetToken() + 回登录页(带 redirect)
└─ 无 token
├─ 在白名单 → 放行
└─ 其余 → 回登录页(query: redirect=原 path)
登录成功后回跳:
const route = useRoute()
const target = route.query.get('redirect') ?? '/pages/index/index'
router.relaunch(target)
7.3 路由 API
import { useRouter } from '@/uni_modules/ux-router/utssdk/index.uts'
const router = useRouter()
router.push('/pages/order/order') // 字符串路径
router.push({ name: 'order' }) // 命名路由
router.replace('/pages/login/login')
router.relaunch('/pages/index/index') // 关掉页面栈重开(登录后回跳用这个)
router.back()
- 禁止
uni.navigateTo/redirectTo/reLaunch。InterceptorPlugin会兜底拦截并转交守卫链,但不得依赖兜底。 router/index.uts已配backFallback: '/pages/index/index':深链 / 刷新直连后页面栈不足,back()会自动回首页而不是报 CANCELLED。
7.4 冷启动为什么要「补跑」
H5 直达或 deeplink 进入时,页面可能已经加载、守卫还没执行。setupPermission() 末尾用 router.isReady().then(() => router.guardRoute(null, null)) 补跑一次守卫链。那两个 null 不能省——5.34 的 Kotlin 生成器会丢弃可选参数默认值,无参调用直接编译报错。
8. 网络层
8.1 全局初始化(已在 main.uts 调好,通常不用动)
initRequest()
// = configureRequest({ baseURL, timeout, header, validateStatus: null })
// + 请求拦截器(注入 Authorization: Bearer)
// + 响应拦截器(错误码 → 中文文案 → showToast)
initRequest() 内部有 initialized 幂等标记,重复调用不会重复注册拦截器(否则错误会弹两次)。
8.2 发请求
import { request } from '@/uni_modules/mx-request'
request<UTSJSONObject>({
url: '/user/info',
method: 'GET',
params: { page: 1 } as UTSJSONObject
})
mx-request 另有 get / post / put / patch / del / head / options 七个快捷方法;需要多套配置(比如另一个 baseURL)用 createRequest 建实例;要中途取消用 createCancelSource()。
8.3 错误怎么走
| 层 | 行为 |
|---|---|
| 响应拦截器 | ERR_TIMEOUT / ERR_NETWORK / 有 statusCode → 映射中文文案并 toast;ERR_CANCELED 静默不提示;仍把错误 reject 给调用方 |
| 业务层 | .catch 里只做业务补救,不要再弹一次 toast |
错误码体系(RequestError.code):参数、配置、取消、超时、网络、4xx、5xx、原生失败 八类,原生 errCode 原值透传。
9. 状态层与类型规范
9.1 类型放哪儿(判据:类型跟着消费关系走)
| 类型性质 | 位置 | 例子 |
|---|---|---|
| 跨层共享(api → store → 页面 / 守卫) | <域>/types.uts 单文件内定义 |
LoginResult、UserInfo、LoadingState |
| store 出口形状 | modules/*.uts 的 class 声明 + stores/types.uts 转发 |
UserStore |
| 单文件私有契约 | 就近定义 | AppSettings(config)、UserState(store 模块) |
| 第三方库类型 | import type 导入,绝不复制 |
RequestConfig、Ref |
硬约束:安卓发行拷贝不追踪 export type ... from 转发链,只被类型转发引用的子文件不会进发行树,分析器会报 index not found。所以域类型必须收敛在 <域>/types.uts 单文件里,禁止建 types/ 子目录做转发。转发只允许指向运行时可达文件(如 stores/types.uts → modules/*)。
9.2 class store 的四个固定动作
export class XxxStore extends PiniaStoreBase {
state: XxxState = reactive<XxxState>({ /* 初值必填,UTS 无 undefined */ })
constructor() {
super()
this.bindState(this.state) // ① 必须
}
get total(): number { // ② 派生值用 getter,不用 computed 字段
return this.state.list.length
}
async loadAction(): Promise<void> { /* ③ action 是普通 method */ }
// ④ 跨 store 依赖在 method 里调用对方的 useXxxStore(),不要放字段初始化器
}
export const useXxxStore = defineStore<XxxStore>('xxx', () => new XxxStore())
禁 computed 字段:插件内 effectScope 跨页面失效。禁 app.use(pinia):原生端不生效,模块级注册表本身就是全局单例。
9.3 UTS 十条红线(违反即编译错误或运行时崩溃)
| # | 坑 | 正确写法 |
|---|---|---|
| 1 | 不支持 undefined |
可空用 null \| T,变量先初始化 |
| 2 | 条件语句禁 truthy/falsy | if (x > 0)、while (isValid),禁 if (arr) |
| 3 | 对象字面量只能赋给 type |
不要用 interface 承接字面量 |
| 4 | 泛型二次传递被 Kotlin 擦除 | JSON.parse<T> 逐调用点内联具体类型 |
| 5 | export * from / 值转发不可靠 |
聚合出口一律 export type { X } from |
| 6 | type 的属性方法不能带泛型 | 回调签名具体化,或把泛型提到 type 上 |
| 7 | enum 不用于跨端 | 字面量联合类型替代 |
| 8 | 函数声明不能当值传递 | 回调一律箭头函数 |
| 9 | Kotlin 数组越界抛异常 | 访问前判界 |
| 10 | 名义类型下裸对象 cast 崩溃 | 跨库对象用导出的显式类型构造(RawLocation) |
10. UI 组件库(m-ui-x)
10.1 用法:标签直接用
<m-button type="primary" block :loading="loading" loading-text="登录中…" @click="handleLogin">登录</m-button>
无需 import、无需注册(easycom 按 uni_modules/m-ui-x/components/<name>/ 识别)。
10.2 组件清单(11 个)
| 组件 | 用途 |
|---|---|
m-button |
语义色 type、plain / disabled / loading、四档尺寸、block、hairline、按压反馈 |
m-cell / m-cell-group |
单元格与分组:title / value / label、图标、四向箭头、inset 卡片 |
m-row / m-col |
栅格:gutter、对齐、换行 |
m-icon |
250+ 内置图标(ttf 随包) |
m-image |
mode 直通、占位、淡入、圆形、懒加载 |
m-text |
语义色 / 色值、三档字号、单行省略、多行截断、可选中 |
m-space |
间距:方向 / 换行 / 对齐,size 单值或行 / 列双值 |
m-loading |
circular / spinner、自定义色与尺寸、带文案 |
m-badge |
数字 / 点、max 截断、语义色、位置偏移、独立形态 |
组件完整 props 以 docs 站与 uni_modules/m-ui-x/README.md 为准;新增 UI 优先复用,不要自绘重复轮子。
10.3 主题定制
在工程根 uni.scss 里直接定义 $m-* 变量即可(变量全部带 !default,编译期叠加,零运行时开销):
$m-button-normal-height: 48px;
$m-color-primary: #2b6de5; // 变量名以 uni_modules/m-ui-x/theme/vars.scss 为准
⚠️ 禁止在 uni.scss 中 @import 插件的 vars.scss:uni.scss 会注入每个组件样式,与组件内引用同一文件会触发 sass 循环导入。
11. 样式与交互约定
- 只用 class 选择器 + flex 布局;不用
scoped;不用rpx(除随屏宽变化的场景,用px)。 - 文字样式只设在
text/button上,不要设在view上。 - toast / modal 一律用
ux-utils:
import { showToast, showModalAsync } from '@/uni_modules/ux-utils'
showToast({ title: '已保存', icon: 'none' })
showModalAsync({ title: '退出登录', content: '确定要退出当前账号吗?' }).then((res) => {
if (res.confirm) { /* ... */ }
})
用 showModalAsync 而不是 uni.showModal 回调式:它的 confirm / cancel 恒存在互斥,不用处理两套分支。禁止 uni.showToast / uni.showModal。
- 其它业务数据持久化用
ux-storage的set/get/remove,key 带业务前缀(order:draft);禁止uni.setStorageSync系。
12. 排错速查
| 现象 | 原因 / 处理 |
|---|---|
| 冷启动没跳登录页,停在首页 | 守卫未执行或 setupPermission() 没在 main.uts 调;确认 router.guardRoute(null, null) 存在 |
新页面不参与守卫、useRouter().push 报找不到路由 |
漏了页内 defineUniPage({ name, title }) |
| 登录后拉用户信息 401 | mock 没放行 Authorization 头(CORS Access-Control-Allow-Headers);或 token 没注入 |
| Android 真机连不上 mock | 127.0.0.1 指向手机自己。改成电脑局域网 IP,mock 监听 0.0.0.0,手机同网 |
| 错误 toast 弹两次 | 某处重复调了 initRequest()(幂等标记被绕开),或业务 .catch 里又弹了一次 |
控制台 NavigationFailure |
ux-router Web 端已知日志(relaunch 后的确认),跳转结果正确,不用处理 |
redirect 参数出现 %252F |
Web 端已知双重编码,round-trip 正常;上 Android 前建议深链实测 |
store.state.x 不更新视图 |
漏 this.bindState(this.state),或用了 computed 字段(应改 getter) |
| 发行 / 云打包报错但 dev 正常 | 见 13.2 的发行四坑 |
if (arr) 编译报错 |
UTS 禁 truthy/falsy,改 arr.length > 0 |
13. 跨端与打包
13.1 现状
- Web:1.1.0 已全链路 E2E 验证(冷启动守卫、登录闭环、DTO、easycom、自绘 modal/toast)。
- Android:已过云打包 Kotlin 编译,真机业务回归仍建议自测。
platformConfig.json当前只开APP-ANDROID。 - iOS / 鸿蒙 / 小程序:底座与插件声明支持,但本模板未做实测。
13.2 发行四坑(1.1.0 已修,改代码时别踩回去)
- uts 插件入口不得导出字符串常量 —— 5.34 的 uts-proxy 会生成未加引号的非法 JS,esbuild 报
Expected a semicolon,且只在发行流水线触发。 - 域类型必须单文件收敛 —— 发行拷贝不追踪
export type ... from转发链,子目录类型文件不进发行树。 - 插件组件内避免
Animation类型标注、脚本级slots.default检查、带flush的watch—— 5.34 Kotlin 生成器解析不到符号。 - Kotlin 端泛型要显式 ——
get<string>(...)这类调用必须写泛型参数,不能靠推断。
另:manifest.json 的 appid 为空,云打包前需在 HBuilderX 里重新获取 appid。
14. 附录
14.1 启动装配(唯一,不要加第四次调用)
// main.uts
app.use(router) // ux-router:provide + 全局 mixin(onShow syncRoute)
initRequest() // mx-request:默认实例 + 双拦截器(幂等)
setupPermission() // 注册 beforeEach + 冷启动补跑
| 需求 | 唯一落点 |
|---|---|
| 网络初始化 / 拦截器 | utils/request.uts → initRequest() |
| 路由守卫 | router/permission.uts → setupPermission() |
| 全局配置 | config/index.uts |
| 应用生命周期 | App.uvue(只放生命周期,不放业务) |
14.2 自动生成的文件(人手不碰)
router/routes.gen.uts:由vite.config.ts的routeGen()从pages/+ 页内defineUniPage生成,开启preserveRouteChanges会保留你手加的自定义字段与整条自定义路由。types/define-uni-page.d.ts、types/route-name.gen.d.ts:宏与路由名的类型增强。- 重新生成时机:
vite编译时。HBuilderX 内若路由没更新,重启一次运行。
14.3 文档站(可选)
cd docs
pnpm install
pnpm dev
在线版:https://mengxi-studio.github.io/unix-architecture/
14.4 与仓库现有文档的三处不一致(以本文 / 代码为准)
| 位置 | 说法 | 实际 |
|---|---|---|
README.md 开头 |
HBuilderX 5.26 | 5.34(CHANGELOG 的修复项依赖 5.34 编译器行为) |
docs/.../getting-started.md 第 6 节 |
「路由表与 pages.json 由 vite 插件自动生成」 | vite.config.ts 只生成 routes.gen.uts 与两个 d.ts;pages.json 需手工注册 |
README.md 第 8 节 |
「新增页面 = 建文件 + pages.json 注册 + defineUniPage」 | 与代码一致,这条是对的 |
14.5 术语
| 词 | 含义 |
|---|---|
| 装配点 | 全局初始化唯一允许发生的位置(main.uts) |
| DTO 还原 | JSON.parse<T>(JSON.stringify(res.data)),把 UTSJSONObject 变成强类型 |
| 域(domain) | 一个业务领域(user / order …),对应 api/*.uts + stores/modules/*.uts |
| 白名单 | router/permission.uts 的 whiteList,免登录路径清单 |
| 冷启动补跑 | 页面已加载但守卫未执行时,主动 guardRoute() 补一次 |
MIT License © MengXi-Studio
(注:部分内容由豆包 AI 生成)

收藏人数:
下载插件并导入HBuilder
下载插件ZIP
赞赏(0)
下载 0
赞赏 0
下载 12774472
赞赏 1960
赞赏
京公网安备:11010802035340号