本文目录

一、什么是接口？
二、如何看懂接口文档？
三、PRD中，接口怎么写？

PRD中的接口模板
产品经理prd里写接口文档时，要注意哪些点？
案例：电商“加入购物车”功能

前言：

摆事实，朋友公司10个产品经理，10个人全部都会在prd里写需求的相关接口文档。

宝，如果你还不会，不要紧，看完这篇文章你就会了~

写完并逐字逐句矫正，已凌晨2点，昨天刚删完一个游戏，难得的认真，奥里给~

一、什么是接口，也就是API

1.定义

API（Application Programming Interface，应用程序编程接口）是一套预定义的规则和工具，允许一个软件（或模块）调用另一个软件（或模块）的功能或数据，无需了解内部细节。

说人话：产品功能的“连接器”

API就像“插座与插头”的匹配关系：你不需要知道插座内部如何输电，只需按标准插上就能用电。它让软件开发者能复用现有功能，专注于自己的业务逻辑，极大提升开发效率。

2.接口的核心作用

● 数据传输：传递用户输入、业务数据（如提交订单时，前端将数据传给后端）。

● 功能调用：触发系统能力（如调用地图API获取定位信息）。

● 解耦协作：模块独立开发，通过接口定义实现协作（如订单系统与库存系统分离）。

3.常见接口类型

● RESTful API：基于HTTP协议，使用GET/POST等方法（主流选择，易读性强）。

● GraphQL：灵活定义所需数据字段（适合复杂查询场景）。

● WebSocket：实时双向通信（如聊天室消息推送）。

4.接口的结构和产品经理关注点

注意:重点在右侧，记得表格右滑

模块	说明	产品经理关注点
接口名称	接口的功能描述（如“获取订单”）	接口的用途
请求方法	即接口所提供的方法，包括获取 (GET)、新增 (POST)、修改 (PUT)、删除 (DELETE) 和。	一般使用GET（获取数据）/POST（提交数据）
端点（URL）	接口访问路径（如/api/v1/users）	定位接口位置
请求参数	即接口所需要的输入参数，包括参数名称、参数类型、参数说明等	参数是否必填？取值范围？
响应数据	即接口所返回的输出结果，包括返回值的类型、名称、说明等	返回的关键字段是否满足需求？比如你访问接口目的是获取订单信息，那么观察是否返回订单
状态码	200（成功）/400（参数错误）等	异常场景处理逻辑

5.生活中实际应用场景

● 第三方登录：用微信/Google账号登录其他App（调用了微信/Google的API）。

● 地图服务：App内嵌入高德/Google地图（调用地图API）。

● 支付功能：电商调用支付宝API完成支付。

● 数据获取：从天气API获取实时数据，或从股票API拉取行情。

如有帮助，勿忘关注，谢谢

二、如何看懂接口文档？

1. 先看全局：快速抓住核心信息

● 接口用途：明确这个API能做什么（例如：获取天气、支付下单）。

● 请求方式：是GET、POST、PUT还是DELETE？

● 接口地址（Endpoint）：如 https://api.example.com/weather。

● 认证方式：是否需要API Key、OAuth 2.0、Token等（文档开头通常会说明）。

2. 重点关注请求参数（Request）

● 必填参数 vs 可选参数：文档会标注哪些参数是必须的（如city），哪些可选（如unit=℃）。

● 参数类型：

○ Query参数：附加在URL后，如 /weather?city=北京&unit=℃。

○ Path参数：嵌入在URL路径中，如 /user/{id}。

○ Body参数：通过POST/PUT请求发送的JSON或表单数据。

● 参数格式：注意是否要编码（如URL编码、JSON格式）、参数值的范围或枚举（如unit只能是℃或℉）。

3. 解析响应结果（Response）

● 响应格式：通常是JSON或XML，文档会给出示例：

{
  "city": "北京",
  "temperature": 28,
  "unit": "℃"
}

● 字段含义：每个返回字段的意义（如temperature表示温度）。

● 状态码：如 200（成功）、400（参数错误）、401（未认证）、500（服务器错误）。

4. 实战技巧：从示例入手

接口文档通常提供调用示例，这是最直观的学习方式：

# 示例：获取北京天气（GET请求）
curl -X GET "https://api.example.com/weather?city=北京&key=你的API密钥"

● 复制示例到工具中测试：用Postman、Insomnia等工具直接调试。

● 对比参数和响应：修改参数值（如我们把示例中的入参参数city改为广州），观察响应变化。

5. 警惕常见“坑点”

● 认证和权限：80%的问题来自未正确配置API Key或Token。

● 频率限制：文档会说明每分钟/每天的最大调用次数。

● 版本差异：注意文档是否标注了接口版本（如/v1/weather和/v2/weather可能不同）。

● 错误码对照表：遇到错误时，速查文档中的错误码解释（如1001=城市不存在）。

6. 推荐学习路径

1. 直接动手：用Postman调用文档中的示例接口，观察结果。

2. 从简单接口练起：例如获取IP地址、天气预报等免费API。

3. 参考成熟文档：学习标准化的文档

（如微信官方文档：https://developers.weixin.qq.com/doc/）

7.示例：快速解析一个天气API文档

## 获取天气
- **Endpoint**: `GET /weather`
- **认证**: 需在Header中添加 `X-API-Key: your_key`
- **参数**:
- `city`（必填）: 城市名称
- `unit`（可选）: 温度单位，`℃`或`℉`，默认`℃`
- **响应示例**:
```json
{
"city": "北京",
"temperature": 28,
"unit": "℃",
"humidity": 65
}

错误码:

400: 参数缺失
401: API Key无效

**你的调用思路**：
1. 构造URL：`/weather?city=上海&unit=℃`
2. 在Header中添加 `X-API-Key: your_key`
3. 发送GET请求，检查返回的JSON数据。

---
### **总结**
接口文档就像**菜谱**：告诉你需要什么材料（参数）、如何操作（请求方式）、最终成品长什么样（响应）。抓住核心参数、认证方式和响应结构，结合工具测试，就能快速上手！

如有帮助，勿忘关注，谢谢

三、PRD中，接口文档怎么写？

3.1 PRD中的接口模板

这是一个用于下单前检查商品库存是否足够的接口，以下是逐项说明：

● 用途：当用户提交订单时，系统调用此接口，检查用户想购买的商品数量是否超出当前库存。

● 重要性：避免超卖（如库存仅剩5件，但用户下单10件时拦截订单）。

● 关键逻辑：

○ 若is_available为true，前端可允许用户继续支付。

○ 若为false，应提示用户“库存不足，剩余X件”。

**业务场景**：用户提交订单时，校验库存是否充足

**接口名称**：库存校验接口

**触发节点**：用户点击“提交订单”按钮时触发

**请求方式**：POST

**请求URL**：`/api/v1/stock/check`

**【入参】请求参数**：

| 参数名 | 类型 | 是否必填 | 示例值 | 说明 |

|-----------|--------|----------|--------------|----------------|

| quantity | int | 是 | 2 | 购买数量 |

**【出参】响应示例（成功）**：  
{  
  "code": 200,  // 状态码，200表示成功
  "data": {  
    "is_available": true,  // 库存是否足够
    "stock_left": 100   // 当前剩余库存量
  }  
}  
**【出参】响应示例（失败）**： 
{  
  "code": 400,  
  "message": "库存不足"  
}

3.2 产品经理prd里写接口文档时，要注意哪些点？

1. 明确接口的业务目标

● 场景驱动：清晰描述接口服务的业务场景（例如：用户下单时校验库存、支付后通知物流系统）。

● 核心价值：说明接口如何支撑业务目标（如提升订单处理效率、避免超卖）。

● 用户流程：结合用户流程图或泳道图，标明接口触发节点（如用户点击“提交订单”后调用库存校验接口）。

2. 规范接口基础信息

● 接口名称：简洁且语义化（如“库存预占接口”而非“接口1”）。

● 请求方式：明确HTTP方法（GET/POST/PUT/DELETE），例如：

POST /api/v1/orders/{order_id}/reserve_stock

● Endpoint URL：标注完整路径及版本（如/api/v1），便于后续迭代兼容。

3. 详细定义请求与响应参数

请求参数

● 参数表：列明参数名称、类型、是否必填、示例值、取值范围及说明。

参数名	类型	必填	示例值	说明
product_id	string	是	"P1001"	商品唯一ID
quantity	int	是	2	需预占的库存数量（>0）

● 参数位置：区分路径参数（Path）、查询参数（Query）、请求体（Body）。

● 数据格式：指定JSON/XML等格式，提供请求示例：

{
  "product_id": "P1001",
  "quantity": 2
}

响应参数

● 成功响应：包含状态码（如200）、核心数据字段（如库存剩余量）。

{
  "code": 200,
  "data": {
    "reserved": true,
    "stock_left": 98
  }
}

● 错误响应：定义常见错误码（如400参数错误、401认证失败）、错误信息及处理建议：

{
  "code": 400,
  "message": "无效的商品ID"
}

4. 安全与权限控制

● 认证方式：说明接口是否需要API Key、OAuth 2.0 Token或JWT认证。

● 权限范围：标注接口访问角色（如仅限内部系统调用、需用户登录）。

● 敏感数据：若涉及用户隐私（如手机号），明确脱敏规则或加密要求。

5. 性能与边界条件

● 响应时间：业务侧可接受的延迟（如95%请求<500ms）。

● 限流策略：频率限制（如每秒100次请求）及超限处理（返回429状态码）。

● 异常场景：定义极端情况处理逻辑（如库存为负时的补偿机制）。

6. 版本管理与兼容性

● 版本号：接口URL中标注版本（如/api/v1），便于后续升级。

● 废弃计划：若旧版接口需下线，注明时间节点及替代方案。

7. 提供可执行示例

微信公众号接口：批量获取用户基本信息

http请求方式: POST https://api.weixin.qq.com/cgi-bin/user/info/batchget?access_token=ACCESS_TOKEN

POST数据示例

{"user_list":[{"openid":"otvxTs4dckWG7imySrJd6jSi0CWE",
           "lang":"zh_CN"},
        {"openid":"otvxTs_JZ6SEiP0imdhpi50fuSZg",
            "lang":"zh_CN"}]}

8. 与技术团队的协作

● 技术评审：在PRD评审阶段邀请开发人员确认接口文档书写的合理性。

● 变更记录：记录接口调整历史（如新增参数、修改响应结构），避免沟通断层。

9. 避免常见误区

● 过度技术细节：不深入数据库设计或算法实现（如“用Redis缓存库存”属于技术方案，非PRD范畴）。

● 模糊描述：避免“尽可能快”等主观表述，量化指标（如“接口成功率≥99.9%”）。

● 单点依赖：若接口依赖外部系统（如第三方支付），需标注SLA（服务等级协议）及降级方案（如超时后提示稍后重试）。

3.3 案例：电商“加入购物车”功能

#### **4.1 业务逻辑分析**
- **用户行为**：点击“加入购物车”按钮。  
- **系统交互**：  
  1. 前端传递商品ID、SKU、数量；  
  2. 后端校验库存、用户身份；  
  3. 返回结果（成功/失败）。  

#### **4.2 接口文档示例**
**接口名称**：加入购物车  
**请求方式**：POST  
**URL**：`/api/v1/cart/add`  

**请求参数**：  
| 参数名     | 类型   | 必填 | 说明              |  
|------------|--------|------|-------------------|  
| user_id    | string | 是   | 用户ID（从Token解析） |  
| product_id | string | 是   | 商品ID            |  
| sku_id     | string | 是   | SKU编码（如颜色、尺寸） |  
| quantity   | int    | 是   | 数量（≥1）        |  

**响应成功**（200）：  
```json
{  
  "code": 200,  
  "data": {  
    "cart_total": 5  // 当前购物车商品总数  
  }  
}