zod-example

一个在 uni-app x（蒸汽模式）项目中使用 zod 做参数校验的 Todo List 示例。

核心：前后端使用同一份 TypeScript schema，schema 定义在 uniCloud 公共模块中，云对象与前端引用的是同一份源码，校验规则只维护一次。

核心亮点

• 单一来源的校验规则：zod schema 写在公共模块 todo-schema 中。
• 前后端同构复用：
  • 云对象 todo 通过 file:../common/todo-schema 依赖该公共模块；
  • 前端通过 vite 的 resolve.alias 把 todo-schema 指向该公共模块的真实源文件，引用同一份源码。
• 前端提交前校验、云对象入库前再校验，两层使用完全相同的规则与中文错误提示。

目录结构

zod-example
├─ pages/index/index.uvue                              # 前端 Todo 页面（引用 todo-schema 调用云对象）
├─ uniCloud-alipay
│  ├─ cloudfunctions
│  │  ├─ common/todo-schema                            # ★ 前后端共享的 zod schema 公共模块
│  │  │  ├─ index.ts
│  │  │  └─ package.json
│  │  └─ todo                                          # 云对象：add / list / toggle / update / remove
│  │     ├─ index.obj.ts
│  │     └─ package.json
│  └─ database/todo.schema.json                        # todo 集合 schema（仅云对象可读写）
├─ package.json                                        # 声明 zod 依赖
└─ vite.config.js                                      # 让共享 schema 的改动在前端实时生效（见「注意事项」）

共享 schema

uniCloud-alipay/cloudfunctions/common/todo-schema/index.ts：

导出	说明
todoSchema	待办项完整结构（_id / title / done / createdAt / updatedAt）
todoAddSchema	新增入参 { title }
todoUpdateSchema	修改入参 { id, title?, done? }
todoIdSchema	删除 / 切换入参 { id }
todoListSchema	列表查询入参 { keyword?, done?, page=1, pageSize=20 }
Todo 等类型	由 z.infer 从 schema 推导
formatZodError	zod 错误 → 一句中文提示
parseInput	校验参数，失败抛出带中文提示的异常（前后端通用）

云对象 API

云对象名：todo，前端通过 uniCloud.importObject('todo') 调用，所有方法返回对象。

方法	入参（zod 校验）	返回
add	{ title }	{ item }
list	{ keyword?, done?, page, pageSize }	{ list, total }
toggle	{ id }	{ item }
update	{ id, title?, done? }	{ item }
remove	{ id }	{ id, removed }

校验失败抛出带 errCode: 'INVALID_PARAM' 的异常，提示信息由共享 formatZodError 生成。

运行步骤

1. 用 HBuilderX 打开本项目，关联 uniCloud 服务空间（目录 uniCloud-alipay）。
2. 右键公共模块 uniCloud-alipay/cloudfunctions/common/todo-schema → 上传公共模块。
3. 右键云对象 uniCloud-alipay/cloudfunctions/todo → 上传部署（本地调试可直接运行云函数）。
4. 上传 uniCloud-alipay/database/todo.schema.json 创建 todo 集合。
5. 运行到 App 或 Web：
   • Web 端建议使用 HBuilderX 内置浏览器调试；使用外部浏览器需在服务空间的跨域配置中放行页面域名。

注意事项

• 共享模块位于 uniCloud-alipay 目录下，不在前端源码树内，而 uni-app 默认把 uniCloud-* 目录加入 server.watch.ignored，所以 Vite 不会监听它、改动不触发热更新。vite.config.js 通过两点让 Vite 原生监听并热更新（无需自己实现文件监听），二者缺一不可：
  1. resolve.alias：把 todo-schema 指向真实源文件，让模块解析路径与监听路径一致；
  2. server.watch.ignored：重写忽略列表（保留除 uniCloud 外的默认忽略项），让 Vite 监听该目录。
• 前端与云对象引用的是同一份源码：前端经 resolve.alias 解析，云对象通过 file:../common/todo-schema 依赖该公共模块。因此根 package.json 只需声明 zod（共享 schema 用到的库），无需再声明 todo-schema。
• 该方式适用于 蒸汽模式（vapor）的 App 以及 Web / 小程序平台；VDOM 模式 App 端无法直接使用 node_modules 包。
• 云对象侧改动共享 schema 后，需重新上传公共模块 / 云对象到服务空间才会生效。