HiAPI Cloud 知识库

Appearance

发布包总览 ​

平台自己发布到 npm 的包共 6 个。它们不是普通依赖 —— 改一行要走完 「发版 → 下游升版本号 → 重新安装」整条链路才生效,而且几乎每个包都被 4~8 个工程消费, 写错一个参数顺序会同时打中所有前端。动它们之前先读这一节。

包版本是什么消费方
@hiapi/hiapi-cloud-web-basic0.0.25HiapiUtils 宿主能力抽象 + 装修 schema 类型 + 链接内核 + 主题8 个工程(含 admin-lib 自己)
@hiapi/hiapi-cloud-admin-lib0.0.13管理后台组件库:useApi()、TablePage、鉴权、验证码admin-ts / shop-admin / vem-admin
@hiapi/hiapi-cloud-components-upload0.2.1构建期 vite 插件:把产物发布到应用商店public-web / shop-web / shop-admin / vem-admin / uniapp-design
@hiapi/hiapi-cloud-dynamic-renderer0.0.8构建期 vite 插件:扫组件目录生成 DynamicRenderer.vuepublic-web / shop-web / uniapp-design / 主应用
@hiapi/socket-client1.0.2长连接 SDK(request/notify/事件订阅)按需
@hiapi/captcha-js1.1.0图形验证码前端admin-ts

🔴 一号陷阱:post / put 的参数顺序,两个包是相反的 ​

这是本仓库出过最贵的一类 bug —— 它不报错。payload 跑到 query string、body 是空的, 后端 @RequestBody 收到一个字段全是默认值的对象(id=0、字符串 null), 于是"删除"删不掉、"上下架"没反应、"审核通过"点了没用,而 HTTP 200。

ts
// web-basic —— 第二个是 query,第三个是 body
HiapiUtils.post(url, params, data)

// admin-lib —— 第二个是 body,第三个是 query   ← 反的!
useApi().post(url, data, params)

记法:HiapiUtils 先 query,useApi 先 body。

判断该放哪个位置:看后端注解 ​

后端写法放哪里
@RequestBody Xxx databody
@RequestParam("id") long idquery
@PathVariable拼进 url
无注解的简单类型形参(如 publish(Long id))query(Spring 默认按 @RequestParam 解析)
@ModelAttribute(BasicQueryController 的 GET /query)query

BasicQueryController 的 /query 同时有 GET(@ModelAttribute)和 POST(@RequestBody)两个映射,所以两种写法都通 —— 这是唯一可以不纠结的接口。

已经踩过的坑(别再犯) ​

时间位置症状
2026-08-21shop-web/subShop/api/shop.ts 全部 16 个 POST 写成 2 参C 端整条写入链路(加购/下单/售后/评价)body 全空
2026-08-22shop-admin 22 处写成 post(url, {}, payload)商户后台所有写操作失效
2026-08-22admin-lib 的 HiapiUtilsInit() 形参照 HiapiUtils 命名却按位置透传给 useApi三个后台里 HiapiUtils.post 的 body/query 对调(当时无调用点,属潜伏)
2026-08-22admin-lib 的 HiapiUtils.delete 实现成 api.get()DELETE 静默降级成 GET,请求打到查询接口,不报错也没删
2026-08-22page-design/main.ts 把 HiapiUtils.post 实现成 (url, data, params)自己的调用点照错实现写所以自洽,但共享 widget 进来就对调
2026-08-22vem-admin qiankun mount() 把 props.post 透传同上,潜伏

教训不是"小心一点",而是:适配两个不同签名时永远不要透传。 形参名写成 A 的顺序、实参按位置传给 B,TypeScript 一个字都不会报 (两边都是 any),而 code review 看形参名只会觉得对。

qiankun 桥接的顺序(现状,尚未统一) ​

主应用 admin-ts 通过 microApi 把网络能力桥给子应用,它用的是 admin-lib 的顺序:

ts
// hiapi-cloud-admin-ts/src/main.ts
const microApi = { post: (url, data, params) => api.post(url, data, params) }

所以子应用在 mount(props) 里接的时候必须交换:

ts
HiapiUtils.post = (url, params, data, options) => props.post(url, data, params, options)

未决事项

让桥接改成 web-basic 的声明顺序会更一致,但 admin-ts(宿主)与 page-design / vem-admin(CDN 加载的子应用)是分别部署的 —— 两边不同时上线就会静默对调所有参数。要改必须一次性协调发布,目前保持现状 + 在子应用侧交换。

二号陷阱:web-basic 有两个大版本在同时跑 ​

声明版本工程
^0.0.25admin-ts、admin-lib(>=0.0.22)、public-web、page-design
^0.0.22shop-web、shop-admin、vem-admin、uniapp-design、主应用 uniapp

0.0.25 才有的东西,0.0.22 完全没有:

  • link.ts:normalizeLink / buildUrl / resolveUrl / CAPABILITY / capabilityOf / matchesPlatform
  • navigator.ts:navigate / resolveLink / LinkAdapter
  • theme.ts:主题令牌运行期注入
  • 类型:LinkKind / LinkAction / LinkOpenType / MiniProgramTarget / NativeAppTarget

照抄 public-web 的组件到 shop-web / uniapp-design 会直接编译不过。 反过来,给 0.0.22 的工程写组件时,颜色只能用自己工程的 --hi-* 令牌(没有 theme 模块), 跳转只能 HiapiUtils.href(字符串)(0.0.22 的 href 第一个参数不接 Link 对象)。

发版流程(每个包都一样) ​

bash
cd <包目录>
npm version patch          # 或 minor
npm publish --access public   # ⚠️ 要人工输 OTP,自动化跑不过去

然后每个下游工程:

bash
# 手改 package.json 里的版本号字符串,再安装
pnpm install

只跑 pnpm install 不会升级

下游写的是 ^0.0.x。npm 对 0.0.x 的语义是精确匹配(major 与 minor 都是 0 时, ^ 不放宽 patch),所以发了 0.0.14 之后,下游不改版本号字符串是永远拉不到的 —— pnpm install 一声不响地保持旧版本。这个坑吃掉过一小时。

想要"改了立刻生效",用 pnpm link 或临时把依赖改成 file:../<包目录>。 提交了 CI 就拉不到。

现存违规(待清理)

  • hiapi-cloud-shop/hiapi-cloud-shop-admin → "@hiapi/hiapi-cloud-components-upload": "file:../../hiapi-cloud-components-upload"
  • hiapi-cloud-vem/vem-admin → "file:///Users/adinz/code/hiapi-cloud/hiapi-cloud-components-upload"(绝对路径,换台机器就装不上)

两处都已提交进 git。改回版本号依赖前,别指望这两个工程在别人机器或 CI 上能装。

hiapi-core-public 不在这里 ​

那是禁止发布的私有构件(已在 pom 里用 deploy.skip 硬拦)。别把它跟这些 npm 包混在一起。

相关 ​