HiAPI Cloud 知识库

Appearance

管理后台前端规范(hiapi-cloud-admin-ts) ​

Vue 3 + Element Plus + @hiapi/hiapi-cloud-admin-lib(file: 依赖,同级目录,改动即时生效)。

列表页一律用 TablePage ​

不要手写 el-table + 分页。

vue
<script setup lang="ts">
import TablePage from '@hiapi/hiapi-cloud-admin-lib/src/components/TablePage/index.vue'
import {useApi} from '@hiapi/hiapi-cloud-admin-lib/src/utils/api'
import type {PageRequestParams, TableColumn, TableHeader} from '@hiapi/hiapi-cloud-admin-lib/src/types'

const api = useApi()
const header: TableHeader[] = [ /* 搜索栏:text/select/date-picker/buttons,key=查询参数名 */ ]
const columns: TableColumn[] = [ /* 列:render/date/money/buttons/index/image/selection */ ]
const onLoad = (data: PageRequestParams) => api.apiQuery('/cloud-xxx/merchant/xxx', data)
</script>

<template>
  <TablePage :header="header" :columns="columns" :request="onLoad" :query="{properties:['created'], direction:'DESC'}"/>
</template>

要点:

  • header[].key 即查询参数名,自动并入请求;date-picker 为范围选择,值是时间戳
  • 自定义列 type:'render',render:(row)=>h(ElTag,{type:'success'},()=>row.status) 返回 VNode
  • 操作列 type:'buttons';行号 type:'index';金额 type:'money'(读 row.scale/symbol)
  • ref 上有 reload(data?);多选用 type:'selection' + @selectionChange
  • 仅当接口不是标准 /query 分页时才允许直接用 el-table

HTTP ​

一律 useApi():get / post / apiQuery。完整方法表见 admin-lib 包文档。

参数顺序:useApi().post(url, data, params) —— 第二个是 body

和 HiapiUtils.post(url, params, data) 正好相反。写反了不报错:payload 跑到 query string、body 是空的,后端 @RequestBody 收到字段全默认的对象,HTTP 200 但什么都没做。 2026-08-22 在 shop-admin 一次修掉 22 处。详见发布包总览 · 一号陷阱。

  • 只发 body:api.post(url, payload)
  • 只发 query(后端是 @RequestParam):api.post(url, {}, {id})
  • postConfirm(msg, url, params, data) —— 又是另一个顺序,params 在前
  • apiQuery(url, data) 自动拼 /query 发 GET
  • api.get 会自动把数组参数 join(',')(admin-lib ≥ 0.0.13),不要自己再 join 一遍

三种账户类型 ​

merchant / channel / platform 各有独立路由文件和菜单;新页面注册到对应账户类型的路由,别混。

路由与全局钩子(血泪教训) ​

  • 组件内注册的全局路由钩子/拦截器,必须在 onUnmounted 注销
  • 401 处理只做一次导航,谨防"处理 401 → 触发钩子 → 再 401"死循环;登出必须清 token + store
  • api.ts 里的 /login 保险丝不要删

微前端(Qiankun 子应用) ​

设计器、VEM 后台等子应用从 CDN /micro-apps/* 加载;子应用的菜单翻译/图标随子应用发布自描述(admin.json),不在主应用硬编码。

图片上传:一律走 HiapiUtils.uploadFile(),不做 url 输入框 ​

主应用(admin-ts)通过 qiankun props 注入统一选图器,子应用在 mount(props) 里接管 HiapiUtils.uploadFile。业务页面选图的唯一姿势:

ts
HiapiUtils.uploadFile().then((files: FileRes[]) => {
    if (files.length > 0) form.value.logo = files[0].filePath
})

配 el-image 做预览。不要让用户手填图片 url(输入框)——绕过了统一存储 (local/OSS/COS/S3 预签名直传体系),线上会出现外链图片无法治理的情况。 商城子应用封装了 ImagePicker.vue(v-model + 预览 + 删除,30 行),新子应用可照抄: hiapi-cloud-shop/hiapi-cloud-shop-admin/src/components/ImagePicker.vue。

表单提交:apiPost 按 id 自动分流 ​

api.apiPost(url, data) 会按 data.id 是否存在自动拼 /add 或 /edit, 新增和编辑共用一个提交函数,不要手写两个分支。