Marico's space

最近折腾 Flutter 和后端接口对接，踩了几个坑，这篇把问题说清楚。

现代移动应用几乎不可能独立工作。不管你是做电商、社交、任务管理还是招聘类 App，Flutter 应用通常都需要和后端服务器通信。

这就是 REST API（表述性状态转移应用程序接口）的用武之地。

这篇指南会讲清楚：REST API 是怎么工作的、Flutter 里怎么发请求、怎么解析 JSON 响应、以及怎么组织可扩展的网络层代码。

如果你刚接触 Flutter 接口对接，这篇能给你一个扎实的基础。

什么是 REST API

REST API（Representational State Transfer Application Programming Interface） 允许不同应用通过 HTTP 协议在互联网上互相通信。

举个例子，一个 Flutter 应用可能需要从后端获取用户列表：

GET https://jsonplaceholder.typicode.com/users

服务器处理请求后返回数据，常见格式是 JSON：

[ { "id": 1, "name": "Leanne Graham", "email": "leanne@example.com" }
]

Flutter 应用把 JSON 数据转成 Dart 对象，然后在界面上展示出来。

整体流程是这样的：

Flutter App ↓
HTTP Request ↓
REST API ↓
Backend Server ↓
Database ↓
JSON Response ↓
Flutter App

Flutter 中配置 API 对接

Flutter 里最简单的方式是用 http 包来发 HTTP 请求。

在 pubspec.yaml 里添加依赖：

dependencies: flutter: sdk: flutter http: ^1.2.0

然后运行：

flutter pub get

导入需要的包：

import 'dart:convert';
import 'package:http/http.dart' as http;

说明一下：

• http 用来发送 HTTP 请求
• dart:convert 用来解析和生成 JSON 数据

创建模型类

别在代码里到处用原始 JSON 或者 dynamic 类型，先建一个 Dart 模型类。

比如：

class User { final int id; final String name; final String email; User({ required this.id, required this.name, required this.email, }); factory User.fromJson(Map<String, dynamic> json) { return User( id: json['id'], name: json['name'], email: json['email'], ); }
}

用模型类好处很多：

• 更好的类型安全
• 代码更清晰
• 调试更方便
• IDE 支持更好
• 项目大了之后更容易维护

创建 API 服务

好的 Flutter 项目不应该把接口调用直接写在 widgets 里。

正确的做法是创建一个独立的服务类，专门负责和后端通信。

import 'dart:convert';
import 'package:http/http.dart' as http; class ApiService { Future<List<User>> getUsers() async { final url = Uri.parse( 'https://jsonplaceholder.typicode.com/users', ); final response = await http .get(url) .timeout(const Duration(seconds: 10)); if (response.statusCode == 200) { final List data = jsonDecode(response.body); return data .map((json) => User.fromJson(json)) .toList(); } throw Exception( 'Failed to load users (${response.statusCode})', ); }
}

这样 UI 层不需要知道 HTTP 请求的具体细节，只需要调用服务、拿到数据就行。

在 Flutter 中展示 API 数据

服务准备好之后，从页面调用它。

比如：

@override
void initState() { super.initState(); loadUsers();
}

然后获取数据、更新 UI：

setState(() { users = data; isLoading = false;
});

展示用户列表：

ListView.builder( itemCount: users.length, itemBuilder: (context, index) { return ListTile( title: Text(users[index].name), subtitle: Text(users[index].email), ); },
)

这样就创建了一个可滚动的列表，数据来自 REST API。

理解 API 请求流程

当 Flutter 应用和后端通信时，整个流程大概是这样的：

User Opens Screen ↓
Flutter Calls API Service ↓
HTTP Request ↓
Backend Processes Request ↓
Database Operation ↓
JSON Response ↓
JSON Decoding ↓
Dart Model ↓
UI Update

理解这个流程很重要，因为出问题的时候能帮你快速定位哪里卡住了。

必须掌握的 HTTP 方法

REST API 常用四个 HTTP 方法。

GET — 读取数据

GET 用于获取信息。

final response = await http.get(url);

常见场景：

• 获取用户列表
• 加载商品列表
• 获取职位列表
• 拉取任务列表

POST — 创建数据

POST 用于创建新资源。

final response = await http.post( url, headers: { 'Content-Type': 'application/json', }, body: jsonEncode({ 'name': 'John', 'email': 'john@example.com', }),
);

典型场景：

• 用户注册
• 登录请求
• 创建任务
• 添加商品

PUT — 更新数据

PUT 用于更新已有资源。

final response = await http.put( url, headers: { 'Content-Type': 'application/json', }, body: jsonEncode({ 'name': 'Updated Name', }),
);

DELETE — 删除数据

DELETE 用于删除资源。

final response = await http.delete(url);

处理加载、成功、空数据和错误状态

生产环境的 Flutter 应用不能假设每个请求都会成功。

至少要处理这几个状态：

加载中

等待 API 响应时显示加载指示器：

const CircularProgressIndicator()

成功

展示获取到的数据。

空数据

如果 API 返回没有记录，给用户一个友好提示：

const Text('No users found')

错误

请求失败了，别让用户对着空白屏幕发呆。

比如：

try { final data = await apiService.getUsers(); setState(() { users = data; isLoading = false; });
} catch (e) { setState(() { errorMessage = 'Unable to load users'; isLoading = false; });
}

好的状态处理让应用感觉可靠很多。

理解 HTTP 状态码

了解 HTTP 状态码能帮助 Flutter 开发者正确处理 API 响应。

状态码	含义
200	请求成功
201	资源创建成功
204	请求成功但无内容返回
400	请求参数错误
401	未授权
403	禁止访问
404	资源不存在
500	服务器内部错误

举个例子，401 响应通常意味着用户的身份令牌丢失或失效了。

404 一般表示请求的资源没找到。

处理认证

很多实际项目中的 API 需要认证。

常见做法是在请求头里带上访问令牌：

final response = await http.get( url, headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN', 'Content-Type': 'application/json', },
);

生产环境应用千万别把敏感凭证直接写进源代码里。

根据应用需求，身份令牌可能需要安全存储，过期了还要刷新。

API 对接最佳实践

Flutter 项目大了之后，如果把接口代码都塞进 widgets 里，很快就会乱成一团。

建议遵循这些做法：

• 接口调用和 UI 代码分离
• 为 API 响应创建模型类
• 用 HTTPS 进行接口通信
• 检查 HTTP 状态码
• 添加请求超时
• 处理加载、成功、空数据和错误状态
• 不硬编码敏感凭证
• 接口地址统一管理
• 大型应用使用 Repository 层
• 需要统一认证或日志时用拦截器
• 网络需求变复杂了可以考虑 Dio 这类库

可扩展的 Flutter 项目结构

小应用的话，简单的服务层结构就够了。

项目大了可以这样组织：

lib/
│
├── core/
│
├── models/
│
├── services/
│
├── repositories/
│
├── providers/
│
├── screens/
│
├── widgets/
│
└── main.dart

这种分层让各个部分的维护和测试都更方便。

更大规模的项目可以再加几层：

UI ↓
State Management ↓
Repository ↓
API Service ↓
REST API

这种方式让业务逻辑、网络层和展示层各司其职。

http 包 vs Dio

http 包对初学者和小应用来说够用了。

大型应用可能更适合用 Dio，它提供更多网络功能：

• 拦截器
• 请求取消
• 表单数据支持
• 文件上传
• 请求配置
• 统一错误处理

不是每个项目都需要 Dio。先用 http 包，等项目需求上来了再换更强大的网络方案。

初学者要避开的常见错误

Flutter 对接 API 时，初学者经常踩这几个坑。

把接口调用直接写在 Widgets 里

这样 UI 代码会很难维护。

更好的做法：把网络逻辑搬到服务层或 Repository 层。

忽略 API 错误

别假设每个响应都是 200 状态码。

一定要检查响应状态，处理可能的失败情况。

到处用 dynamic

用模型类能有更好的类型安全，代码也更容易看懂。

不添加超时

服务器可能响应很慢。

加上超时机制，避免应用无限等待。

硬编码敏感信息

别把 API 密钥、密钥串或凭证直接写在源代码里。

写在最后

REST API 对接是 Flutter 开发者最重要的技能之一。

掌握了这些：

• 发送 HTTP 请求
• 处理 JSON
• 创建 Dart 模型
• 处理 API 响应
• 管理加载和错误状态
• 把网络层和 UI 分离
• 正确组织项目结构

你就有了搭建真实 Flutter 应用的基础。

从简单的 API 开始练手，熟练掌握 GET、POST、PUT、DELETE 请求，然后逐步探索认证、Repository、状态管理和高级网络库。

接口对接练得越多，Flutter 应用连上真实后端就越轻松。