跨系统、跨微服务的接口设计是需求文档的一部分吗
目录
【总结】跨系统、跨微服务的接口设计，属于需求说明书的内容，但只到业务契约层；
产品经理定义“要什么、何时要、出错怎么办”，
技术负责“怎么实现、怎么保证稳定”。
为什么？
因为接口本质上是业务协作的边界：
谁拥有数据主权
谁对业务结果负责
出错谁兜底
重试会不会造成重复下单
这些如果不在需求阶段定清楚，技术阶段一定会扯皮。
反驳的说辞
接口的技术实现是技术问题，
但“为什么要调、什么时候调、调失败业务怎么办”，
这是需求定义问题，不是技术实现问题。
这是一个边界问题，结论需要分层来看，而不是简单的“是 / 否”。
一句话结论（先给结论）
跨系统、跨微服务的接口设计：
属于需求说明书的一部分，但通常只到“契约级 / 业务级”，而不是“技术实现级”；
产品经理对其“定义需求与边界”负责，技术负责人对其“具体设计与落地”负责。
一、在需求说明书（PRD / BRD）中，接口设计“应该出现到什么程度”
✅ 应该包含（产品经理职责）
在正式、可落地的需求说明书中，以下内容必须出现：
1️⃣ 系统间的交互关系
- 哪些系统参与
- 调用方向（谁调用谁）
- 同步 / 异步
- 关键业务链路
例：
「订单创建后，需要同步调用风控系统进行风险校验，校验通过后才能进入支付流程」
2️⃣ 业务语义层面的接口契约（Business Contract）
不是技术细节，而是业务含义：
- 接口目的（Why）
- 触发条件（When）
- 输入输出的业务字段
- 成功 / 失败的业务含义
- 关键业务规则
例：
「调用库存系统reserveStock接口
输入：SKU、数量、订单号
输出：是否锁库存成功
失败时订单需进入待处理状态」
3️⃣ 业务边界与职责归属（非常重要）
- 哪个系统是最终裁决者
- 哪个系统负责兜底
- 异常由谁处理
例：
「库存不足的判断以库存系统为准，订单系统不做二次校验」
4️⃣ SLA / 非功能性要求（业务视角）
- 是否强一致
- 是否允许延迟
- 可接受失败率
- 超时后的业务行为
❌ 不应该包含（不属于产品经理职责）
以下内容不要求产品经理在需求说明书中给出：
- HTTP / gRPC / MQ 选型
- REST / RPC 接口路径
- 参数类型（string / int）
- 重试策略、熔断算法
- 鉴权方式（OAuth / AKSK）
- DTO / VO / Protobuf 定义
这些属于技术设计说明（TDD / 技术方案）。
二、跨微服务接口 ≠ 纯技术问题（这是很多团队的误区）
很多冲突源于一句话：
“接口是技术的事情，产品不用管”
这是错误的。
为什么？
因为接口本质上是业务协作的边界：
- 谁拥有数据主权
- 谁对业务结果负责
- 出错谁兜底
- 重试会不会造成重复下单
这些如果不在需求阶段定清楚，技术阶段一定会扯皮。
三、产品经理 vs 技术人员：职责清晰划分
产品经理（必须负责）
| 维度 | 是否负责 |
|---|---|
| 是否需要对接某系统 | ✅ |
| 接口的业务目的 | ✅ |
| 调用时机 | ✅ |
| 成功 / 失败的业务含义 | ✅ |
| 业务字段含义 | ✅ |
| 业务异常处理策略 | ✅ |
技术负责人 / 架构师（必须负责）
| 维度 | 是否负责 |
|---|---|
| 接口协议 / 技术选型 | ✅ |
| 数据结构定义 | ✅ |
| 性能 / 并发 / 限流 | ✅ |
| 重试、幂等、事务 | ✅ |
| 监控、日志、告警 | ✅ |
四、成熟团队的“正确姿势”（推荐）
PRD 中的接口描述长这样（示意）
【接口名称】库存锁定
【调用方】订单系统
【被调用方】库存系统
【触发时机】用户提交订单
【业务入参】SKU、数量、订单号
【业务返回】
- 成功：库存已锁定
- 失败：库存不足 / 系统异常
【异常处理】
- 库存不足：提示用户
- 系统异常：订单进入“待确认”状态
【一致性要求】强一致
👉 不出现任何技术细节，但业务边界非常清楚
五、总结一句“职能边界话术”（你可以直接用）
跨系统、跨微服务的接口设计，属于需求说明书的内容，但只到业务契约层；
产品经理定义“要什么、何时要、出错怎么办”，
技术负责“怎么实现、怎么保证稳定”。
如果你愿意，我可以帮你：
- 给你一个 PRD 中“跨系统接口说明”的标准模板
- 或直接帮你 review 你现在的需求文档，看哪些接口责任没写清楚
浙公网安备 33010602011771号