HiAPI Cloud 知识库

Appearance

架构总图 ​

一张图看懂 HiAPI Cloud:

mermaid
graph TB
    subgraph 前端
        ADMIN[管理后台<br/>hiapi-cloud-admin-ts<br/>Vue3+ElementPlus]
        UNI[移动端/小程序<br/>hiapi-cloud-uniapp<br/>UniApp]
        DESIGN[装修组件<br/>uniapp-design<br/>UMD微组件]
    end

    GW[网关 hiapi-cloud-gateway<br/>Spring Cloud Gateway<br/>剥离 /cloud-xxx 前缀 → Nacos 路由]

    subgraph 微服务
        PUB[hiapi-cloud-public<br/>公共API+账户+应用市场对接]
        USER[hiapi-cloud-user<br/>用户中心]
        FIN[hiapi-cloud-finance<br/>支付/分账/退款]
        VEM[hiapi-cloud-vem<br/>售货机]
        SHOP[hiapi-cloud-shop<br/>商城]
        STORE[hiapi-cloud-store<br/>门店]
    end

    subgraph 基础设施
        NACOS[Nacos 注册/配置]
        MYSQL[(MySQL<br/>全表带 mid 租户隔离)]
        REDIS[(Redis)]
        TASK[hiapi-task-worker<br/>异步任务/webhook]
    end

    NUWA[hiapi-cloud-nuwa Go<br/>应用市场+授权服务+模块库]

    ADMIN --> GW
    UNI --> GW
    GW --> PUB & USER & FIN & VEM & SHOP & STORE
    微服务 --- NACOS
    微服务 --- MYSQL
    微服务 --- REDIS
    PUB -.授权票据/模块下载.-> NUWA

网关路由表 ​

前端请求前缀目标服务
/cloud-api/**hiapi-cloud-public(公共 API + 账户)
/cloud-user/**hiapi-cloud-user
/cloud-finance/**hiapi-cloud-finance
/cloud-vem/**hiapi-cloud-vem
/cloud-shop/**hiapi-cloud-shop
/cloud-store/**hiapi-cloud-store

四种账户类型(理解权限的钥匙) ​

platform(平台) > channel(渠道) > merchant(商户/租户) > user(终端用户)
  • URL 第二段 = 权限边界:/cloud-vem/merchant/** 只有商户账号能调,/cloud-vem/user/** 是终端用户接口。详见API 设计约定。
  • 所有业务数据都挂在 mid(商户ID)下,这是租户隔离的根,详见术语表。

公共框架(所有 Java 服务的地基) ​

仓库作用
hiapi-fast-frameBasicQueryController / BasicCurdController / BasicService 等基类,见后端规范
hiapi-frame⚠️ 整体废弃,不再部署。新架构里"看起来没实现"的功能是真缺口,不是没迁完
hiapi-basic-feign⚠️ 已归档(2026-07-31 从超级项目摘除)。契约已归位到各提供方仓

服务间调用现在长这样(不再有集中的契约仓):

放哪是什么
<svc>-contract纯接口(方法上有 @GetMapping,类上无 @FeignClient)+ DTO,零 Spring bean。提供方和消费方都依赖
<svc>-contract-feign@FeignClient 客户端 + SPI 适配器。只有消费方依赖

业务代码不得 import 别人的 Feign* 客户端,一律经框架 SPI (cn.hiapi.core.basic.cloud.ICloudXxxService),取实现用 dispatchContext.getCloudService(...) 而不是 getServiceOne(...)。 详见根 CLAUDE.md「服务仓的标准分层」的三条铁律。

特殊部分 ​

  • hiapi-cloud-nuwa(Go):应用市场 + 软件授权服务(License/模块中央库/设备台账),独立于 Java 体系。
  • hiapi-cloud-private / hiapi-core-public / hiapi-core-cpp:代码保护体系——受保护业务模块经 C++ JNI 加载器在运行时载入,详见 ADR-0002。
  • 微前端:管理后台经 Qiankun 从 CDN 加载子应用(设计器、VEM 后台等),子应用菜单/图标随发布自描述。