一、适用范围与前置约定本细则覆盖团队所有Web项目、小程序、内部管理系统的前后端接口以及微服务之间的内部通信接口所有新开发接口必须严格遵循本规范存量接口迭代时逐步对齐标准。 团队默认采用「外REST 内RPC」的分层架构面向C端用户、第三方合作方的对外接口统一使用RESTful规范内部微服务之间的高频调用统一使用gRPC框架兼顾通用性与性能。二、RESTful 接口落地细则2.1 路径与版本管理所有对外接口统一以/api/v[版本号]作为基础路径当前线上稳定版本为/api/v1后续迭代新增不兼容逻辑时直接升级版本号旧版本接口保留3个月过渡期后下线。路径层级严格控制在3级以内超过3级的复杂筛选逻辑全部通过Query参数传递示例正确示例/api/v1/users/10086/orders?statuspaidpage2错误示例/api/v1/users/10086/orders/paid/2多单词路径统一使用中划线-连接禁止使用下划线、驼峰命名避免不同系统之间的URL兼容性问题。2.2 请求与响应约束所有POST、PUT请求的请求体统一使用JSON格式禁止使用FormData传递复杂业务参数文件上传接口单独拆分使用multipart/form-data格式。分页参数统一命名为page页码从1开始、size每页条数默认10条最大不超过100条排序参数统一为sort格式为字段名,asc/desc。响应体强制统一结构所有接口返回格式必须对齐{code: 20000,status: 200,message: 请求处理成功,data: {},trace_id: 20260721113334abc123}其中trace_id为全链路唯一标识用于线上问题快速排查定位。2.3 错误与安全规则严格使用标准HTTP状态码标识请求结果禁止所有接口统一返回200后在body内自定义错误标识200GET、PUT请求处理成功201POST创建资源成功204DELETE删除资源成功400请求参数格式错误401未登录或Token失效403已登录但无操作权限404请求的资源不存在429请求频率超限触发限流500服务端内部异常所有对外接口强制走HTTPS协议敏感参数密码、身份证号禁止在URL中明文传递用户Token统一放在请求头的Authorization字段中格式为Bearer [token内容]。三、RPC 接口落地细则3.1 IDL 定义规范统一使用Protobuf 3作为接口定义语言包名按业务模块划分示例package com.chengdu.team.user.v1避免不同模块的接口命名冲突。服务名统一以Service结尾方法名使用大驼峰精准描述业务动作禁止使用模糊的通用命名正确示例CreateUser、BatchUpdateOrderStatus错误示例OperateData、DoSomething每个消息体的字段序号从1开始连续分配预留5个空位作为未来扩展字段禁止随意修改已上线字段的序号和类型。3.2 传输与异常约定所有RPC接口基于HTTP/2协议传输序列化统一使用Protobuf二进制格式单接口请求体大小严格控制在2MB以内大文件传输单独走对象存储服务禁止通过RPC接口传递。响应体统一携带业务状态码0代表调用成功非0值对应具体业务错误错误码区间按模块划分用户模块10001-19999订单模块20001-29999避免不同模块的错误码重复。所有写操作接口必须实现幂等性客户端携带唯一请求ID服务端通过请求ID判断是否重复调用避免网络重试导致数据重复生成。3.3 开发运维规则每个RPC接口必须配置独立的超时时间普通查询接口超时设置为500ms复杂计算接口超时设置为3s禁止全局统一设置超时时间。所有RPC调用强制配置熔断策略连续10次调用失败后自动熔断5s后进入半开状态尝试恢复避免单个服务故障拖垮整个集群。接口版本迭代优先通过新增方法实现禁止直接修改已上线方法的参数结构旧方法标记为Deprecated后保留至少2个迭代周期再下线。四、团队协作配套流程所有新接口开发前必须先定义接口契约通过SwaggerPostman同步给前端和调用方确认后再启动代码开发避免后期反复调整。接口上线前必须完成自动化用例校验覆盖正常场景、参数异常场景、权限校验场景确保接口逻辑符合契约定义。线上接口变更提前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: SecurePass123 }‌成功响应示例 (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:‌httpAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 Content-Type: application/jsonBody: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 }