PRD接口清单设计：核心要素与避坑指南

1. 为什么PRD中的接口清单如此重要？

在互联网产品研发流程中，PRD（产品需求文档）是连接产品、开发和测试团队的核心纽带。我经历过太多因为接口描述不清导致的开发事故——有一次因为参数类型定义模糊，导致移动端传了字符串而服务端期待数值类型，直接引发线上支付故障。从那以后，我深刻认识到：PRD中的接口清单不是形式主义的文档，而是保障多方协作的"技术契约"。

典型的接口问题往往集中在三个方面：请求参数遗漏必填项说明、响应结构缺少关键字段、错误码定义模糊。这些问题会在联调阶段集中爆发，消耗大量沟通成本。比如最近热门的"错误码为0x80020005"问题，就是因为文档未明确说明该错误码对应的具体网络配置异常场景。

2. 接口清单核心四要素拆解

2.1 请求参数：从混乱到规范

请求参数定义最容易出现的问题就是"想当然"。我曾见过一个电商下单接口，文档只写了需要"用户ID"，但实际开发时才发现需要同时传"用户ID"和"设备ID"用于风控校验。完整的请求参数应包含：

• 参数名：遵循snake_case或camelCase规范
• 类型：明确string/number/boolean/array/object等
• 是否必填：用Y/N或true/false标注
• 示例值：给出典型场景下的示例（如手机号"13800138000"）
• 约束条件：如字符串长度、数值范围、正则表达式
• 默认值：非必填项的默认取值

特别要注意类似"jmeter请求参数定义随机数"这样的动态参数场景，需要在文档中明确说明生成规则。例如订单号参数可以标注："由客户端生成的18位数字，建议使用时间戳+随机数组合"。

2.2 响应结构：别让客户端猜字段

响应结构最常见的坑就是字段层级过深或含义模糊。建议采用"三层原则"：

1. 第一层：状态码和基础信息（code/message/data）
2. 第二层：业务数据主体（如订单信息）
3. 第三层：关联数据（如商品列表）

对于数组类响应，一定要说明元素结构和示例。比如获取商品列表的接口，应该给出单个商品的完整字段说明，而不是简单写"返回商品数组"。

2.3 错误码设计：避免"系统错误"式描述

从热搜词"错误码:41002,appid missing"就能看出，明确的错误码多么重要。好的错误码设计应该：

1. 采用分段编码（如1xxxx表示参数错误，2xxxx表示权限问题）
2. 每个错误码对应具体解决方案（不要只说"系统错误"）
3. 包含用户端提示文案和技术排查建议
4. 预留扩展空间（按业务模块分配号段）

例如支付超时错误可以这样定义：

code复制{
  "code": "30001",
  "message": "支付处理超时，请稍后重试",
  "solution": "检查支付网关状态，确认订单未重复提交"
}

2.4 接口文档模板实战

基于多年踩坑经验，我整理了一个高可用的接口模板（Markdown格式）：

markdown复制## 用户登录接口
`POST /api/v1/login`

### 请求参数
| 参数名 | 类型 | 必填 | 示例值 | 说明 |
|--------|------|------|--------|------|
| username | string | Y | "user@example.com" | 支持邮箱/手机号 |
| password | string | Y | "P@ssw0rd!" | 8-20位，需包含大小写和特殊字符 |
| device_id | string | N | "IOS-7D3F2A" | 设备唯一标识 |

### 成功响应
```json
{
  "code": 200,
  "data": {
    "user_id": "U123456",
    "access_[token](https://taotoken.net?utm_source=ai)": "eyJhbGciOi...",
    "expires_in": 86400
  }
}
```

### 错误码
| 错误码 | HTTP状态码 | 描述 | 解决方案 |
|--------|------------|------|----------|
| 40001 | 400 | 用户名或密码错误 | 检查输入或使用忘记密码功能 |
| 40002 | 400 | 账号已锁定 | 联系客服解锁或30分钟后重试 |
| 50001 | 500 | 认证服务不可用 | 检查SSO服务状态 |

3. 高级技巧与避坑指南

3.1 参数依赖与条件必填

很多接口参数之间存在依赖关系，比如：

• 当payment_type为"信用卡"时，必须传card_number
• 查询时间范围不超过31天

这种情况应该在参数表中增加"备注"列说明约束条件。更复杂的可以使用状态转换图辅助说明。

3.2 版本控制策略

接口演进必须考虑版本兼容性。推荐采用：

1. URL路径版本控制（/api/v1/xxx）
2. 废弃字段标记为deprecated而非直接删除
3. 重大变更维护版本迁移指南

3.3 自动化文档工具链

手动维护文档容易过时，建议搭建：

1. Swagger/YAPI用于接口定义
2. 通过代码注释生成文档（如Springfox）
3. 在CI流程中加入文档校验步骤

4. 真实案例解析

4.1 支付接口参数设计缺陷

某电商平台曾因未明确"time_expire"参数的分钟级精度要求（错误提示"time_expire时间过短"），导致大量预订单失效。后来在文档中明确标注：

code复制time_expire: 订单过期时间（单位：分钟）
约束：当面付≥1分钟，在线支付≥5分钟

4.2 Cookie丢失问题排查

类似"playwright chrome点击按钮后请求头没有带cookie参数"的问题，往往是因为：

1. 文档未说明需要先调用/auth接口获取cookie
2. 跨域场景未明确withCredentials配置
3. 未标注Cookie的Domain/Path属性要求

在PRD中应该增加"前置条件"章节说明认证流程。