Interface 规范

目标

规范定义和使用接口

分类	public（公开接口）	admin（管理员接口）	internal（内部接口）
谁在用	第三方集成伙伴、外部开发者、移动/前端应用	内部运营/客服/风控团队，或企业租户管理员（B2B）	微服务间调用、批处理/定时任务、数据/搜索/风控等内部系统
典型场景	资源查询/搜索、下单/提交、用户自助操作、Webhook 订阅管理	账户治理与封禁、权限/组织/策略管理、退款/对账、数据导出与擦除（GDPR）、密钥轮换、开关/灰度配置	库存预留与释放、账单结算与对齐、索引/缓存重建、异步事件发布、批量回填与迁移
示例接口	GET /api/v1/public/products/{id}	POST /api/v1/admin/users/{id}:block	POST /ap/v1/internal/search:index
如何选择	面向第三方或终端客户端且需长期稳定	仅运营/管理员可执行、影响资金/权限/合规	仅服务/Job 调用、内部数据形态、可频繁调整

所有接口定义在interface库中，以proto文件形式定义，支持grpc和http两种格式。虽然有脚手架工具能够自动基于proto文件生成代码，但服务端或者客户端就是否使用生成代码不做硬性要求。

在新建或者修改proto文件，在自己的项目里面是否使用脚手架生成的服务端和客户端代码不做硬性要求。

公共接口，位置：yeying/api/common/

专有接口，位置：yeying/api/<app name>/

兼容性，尽量不动路经的版本号/api/v1/xx，除非无法向下兼容，才使用/api/v2/xx