第一个任务:从后端到前端加一个标准列表

跑通这条链路,你就掌握了本系统 80% 的日常开发套路。目标:新增一个"资源"的分页列表(后端接口 + 管理后台页面)。

1. 后端:三件套(entity / service / controller)

// 1) 实体:xxx-entity 模块。每个字段写 Javadoc 注释(会进接口文档!)
@Getter @Setter
@Entity @Table(name = "hiapi_xxx_resource")
public class XxxResource extends BasicEntity {
    /** 商户ID(租户隔离) */
    private long mid;
    /** 资源名称 */
    private String name;
}

// 2) Service:实现 BasicService
@Service
public class XxxResourceService extends AbsBasicService<XxxResource, Long> { }

// 3) Controller:继承基类,/query /get /save /update /delete 全部自动获得
@RestController
@RequestMapping("/merchant/xxx-resource")   // merchant 前缀 = 商户权限
public class XxxResourceController
        extends BasicCurdController<XxxResource, Long, XxxResourceVo, XxxResourceQuery> {

    @Override
    protected long getMid() { return TokenGet.getMid(); }  // 租户隔离,必写
}

要点(违反会被打回):

• 查询必须带 mid —— 基类的 getMid() 钩子就是干这个的
• 更新用 UpdateFields.newBuilder().put(...).build() + QueryWrapper,不要整实体覆盖
• 定制点用基类钩子:parseData(存前转换)、toListVo/toDataVo(出参转换)、saveCallback(存后事务内)、deleteBeforeIntercept(删前校验)

2. 前端:TablePage 一把梭

管理后台列表页不要手写 el-table + 分页,用 TablePage:

<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[] = [
  {type: 'text', label: '名称', key: 'name', placeholder: '按名称搜索'}
]
const columns: TableColumn[] = [
  {label: 'ID', prop: 'id', width: 80},
  {label: '名称', prop: 'name'},
  {label: '创建时间', prop: 'created', type: 'date'}
]
// apiQuery 自动拼 /query 并 GET → /cloud-xxx/merchant/xxx-resource/query?page=&size=&name=
const onLoad = (data: PageRequestParams) => api.apiQuery('/cloud-xxx/merchant/xxx-resource', data)
</script>

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

再到对应账户类型的路由文件注册路由 + 菜单。完整规范见管理后台前端规范。

3. 提交前

• 后端:mvn package -DskipTests 过编译;前端:npx vue-tsc --noEmit 过类型检查
• 新接口写好 Javadoc → 同步接口文档到 EOLINK(见 api/)
• 跨团队要用的新接口?先走契约先行流程