dio初次实操教程
欢迎来到这份 dio初次实操教程的首页栏目。它把一次真实的上手过程摊开来讲：先备好 Dart 或 Flutter 工程，再写出第一个 Dio 实例，然后一路走到请求头统一、拦截器串联和错误兜底。你不需要先读完厚厚的手册，照着页面的节奏敲一遍，就能看到响应落在控制台里。
半夜的台灯下，小林第一次把 Dio 加进自己的小项目。他先别急着写业务，而是先让一个最小请求跑通——这是这份教程反复强调的起点：能跑起来，才有资格谈封装。
- 环境准备
- 实例与配置
- GET / POST 实操
- 拦截器
- 错误处理
第一步：把 Dio 请进工程
Dio 是一个运行在 Dart 与 Flutter 环境中的 HTTP 客户端，用起来像给网络请求套了一层顺手的壳。你要做的准备并不多：一个能编译的工程、一个可访问的接口地址，以及把依赖写进配置里。 打开工程的依赖文件，在依赖段落加入 Dio，版本以包管理站点当前提供的为准；随后执行依赖拉取命令，让它在本地落地。工程目录里出现新的引用记录，就说明这一步成了。
dependencies:
dio: ^5.0.0
# 拉取依赖
# dart pub get 或 flutter pub get导入与最小实例
在需要使用网络的文件顶部导入 Dio，然后创建实例。基地址与超时可以放在配置对象里一次性设定，后续调用就不必层层重复。
import 'package:dio/dio.dart';
final dio = Dio(BaseOptions(
baseUrl: 'https://api.example.com',
connectTimeout: const Duration(seconds: 5),
receiveTimeout: const Duration(seconds: 8),
));把实例放在一个独立文件里导出，是一个很省心的小习惯：日后换地址、加请求头，都只需要动一处。
核心实操：从一次 GET 走到完整流程
-
发起第一个 GET 请求
调用实例上的方法并等待结果。响应的状态码与数据体分别落在不同字段里，取出来打印即可确认链路通畅。
final res = await dio.get('/posts/1'); print(res.statusCode); print(res.data); -
提交一次 POST 数据
需要发送负载时，把数据放进参数里。Dio 会依据内容类型自动编码，多数场景无需手工拼装请求体。
final out = await dio.post('/posts', data: { 'title': 'first', 'body': 'hello dio', }); -
统一请求头
鉴权字段、客户端标识这类内容，最好集中处理。可以写在配置对象的请求头里，也可以放进拦截器，按需增减。
dio.options.headers['X-Client'] = 'practice-demo'; -
接入拦截器
拦截器像一个关卡：请求出发前、响应回来时、出错的时候，都允许你插一手。日志、签名、刷新凭证，都可以安放在这里。
dio.interceptors.add(InterceptorsWrapper( onRequest: (options, handler) { options.headers['X-Token'] = 'demo-token'; return handler.next(options); }, onResponse: (response, handler) { return handler.next(response); }, onError: (err, handler) { return handler.next(err); }, )); -
为失败留一条退路
网络世界不总是顺利。用异常捕获把错误接住，读取错误类型与响应状态，再决定是重试、提示还是静默降级。
try { await dio.get('/not-found'); } on DioException catch (e) { print(e.type); print(e.response?.statusCode); }
方法对照：常用调用的取舍
把常用的四个方法放在一张表里，上手时照查即可。它们共享同一套配置与拦截器，切换成本很低。
| 方法 | 适合的场景 | 最小调用 |
|---|---|---|
| get | 读取列表、详情等查询类资源 | dio.get('/posts') |
| post | 新建记录、提交表单或数据体 | dio.post('/posts', data: {...}) |
| put | 整体更新一条已有记录 | dio.put('/posts/1', data: {...}) |
| delete | 删除指定资源 | dio.delete('/posts/1') |
需要下载文件或接收纯文本时，可在配置对象里调整响应的解析方式，让返回内容按你的预期呈现。
常见问题
- 请求迟迟不返回，一直等着怎么办？
- 先检查配置对象里的连接与接收超时是否设置合理，再确认目标地址在设备上能否访问。多数“卡住”源于地址写错或网络受限。
- 拿到的数据不是我想要的类型
- 确认接口返回的内容类型与响应解析方式是否匹配。需要原始文本时显式指定按文本处理，需要对象时保持默认的 JSON 解析。
- 怎样给所有请求统一加请求头？
- 两种做法都可行：写在基础配置的请求头里，或在拦截器的请求阶段动态追加。需要按条件变化的字段，更适合放在拦截器。
- 拦截器和单独处理请求有什么区别？
- 拦截器作用于该实例下的全部请求，适合日志、鉴权这类共性逻辑；一次性、特殊的需求，直接写在单次调用里更清晰。