Interface 规范

目标

规范定义和使用服务接口。

每个服务有且只有这三类接口：公开接口（public）、运营接口（admin）、内部接口（internal）。每个接口对应属于某类接口，不会同时属于几类接口。如果某个接口覆盖了多种接口，只要包含了公开接口，那么就是公开接口；如果覆盖了运营接口和内部接口，那么就是运营接口。

分类	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文件生成代码，但服务端或者客户端就是否使用生成代码不做硬性要求。建议使用生成的代码。

新建的接口可以存放在两个地方：yeying/api/common和yeying/api/<app name>，前者存放公共接口，比如auth、health等，几乎所有服务都有的接口。后者存放专有接口，也就是各自服务的专有接口。

接口变更，需要判断是否实现向下兼容。如果能够实现向下兼容，就不要动路经的版本号/api/v1/xxx，否则，变更接口定义中路径版本号，比如/api/v2/xxx