接口传参不只是字符串和数字
做网络请求时，很多人以为接口只需要传个用户名、密码这种简单字段。可实际开发中，经常要提交一整个表单数据，比如用户资料编辑页，包含基本信息、地址列表、偏好设置，甚至嵌套的头像上传信息。这时候，单纯用字符串拼接根本行不通。
复杂对象长什么样？
举个例子：你要提交一个订单，这个订单不只包含商品 ID 和数量，还有收货人信息、多个配送地址、优惠券使用记录，以及每个商品的附加选项（比如颜色、尺码）。这些数据天然就是嵌套结构，如果强行拍平成 key=value 的形式，代码会变得难以维护。
这时候就得靠接口定义支持复杂对象传输。常见的方式是通过 JSON 格式把整个对象传过去。后端接收时直接解析 JSON 体，还原出原始结构。
前后端怎么约定这类结构？
光传 JSON 不够，团队协作时必须明确字段含义。比如前端传了一个 addresses 数组，每个元素是不是都带 is_default 字段？如果不提前说清楚，后端可能按必填处理，前端漏了就出问题。
所以接口文档里得写明白结构。可以用 Swagger 或者 YAPI 这类工具，在参数描述中直接定义对象层级。例如：
{
"user_id": 123,
"order_items": [
{
"product_id": 456,
"quantity": 2,
"options": {
"color": "黑色",
"size": "XL"
}
}
],
"shipping_address": {
"name": "张三",
"phone": "13800138000",
"detail": "北京市朝阳区某某路123号"
},
"use_coupon": true
}别忘了类型和边界情况
定义复杂对象时，不仅要列字段，还得说明类型。比如 quantity 是整数还是字符串？use_coupon 能不能为 null？这些细节一旦模糊，联调阶段就会频繁返工。
更现实的问题是，默认值怎么处理。前端没传某个嵌套字段，后端是该用默认配置，还是直接报错？建议在接口文档中标注“可选”或“必填”，减少沟通成本。
实际开发中的小技巧
前端发请求前，可以先用 TypeScript 定义好接口对应的类型，这样在写代码时就有提示，也不容易拼错字段。后端接收时也建议做一次结构校验，比如用 Joi 或 class-validator，防止畸形数据入库。
还有一点容易忽略：文件上传和其他字段混在一起的情况。比如用户资料里既有昵称、生日，又要传头像。这时候不能用普通 JSON，得用 FormData，并把对象字段序列化成键路径的形式，比如：
profile[nickname]=小明&profile[birthday]=1990-01-01或者干脆拆分成两个接口：一个更新资料，一个单独上传头像，逻辑更清晰。