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文件生成代码，但服务端或者客户端就是否使用生成代码不做硬性要求。建议使用生成的代码。
接口定义
在新建或者修改proto文件，在自己的项目里面是否使用脚手架生成的服务端和客户端代码不做硬性要求。
公共接口，位置：新建的接口可以存放在两个地方：yeying/api/common/
专有接口，位置：common和yeying/api/<app name>，前者存放公共接口，比如/auth、health等，几乎所有服务都有的接口。后者存放专有接口，也就是各自服务的专有接口。
向下兼容
兼容性，尽量不动路经的版本号/接口变更，需要判断是否实现向下兼容。如果能够实现向下兼容，就不要动路经的版本号/api/v1/，否则，变更接口定义中路径版本号，比如xx，除非无法向下兼容，才使用/xxx/api/v2/xxxxx