更新记录

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.json versionName 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 秒验收)

  1. 冷启动访问首页 → 无 token,自动跳到 /pages/login/login;
  2. 登录页已预填 admin / 123456,点「登录」→ 回首页并显示「欢迎,xxx」;
  3. 首页点「退出登录」→ 确认弹窗 → 回登录页。

三步走通,说明网络层(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 已修,改代码时别踩回去)

  1. uts 插件入口不得导出字符串常量 —— 5.34 的 uts-proxy 会生成未加引号的非法 JS,esbuild 报 Expected a semicolon,且只在发行流水线触发。
  2. 域类型必须单文件收敛 —— 发行拷贝不追踪 export type ... from 转发链,子目录类型文件不进发行树。
  3. 插件组件内避免 Animation 类型标注、脚本级 slots.default 检查、带 flush 的 watch —— 5.34 Kotlin 生成器解析不到符号。
  4. 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 生成)

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

无

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

许可协议

MIT License

Copyright (c) 2026 MengXi-Studio

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

暂无用户评论。