API 设计约定

URL 结构 = 权限边界(最重要的一条)

/cloud-{service}/{audience}/{resource}/{action}

audience 段	谁能调	示例
public	无需登录	/cloud-api/public/config/{group}
account	登录/注册流程	/cloud-api/account/login
user	终端用户(C 端)	/cloud-vem/user/device/query
merchant	商户后台	/cloud-vem/merchant/device/query
channel	渠道后台	/cloud-api/channel/merchant/create
platform	平台管理员	/cloud-vem/platform/app/query
feign	仅服务间内部调用	/cloud-api/feign/merchant/details
open	开放平台(appId+sign)	/cloud-vem/open-api/...

新增接口先想清楚放哪个 audience 段——放错段 = 权限漏洞。

标准分页查询约定

继承 BasicQueryController 自动获得:

GET /{...}/query?page=0&size=10&<查询字段>=...&properties=created&direction=DESC
→ { "data": [...], "total": 123 }

前端配套 useApi().apiQuery(url, data)(自动拼 /query)。非标准列表(自定义 /list、树形等)另行定义,但分页列表一律走 /query 约定。

错误码

各服务用自己的 Language 枚举(如 VemLanguage),格式:(code, i18nKey, 默认中文消息)。错误码段按服务划分(vem: 8801xxxxx),新增错误码在本服务枚举内追加。

兼容性纪律(多团队协作生命线)

1. 字段只加不删;要废弃先标 @Deprecated + 文档注明替代字段,保留至少一个迭代
2. 改已有接口的入参/语义 = PR 必须 @ 所有调用方团队
3. 跨团队新接口先走契约先行流程
4. 跨服务接口改动 = 同时改提供方仓的 <svc>-contract,并保证 /feign/** 的 controller implements 那个契约接口——这是唯一能让契约漂移在编译期暴露的办法(由 hiapi-chart/ci/check-contracts.sh 看守)

接口文档

实体/VO/入参字段写 Javadoc 注释 → 生成 OpenAPI → 同步 EOLINK。流程见 api/index.md。