【API封装参数传递】params 与 API 封装

代码：

export function getRoleList(params) {
  return request({
    url: '/sys/role',
    params  // 这里的 params 是关键
  })
}

params 的含义：

• 它是一个形参，代表调用这个函数时传入的参数对象。
• 在 Axios（request 通常是基于 Axios 封装的）的配置项中，params 专门用于定义查询参数。
• 最终，它会被拼接到 URL 的后面，变成 ?key=value&key2=value2 的形式。

实际效果示例：

getRoleList({ page: 1, size: 10, roleName: 'admin' })

那么这段代码发出的 HTTP 请求实际上是：

GET /sys/role?page=1&size=10&roleName=admin

一、 params 到底做了什么？

在上述代码中，request 函数通常是对 HTTP 库（如 Axios）的封装。在 Axios 的配置对象中，params 是一个专用属性，用于将数据序列化为 URL 查询字符串。

例如：假设我们需要查询"角色列表"，并进行分页。我们在组件中调用：

// 页面组件中
import { getRoleList } from '@/api/system'

const loadData = async () => {
  // 传入查询参数对象
  const query = {
    page: 1,
    pageSize: 10,
    keyword: '管理员'
  }
  
  // 发起请求
  const res = await getRoleList(query)
}

当执行 getRoleList(query) 时，浏览器网络面板中显示的实际请求 URL 如下：

GET /sys/role?page=1&pageSize=10&keyword=%E7%AE%A1%E7%90%86%E5%91%98

结论：params 将 JSON 对象转换成了 URL 问号后的键值对字符串。

二、 核心知识点辨析：params vs data

这是前端面试和开发中极易混淆的两个概念。在基于 Axios 的请求中：

|------------|--------------------------------------------|------------------------------------------|
| 特性 | params | data |
| 作用位置 | URL | Request Body (请求体) |
| 常用请求方法 | GET，DELETE | POST，PUT，PATCH |
| 数据格式 | 键值对字符串 | JSON 对象，Form-Data 等 |
| 后端接收方式 | Spring: @RequestParam<br>Node: req.query | Spring: @RequestBody<br>Node: req.body |
| 适用场景 | 查询、筛选、分页 | 新增、修改、提交表单 |

代码对比：

// 1. GET 请求：使用 params (查询角色)
export function getRole(id) {
  return request({
    url: '/sys/role',
    method: 'get',
    params: { id } // -> /sys/role?id=1
  })
}

// 2. POST 请求：使用 data (新增角色)
export function addRole(data) {
  return request({
    url: '/sys/role',
    method: 'post',
    data: data // -> Body: { "roleName": "admin" }
  })
}

三、 开发中的常见问题

1. 处理空参数

实际开发中，搜索条件可能为空。我们通常不希望 URL 出现 ?keyword=&page=1这种无意义的参数。

可以在 request 拦截器中统一处理，或者在调用前过滤：

// 使用 lodash 的 omitBy 或者简单的 filter
const cleanParams = Object.fromEntries(
  Object.entries(query).filter(([_, v]) => v !== '' && v !== null && v !== undefined)
)
getRoleList(cleanParams)

2. 数组参数的坑

当 params 中包含数组时，如 ids: [1, 2, 3]，默认序列化结果可能因后端框架不同而有差异（如 ids[]=1&ids[]=2 或 ids=1,2,3）。此时需要与后端约定序列化方式（使用 qs 库或 paramsSerializer）。

// 在 request 封装中配置
import qs from 'qs'

request({
  url: '/sys/role',
  params,
  paramsSerializer: params => qs.stringify(params, { indices: false })
})