跨平台开发 / 系统课时

传递查询参数和路径参数

传递查询参数和路径参数

本篇将解决 Flutter 调用接口时如何组织 URL 参数的问题,掌握 Dio 中查询参数和路径参数的区别,并能够正确处理分页、筛选和详情查询等常见接口调用。

学习目标

  • 区分查询参数与路径参数的用途
  • 使用 Dio 传递分页、筛选和资源 ID 参数
  • 理解不同参数形式对接口设计的影响

查询参数和路径参数的区别

接口中的参数通常有两种表现形式:查询参数和路径参数。

查询参数位于 URL 的 ? 后面,用于描述查询条件,例如分页页码、排序方式和过滤条件。

路径参数直接属于 URL 路径的一部分,通常用于定位某个具体资源,例如用户 ID 或订单 ID。

类型 示例 适用场景
查询参数 /users?page=1&size=20 分页、筛选、排序
路径参数 /users/1001 查询指定资源

使用 Dio 传递查询参数

Dio 使用 queryParameters 参数发送 URL 查询参数,不需要手动拼接字符串。

dart
import 'package:dio/dio.dart';

Future<void> loadUsers() async {
  final dio = Dio();

  final response = await dio.get(
    'https://api.example.com/users',
    queryParameters: {
      'page': 1,
      'size': 20,
      'keyword': 'flutter',
    },
  );

  print(response.data);
}

预期输出

text
{items: [...], page: 1, size: 20}

Dio 会自动生成类似下面的请求地址:

text
https://api.example.com/users?page=1&size=20&keyword=flutter

这种方式比手动拼接 URL 更安全,也能避免参数编码问题。

处理路径参数

路径参数通常需要根据业务对象动态生成。Dio 不会自动替换路径中的变量,需要开发者提前构造完整路径。

dart
import 'package:dio/dio.dart';

Future<void> getUserDetail(int userId) async {
  final dio = Dio();

  final response = await dio.get(
    'https://api.example.com/users/$userId',
  );

  print(response.data);
}

预期输出

text
{id: 1001, name: Alice}

这里的 userId 来自业务数据,实际项目中通常来自列表点击、路由参数或本地缓存。

分页和筛选参数设计

列表接口通常同时包含多个查询参数,例如:

  • page 表示当前页
  • size 表示每页数量
  • sort 表示排序字段
  • keyword 表示搜索条件

开发时应保持参数名称与服务端接口文档一致,避免客户端自行修改命名。

如果接口需要组合多个筛选条件,也建议通过 queryParameters 统一管理,而不是散落在字符串拼接中。

参数错误的排查方式

当接口返回数据异常时,可以按照以下顺序检查:

  • 确认参数属于查询参数还是路径参数
  • 检查参数名称是否拼写正确
  • 检查数字、布尔值等类型是否符合接口要求
  • 查看最终发送的 URL 是否符合预期

合理区分参数类型,可以让接口调用代码更容易维护,也能减少因为 URL 拼接错误导致的问题。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

传递查询参数和路径参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通