联犀开发者文档

前后端应用开发

约 962 字大约 3 分钟

2026-10-16

以公开 apps/iot-basic 为起点，先完成环境准备。自己的业务不需要修改平台合同或等待平台主仓合入。

保留可独立构建的布局

apps/iot-basic/
├── web/       Vue Web 客户端
├── mobile/    uni-app 独立项目
└── backend/   Go 后端、平台认证与代理

首次复用建议保留完整 ur-kit 布局和锁文件。单独复制 Web 会丢失共享包闭包，单独复制 mobile 会丢失合同和版本校验入口。源码从固定标签取得，不借用 SaaS 工作区的别名或 node_modules。

Go 后端若拆为单独仓库，需要修改自己的 module 名，将样例 v0.0.0 和相对 replace 改成固定 ur-kit v0.2.36，再整理依赖。Java/Node 可复用公开 SDK 与中间件实现后端，但需自行完成业务服务及 Docker 运行阶段。

实现一条自己的业务链路

  1. 定义自己的路径前缀，如 /api/v1/my-app/，确定请求、响应、业务权限与数据范围。
  2. 后端复用公开认证中间件，从可信上下文读身份，再按资源、动作、企业和项目授权。
  3. 数据模型与仓储放在自己的后端，表结构和种子数据用幂等迁移管理。
  4. Web 页面调用应用自己的 API 封装，平台 API 继续复用生成客户端与请求拦截器。
  5. 路由在应用自身注册，再按平台集成登记应用、菜单与入口。

示例 ping 只演示认证，不提供业务数据库隔离和资源授权。不要直接把前端传入的项目 ID 写入数据库，也不能认为平台 API 原样透传已经实现应用自己的控制边界。

Web 路由与状态

页面归应用的 views，生产路由模块使用懒加载组件和唯一 name。详情可隐藏菜单，但仍校验 URL 访问权限；企业路径由现有 org-scope 统一处理。

构建时配置实际 VITE_GLOB_APPID。继续使用 IoT 客户端壳时保留其应用名约定，不任意改名破坏组织路由。切换企业或项目时清理旧状态，异步响应核对当前上下文，提交成功后刷新所有受影响数据。

移动端

mobile 在自己的目录安装，不属于根 Web workspace：

cd apps/iot-basic/mobile
pnpm install --ignore-workspace --frozen-lockfile
pnpm run tsc
pnpm run test:contract
pnpm run dev:h5

运行前提供 VITE_API_BASE_URL、VITE_WS_BASE_URL、VITE_TENANT_API_BASE_URL。微信端还需实际小程序 AppID 和合法域名：

pnpm run build:mp-weixin

用微信开发者工具导入 dist/build/mp-weixin/ 并做端侧验收。页面、服务与仓储代码归移动端；只有平台合同升级时才重新生成平台客户端，自己的业务接口不写进平台生成目录。

验证与交付

# 从 ur-kit 根目录选择本次涉及的端。
(cd apps/iot-basic/backend && go test ./...)
pnpm --filter org-iot-client test:unit
pnpm --filter org-iot-client typecheck
pnpm --filter org-iot-client build

新业务至少覆盖坏令牌、跨企业/项目、非法资源动作、坏参数及依赖故障。登录、上下文切换、页面刷新、平台代理和业务读写要分项验收。Docker 的静态页面回退不能把未知 API 返回为 HTML。

完整样例见 IoT 基础应用，容器交付见部署指南。

实时与其他平台能力

应用接收设备数据、告警和用户通知见WS 与消息通知，应用发送通知需要单独的服务权限。上传、字典、数据分析等无需复制平台实现，按能力清单选择公开入口。

更新日志

2026/10/16 20:08
查看所有更新日志
  • b1437-docs(应用开发): 补齐WS通知及平台能力接入导航于
  • 1a4a7-docs(开发指南): 重建平台与应用开发路线于