PRD接口清单怎么写：请求参数/响应结构/错误码（附接口文档模板）

前言

接口文档是前后端协作的基础。很多联调问题都是因为接口文档不清楚：参数类型不明确、响应结构不完整、错误码没定义。这篇给你完整的接口文档模板。

一、接口文档模板

接口名称：创建订单 接口路径：POST /api/orders 接口描述：创建新订单 权限要求：登录用户 请求头： - Content-Type: application/json - Authorization: Bearer {token} 请求参数： { "goods_id": 123, // 商品ID，必填，整数 "quantity": 2, // 购买数量，必填，整数，≥1 "address_id": 456, // 收货地址ID，必填，整数 "coupon_id": 789, // 优惠券ID，选填，整数 "remark": "请尽快发货" // 备注，选填，字符串，≤200字符 } 响应结构（成功）： { "code": 200, "message": "创建成功", "data": { "order_id": "202312010001", "order_no": "ORD202312010001", "total_amount": 199.00, "created_at": "2023-12-01 10:00:00" } } 响应结构（失败）： { "code": 400, "message": "库存不足", "data": null } 错误码： - 200：成功 - 400：参数错误 - 401：未登录 - 403：无权限 - 404：商品不存在 - 500：系统错误

二、请求参数规范

参数名	类型	必填	说明	示例
goods_id	整数	是	商品ID	123
quantity	整数	是	购买数量，≥1	2
address_id	整数	是	收货地址ID	456
coupon_id	整数	否	优惠券ID	789
remark	字符串	否	备注，≤200字符	请尽快发货

三、响应结构规范

统一响应格式： { "code": 200, // 状态码 "message": "成功", // 提示信息 "data": {} // 业务数据 } 分页响应格式： { "code": 200, "message": "成功", "data": { "list": [], // 数据列表 "total": 100, // 总条数 "page": 1, // 当前页 "page_size": 20 // 每页条数 } }

四、错误码规范

错误码	说明	HTTP状态码
200	成功	200
400	参数错误	400
401	未登录	401
403	无权限	403
404	资源不存在	404
500	系统错误	500

五、接口文档编写步骤

步骤1：梳理接口需求

在编写接口文档前，需要梳理接口需求：

明确业务场景：接口要解决什么业务问题
确定接口功能：接口要实现什么功能
识别输入输出：需要什么输入，返回什么数据
分析异常情况：可能出现的异常情况

在梳理接口需求时，可以使用思维导图工具来整理接口结构和参数关系，比如使用AI思维导图工具，输入业务场景和功能需求，自动生成结构化的接口设计思维导图，帮助快速梳理接口结构和参数。

步骤2：设计接口结构

根据业务需求，设计接口结构：

接口路径：RESTful风格，清晰表达资源和方法
请求方法：GET、POST、PUT、DELETE等
请求参数：必填参数、选填参数、参数类型、参数说明
响应结构：成功响应、失败响应、数据结构

步骤3：定义错误码

定义统一的错误码规范：

成功码：200表示成功
客户端错误：400-499表示客户端错误
服务端错误：500-599表示服务端错误
业务错误：自定义业务错误码

步骤4：编写接口文档

使用标准模板编写接口文档：

接口基本信息：名称、路径、方法、描述
请求参数：参数名、类型、必填、说明、示例
响应结构：成功响应、失败响应、数据结构
错误码：错误码、说明、HTTP状态码

步骤5：评审和优化

接口文档编写完成后，进行评审和优化：

内部评审：产品、前端、后端一起评审
查漏补缺：检查是否有遗漏的参数或场景
优化完善：根据评审意见优化文档

六、实际案例详解

案例1：电商订单创建接口

业务场景：用户下单时，前端调用接口创建订单。

接口文档：

接口名称：创建订单 接口路径：POST /api/v1/orders 接口描述：用户下单，创建新订单 权限要求：登录用户 请求头： - Content-Type: application/json - Authorization: Bearer {token} 请求参数： { "goods_list": [ // 商品列表，必填，数组 { "goods_id": 123, // 商品ID，必填，整数 "quantity": 2, // 购买数量，必填，整数，≥1 "sku_id": 456 // SKU ID，选填，整数 } ], "address_id": 789, // 收货地址ID，必填，整数 "payment_method": "alipay", // 支付方式，必填，字符串，枚举：alipay/wechat/bank "coupon_id": 101, // 优惠券ID，选填，整数 "remark": "请尽快发货" // 备注，选填，字符串，≤200字符 } 响应结构（成功）： { "code": 200, "message": "创建成功", "data": { "order_id": "202312010001", "order_no": "ORD202312010001", "total_amount": 199.00, "freight_amount": 10.00, "coupon_amount": 20.00, "paid_amount": 189.00, "created_at": "2023-12-01 10:00:00", "payment_url": "https://pay.example.com/order/202312010001" } } 响应结构（失败）： { "code": 400, "message": "库存不足", "data": null } 错误码： - 200：成功 - 400：参数错误（如：商品ID不存在、数量不足等） - 401：未登录 - 403：无权限 - 404：商品不存在 - 500：系统错误

关键点：

参数类型明确：goods_list是数组，包含对象
参数约束清晰：quantity≥1，remark≤200字符
响应结构完整：包含订单所有关键信息
错误码明确：覆盖所有可能的错误情况

案例2：CRM客户列表查询接口

业务场景：销售查看客户列表，支持分页和筛选。

接口文档：

接口名称：查询客户列表 接口路径：GET /api/v1/customers 接口描述：分页查询客户列表，支持筛选和排序 权限要求：登录用户 请求头： - Authorization: Bearer {token} 请求参数（Query参数）： - page: 页码，选填，整数，默认1，≥1 - page_size: 每页条数，选填，整数，默认20，范围1-100 - keyword: 关键词，选填，字符串，搜索客户名称、联系人 - status: 客户状态，选填，字符串，枚举：正常/停用/删除 - source: 客户来源，选填，字符串，枚举：线上/线下/转介绍 - sort: 排序字段，选填，字符串，默认created_at，枚举：created_at/name/amount - order: 排序方式，选填，字符串，默认desc，枚举：asc/desc 响应结构（成功）： { "code": 200, "message": "查询成功", "data": { "list": [ { "customer_id": 1, "customer_name": "XX公司", "contact_name": "张三", "contact_phone": "138****5678", "status": "正常", "source": "线上", "amount": 100000.00, "created_at": "2023-12-01 10:00:00" } ], "total": 100, "page": 1, "page_size": 20, "total_pages": 5 } } 响应结构（失败）： { "code": 400, "message": "参数错误：page_size不能超过100", "data": null } 错误码： - 200：成功 - 400：参数错误（如：page_size超过100、sort字段不存在等） - 401：未登录 - 403：无权限 - 500：系统错误

关键点：

分页参数明确：page、page_size、默认值、取值范围
筛选参数完整：支持多维度筛选
排序参数清晰：支持多字段排序
响应结构规范：统一的分页响应格式

案例3：文件上传接口

业务场景：用户上传头像、商品图片等文件。

接口文档：

接口名称：上传文件 接口路径：POST /api/v1/files/upload 接口描述：上传文件（图片、文档等） 权限要求：登录用户 请求头： - Content-Type: multipart/form-data - Authorization: Bearer {token} 请求参数（Form Data）： - file: 文件，必填，文件类型 - 支持格式：jpg/jpeg/png/gif/pdf/doc/docx - 文件大小：≤10MB - 图片尺寸：≤5000x5000 - type: 文件类型，必填，字符串，枚举：avatar/goods/document - description: 文件描述，选填，字符串，≤200字符 响应结构（成功）： { "code": 200, "message": "上传成功", "data": { "file_id": "202312010001", "file_name": "avatar.jpg", "file_url": "https://cdn.example.com/files/202312010001.jpg", "file_size": 102400, "file_type": "image/jpeg", "uploaded_at": "2023-12-01 10:00:00" } } 响应结构（失败）： { "code": 400, "message": "文件格式不支持", "data": null } 错误码： - 200：成功 - 400：参数错误（如：文件格式不支持、文件过大等） - 401：未登录 - 403：无权限 - 413：文件过大 - 500：系统错误

关键点：