跨平台开发 / 系统课时
传递查询参数和路径参数
传递查询参数和路径参数
本篇将解决 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 拼接错误导致的问题。
按自己的节奏,确认真正理解。