团队专属接口设计规范细则「外REST + 内RPC」

一、适用范围与前置约定

本细则覆盖团队所有Web项目、小程序、内部管理系统的前后端接口，以及微服务之间的内部通信接口，所有新开发接口必须严格遵循本规范，存量接口迭代时逐步对齐标准。 团队默认采用「外REST + 内RPC」的分层架构：面向C端用户、第三方合作方的对外接口统一使用RESTful规范，内部微服务之间的高频调用统一使用gRPC框架，兼顾通用性与性能。

二、RESTful 接口落地细则

2.1 路径与版本管理

1. 所有对外接口统一以 /api/v[版本号] 作为基础路径，当前线上稳定版本为 /api/v1，后续迭代新增不兼容逻辑时直接升级版本号，旧版本接口保留3个月过渡期后下线。

2. 路径层级严格控制在3级以内，超过3级的复杂筛选逻辑全部通过Query参数传递，示例：

   • 正确示例：/api/v1/users/10086/orders?status=paid&page=2

   • 错误示例：/api/v1/users/10086/orders/paid/2

3. 多单词路径统一使用中划线 - 连接，禁止使用下划线、驼峰命名，避免不同系统之间的URL兼容性问题。

2.2 请求与响应约束

1. 所有POST、PUT请求的请求体统一使用JSON格式，禁止使用FormData传递复杂业务参数，文件上传接口单独拆分使用multipart/form-data格式。

2. 分页参数统一命名为 page（页码，从1开始）、size（每页条数，默认10条，最大不超过100条），排序参数统一为 sort，格式为 字段名,asc/desc。

3. 响应体强制统一结构，所有接口返回格式必须对齐：

   {
"code": 20000,
"status": 200,
"message": "请求处理成功",
"data": {},
"trace_id": "20260721113334abc123"
}

   其中trace_id为全链路唯一标识，用于线上问题快速排查定位。

2.3 错误与安全规则

1. 严格使用标准HTTP状态码标识请求结果，禁止所有接口统一返回200后在body内自定义错误标识：

   • 200：GET、PUT请求处理成功

   • 201：POST创建资源成功

   • 204：DELETE删除资源成功

   • 400：请求参数格式错误

   • 401：未登录或Token失效

   • 403：已登录但无操作权限

   • 404：请求的资源不存在

   • 429：请求频率超限触发限流

   • 500：服务端内部异常

2. 所有对外接口强制走HTTPS协议，敏感参数（密码、身份证号）禁止在URL中明文传递，用户Token统一放在请求头的 Authorization 字段中，格式为 Bearer [token内容]。

三、RPC 接口落地细则

3.1 IDL 定义规范

1. 统一使用Protobuf 3作为接口定义语言，包名按业务模块划分，示例：package com.chengdu.team.user.v1，避免不同模块的接口命名冲突。

2. 服务名统一以 Service 结尾，方法名使用大驼峰精准描述业务动作，禁止使用模糊的通用命名：

   • 正确示例：CreateUser、BatchUpdateOrderStatus

   • 错误示例：OperateData、DoSomething

3. 每个消息体的字段序号从1开始连续分配，预留5个空位作为未来扩展字段，禁止随意修改已上线字段的序号和类型。

3.2 传输与异常约定

1. 所有RPC接口基于HTTP/2协议传输，序列化统一使用Protobuf二进制格式，单接口请求体大小严格控制在2MB以内，大文件传输单独走对象存储服务，禁止通过RPC接口传递。

2. 响应体统一携带业务状态码，0代表调用成功，非0值对应具体业务错误，错误码区间按模块划分：用户模块10001-19999，订单模块20001-29999，避免不同模块的错误码重复。

3. 所有写操作接口必须实现幂等性，客户端携带唯一请求ID，服务端通过请求ID判断是否重复调用，避免网络重试导致数据重复生成。

3.3 开发运维规则

1. 每个RPC接口必须配置独立的超时时间，普通查询接口超时设置为500ms，复杂计算接口超时设置为3s，禁止全局统一设置超时时间。

2. 所有RPC调用强制配置熔断策略，连续10次调用失败后自动熔断，5s后进入半开状态尝试恢复，避免单个服务故障拖垮整个集群。

3. 接口版本迭代优先通过新增方法实现，禁止直接修改已上线方法的参数结构，旧方法标记为Deprecated后保留至少2个迭代周期再下线。

四、团队协作配套流程

1. 所有新接口开发前必须先定义接口契约，通过Swagger+Postman同步给前端和调用方确认后，再启动代码开发，避免后期反复调整。

2. 接口上线前必须完成自动化用例校验，覆盖正常场景、参数异常场景、权限校验场景，确保接口逻辑符合契约定义。

3. 线上接口变更提前3个工作日同步所有调用方，不兼容变更必须提前发布灰度版本，预留足够的迁移时间，避免直接影响线上业务。

基于RESTful API设计规范，以下提供‌用户登录‌和‌订单创建‌的完整接口示例。这两个场景分别代表了“身份鉴权”和“核心业务资源创建”，涵盖了Token获取、请求头携带、幂等性处理及标准响应结构。

1. 用户登录接口 (获取 Token)

登录接口的核心目的是验证用户身份并颁发访问令牌（Access Token）。遵循无状态原则，服务端不保存会话，而是返回一个有时效性的 Token。

‌接口定义‌

• ‌URL‌: /api/v1/auth/login
• ‌Method‌: POST
• ‌Content-Type‌: application/json
• ‌描述‌: 用户提交账号密码，验证通过后返回 JWT Token 及过期时间。

‌请求示例 (Request)‌

{ "username": "zhangsan", "password": "SecurePass@123" }

‌成功响应示例 (Response - 200 OK)

{ "code": 20000, "status": 200, "message": "登录成功", "data": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 7200, "user_info": { "user_id": 10086, "nickname": "张三", "avatar": "https://picsum.photos/100/100" } }, "trace_id": "20260721120001abc" }‌

‌失败响应示例 (Response - 401 Unauthorized)

{ "code": 40101, "status": 401, "message": "用户名或密码错误", "data": null, "trace_id": "20260721120002def" }‌

2. 订单创建接口 (受保护资源)

创建订单属于写操作，且涉及资金安全，必须携带登录时获取的 Token 进行鉴权。同时，为了防止网络重试导致重复下单，通常需要在请求头或请求体中携带唯一的request_id实现幂等性。

‌接口定义‌

• ‌URL‌: /api/v1/orders
• ‌Method‌: POST
• ‌Headers‌:
  • Authorization: Bearer <access_token> (必填，用于鉴权)
  • Idempotency-Key: uuid-v4-string (可选但推荐，用于幂等控制)
• ‌描述‌: 创建一个新的购物订单。

‌请求示例 (Request)

Header:‌

http

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 Content-Type: application/json

Body:

json

{ "items": [ { "product_id": 2001, "quantity": 2, "price": 99.00 }, { "product_id": 2005, "quantity": 1, "price": 150.00 } ], "address_id": 505, "remark": "请放在前台" }

‌成功响应示例 (Response - 201 Created)‌

json

{ "code": 20000, "status": 201, "message": "订单创建成功", "data": { "order_id": "ORD202607210001", "total_amount": 348.00, "status": "PENDING_PAYMENT", "created_at": "2026-07-21T12:00:00Z", "expire_time": "2026-07-21T12:30:00Z" }, "trace_id": "20260721120003ghi" }

‌失败响应示例 (Response - 400 Bad Request - 库存不足)‌

json

{ "code": 40002, "status": 400, "message": "商品库存不足", "data": { "invalid_items": [ { "product_id": 2001, "reason": "insufficient_stock", "available_stock": 0 } ] }, "trace_id": "20260721120004jkl" }