logo

Flutter认证授权实战:JWT与权限

作者:carzy2026.11.17 03:26浏览量:0

简介:本文讲透 Flutter 认证授权实战:从 JWT、登录接口契约、AuthService、令牌续期、安全存储与路由守卫,到后端权限校验,提供可复用代码和排错清单,帮助开发者构建安全登录体系。

一、先区分认证与授权:两个问题不要混在一起

在 Flutter 应用中,认证解决“你是谁”,授权解决“你能做什么”。两者经常被一起讨论,但设计时应分开处理。

模块 核心问题 典型场景
认证 Authentication 你是谁? 账号密码登录、短信验证码、第三方登录
授权 Authorization 你能做什么? 普通用户不能进入管理员页面、不能删除他人数据

前端可以隐藏按钮、限制页面入口,但真正的安全边界必须在后端。前端隐藏入口只是体验优化,后端接口仍然必须校验令牌、用户身份与权限。

常见错误是只在前端判断 role == 'admin',但后端没有做二次校验。一旦接口被直接调用,权限就会失效。因此,更稳妥的设计是:登录后拿到身份,前端根据权限控制展示,后端在每次请求时再次校验。

二、JWT 的原理与安全边界:它能表达身份,但不能默认当作加密

JWT,全称 JSON Web Token,是一种紧凑且自包含的令牌格式,通常用于客户端和服务端之间传递身份信息。它的基本结构是:

  1. Header.Payload.Signature
  • Header:声明令牌类型和签名算法,例如 {"alg":"HS256","typ":"JWT"}。
  • Payload:存放声明信息,例如用户 ID、角色、过期时间等。
  • Signature:使用密钥对前两部分签名,用于防止内容被篡改。

需要注意:JWT 默认只是编码后的 JSON 数据,不是加密内容。也就是说,持有令牌的人可以解析出 Payload。因此,不建议在 Payload 中存放密码、手机号、身份证号等敏感信息。

如果应用使用 JWT,还要注意令牌过期机制。短有效期 access_token 配合 refresh_token,是常见做法。当 access_token 过期时,服务端可以返回 401,客户端再用 refresh_token 静默换取新的令牌。

三、环境依赖与后端接口契约:先对齐协议,再写客户端

为了让示例更接近真实项目,以下代码基于以下前置条件:

  • Flutter 3.19 及以上,Dart 3 及以上。
  • 状态管理使用 provider。
  • 网络请求使用 http。
  • 令牌保存使用 flutter_secure_storage。
  • 路由管理使用 go_router。

后端接口建议统一使用 JSON,并明确返回结构。例如:

  1. POST /login
  2. Content-Type: application/json
  3. {
  4. "username": "demo",
  5. "password": "password"
  6. }

成功返回:

  1. {
  2. "access_token": "xxx",
  3. "refresh_token": "yyy",
  4. "role": "admin",
  5. "permissions": ["read_user", "write_user"]
  6. }

其他常用接口:

  1. POST /refresh
  2. Content-Type: application/json
  3. {
  4. "refresh_token": "yyy"
  5. }
  1. POST /logout
  2. Authorization: Bearer <access_token>
  1. GET /me
  2. Authorization: Bearer <access_token>

状态码也建议明确:400 表示参数错误,401 表示未登录或令牌失效,403 表示无权限,429 表示请求过于频繁,5xx 表示服务端异常。客户端代码必须围绕这些状态码分支处理,而不是只判断 statusCode == 200。

四、如何设计 Flutter 登录流程:从输入账号到全局状态恢复

一个完整的登录流程可以拆成以下步骤:

  1. 用户输入账号和密码。
  2. 客户端以 JSON 格式调用后端登录接口。
  3. 后端校验成功后返回 access_token 和可选的 refresh_token。
  4. 客户端将令牌保存到安全存储。
  5. 后续请求在 Header 中携带令牌:
  1. Authorization: Bearer <access_token>
  1. 后端解析令牌,判断用户身份与权限。
  2. 如果令牌过期,客户端使用 refresh_token 请求刷新。

客户端请求必须统一格式。登录、刷新、业务请求都建议使用 Content-Type: application/json,否则服务端可能返回 400 或 415。

五、如何补全 AuthService:包含 role、permissions、异常与登录态恢复

下面是一个简化但可运行的 AuthService 示例。它包含令牌、刷新令牌、角色、权限、登录、退出、登录态恢复和刷新会话。

  1. import 'dart:convert';
  2. import 'package:flutter/foundation.dart';
  3. import 'package:flutter_secure_storage/flutter_secure_storage.dart';
  4. import 'package:http/http.dart' as http;
  5. class AuthService extends ChangeNotifier {
  6. static const _tokenKey = 'access_token';
  7. static const _refreshKey = 'refresh_token';
  8. static const _roleKey = 'role';
  9. static const _permissionKey = 'permissions';
  10. final FlutterSecureStorage _storage = const FlutterSecureStorage();
  11. String? _token;
  12. String? _refreshToken;
  13. String? _role;
  14. Set<String> _permissions = {};
  15. String? get token => _token;
  16. String? get refreshToken => _refreshToken;
  17. String? get role => _role;
  18. Set<String> get permissions => Set.unmodifiable(_permissions);
  19. bool get isLoggedIn => _token != null;
  20. Future<bool> login(String username, String password) async {
  21. try {
  22. final response = await http.post(
  23. Uri.parse('https://api.example.com/login'),
  24. headers: {'Content-Type': 'application/json'},
  25. body: jsonEncode({
  26. 'username': username,
  27. 'password': password,
  28. }),
  29. ).timeout(const Duration(seconds: 10));
  30. if (response.statusCode == 200) {
  31. final data = jsonDecode(response.body) as Map<String, dynamic>;
  32. await _applySession(
  33. accessToken: data['access_token'] as String,
  34. refreshToken: data['refresh_token'] as String?,
  35. role: data['role'] as String? ?? 'user',
  36. permissions: (data['permissions'] as List?)
  37. ?.map((e) => e.toString())
  38. .toSet() ??
  39. {},
  40. );
  41. return true;
  42. }
  43. if (response.statusCode == 401) {
  44. return false;
  45. }
  46. throw Exception('登录接口异常:${response.statusCode}');
  47. } catch (_) {
  48. return false;
  49. }
  50. }
  51. Future<bool> restoreLoginState() async {
  52. final token = await _storage.read(key: _tokenKey);
  53. if (token == null || token.isEmpty) {
  54. return false;
  55. }
  56. _token = token;
  57. _refreshToken = await _storage.read(key: _refreshKey);
  58. _role = await _storage.read(key: _roleKey);
  59. final savedPermissions = await _storage.read(key: _permissionKey);
  60. _permissions = savedPermissions == null || savedPermissions.isEmpty
  61. ? {}
  62. : savedPermissions.split(',').toSet();
  63. notifyListeners();
  64. return true;
  65. }
  66. Future<void> refreshSession() async {
  67. if (_refreshToken == null) {
  68. await logout();
  69. return;
  70. }
  71. try {
  72. final response = await http.post(
  73. Uri.parse('https://api.example.com/refresh'),
  74. headers: {'Content-Type': 'application/json'},
  75. body: jsonEncode({
  76. 'refresh_token': _refreshToken,
  77. }),
  78. ).timeout(const Duration(seconds: 10));
  79. if (response.statusCode != 200) {
  80. await logout();
  81. return;
  82. }
  83. final data = jsonDecode(response.body) as Map<String, dynamic>;
  84. await _applySession(
  85. accessToken: data['access_token'] as String,
  86. refreshToken: data['refresh_token'] as String?,
  87. role: data['role'] as String?,
  88. permissions: (data['permissions'] as List?)
  89. ?.map((e) => e.toString())
  90. .toSet(),
  91. );
  92. } catch (_) {
  93. await logout();
  94. }
  95. }
  96. Future<void> logout() async {
  97. try {
  98. if (_token != null) {
  99. await http.post(
  100. Uri.parse('https://api.example.com/logout'),
  101. headers: {'Authorization': 'Bearer $_token'},
  102. ).timeout(const Duration(seconds: 5));
  103. }
  104. } catch (_) {}
  105. _token = null;
  106. _refreshToken = null;
  107. _role = null;
  108. _permissions = {};
  109. await _storage.delete(key: _tokenKey);
  110. await _storage.delete(key: _refreshKey);
  111. await _storage.delete(key: _roleKey);
  112. await _storage.delete(key: _permissionKey);
  113. notifyListeners();
  114. }
  115. Future<void> _applySession({
  116. required String accessToken,
  117. String? refreshToken,
  118. String? role,
  119. Set<String>? permissions,
  120. }) async {
  121. _token = accessToken;
  122. if (refreshToken != null) {
  123. _refreshToken = refreshToken;
  124. }
  125. if (role != null) {
  126. _role = role;
  127. }
  128. if (permissions != null) {
  129. _permissions = permissions;
  130. }
  131. await _storage.write(key: _tokenKey, value: accessToken);
  132. if (_refreshToken != null) {
  133. await _storage.write(key: _refreshKey, value: _refreshToken!);
  134. }
  135. if (_role != null) {
  136. await _storage.write(key: _roleKey, value: _role!);
  137. }
  138. await _storage.write(
  139. key: _permissionKey,
  140. value: _permissions.join(','),
  141. );
  142. notifyListeners();
  143. }
  144. }

这段代码修复了几个常见问题:role 和 permissions 被完整保存;登录使用 JSON;请求加入超时和异常处理;restoreLoginState 不再接收无用的 BuildContext,而是把本地令牌写回 AuthService 并调用 notifyListeners()。

六、如何让 App 启动时恢复登录态:不要在页面里写 BuildContext

很多示例会在某个页面里调用 restoreLoginState(context),这样既容易漏调,也容易因为页面未构建导致状态不同步。更推荐在 App 启动时先完成恢复,再挂载界面。

  1. void main() async {
  2. WidgetsFlutterBinding.ensureInitialized();
  3. final authService = AuthService();
  4. await authService.restoreLoginState();
  5. runApp(
  6. ChangeNotifierProvider.value(
  7. value: authService,
  8. child: const MyApp(),
  9. ),
  10. );
  11. }

在真实项目中,恢复本地令牌后通常还要请求一次 GET /me,确认令牌仍然有效,并获取最新角色与权限。本地保存的权限只用于首屏体验,最终仍以后端返回为准。

七、如何用 go_router 做路由守卫:未登录访问自动跳转到登录页

如果项目使用 go_router,可以在全局路由表中统一处理重定向。

  1. import 'package:flutter/material.dart';
  2. import 'package:go_router/go_router.dart';
  3. import 'package:provider/provider.dart';
  4. final router = GoRouter(
  5. initialLocation: '/',
  6. redirect: (context, state) {
  7. final auth = context.read<AuthService>();
  8. final loggingIn = state.matchedLocation == '/login';
  9. if (!auth.isLoggedIn && !loggingIn) {
  10. return '/login';
  11. }
  12. if (auth.isLoggedIn && loggingIn) {
  13. return '/';
  14. }
  15. return null;
  16. },
  17. routes: [
  18. GoRoute(
  19. path: '/login',
  20. builder: (_, __) => const LoginPage(),
  21. ),
  22. GoRoute(
  23. path: '/',
  24. builder: (_, __) => const HomePage(),
  25. ),
  26. ],
  27. );

这样用户访问个人中心、订单页、管理后台时,如果未登录,就会被统一重定向到登录页,而不是在每个页面重复写判断。

八、如何控制授权:前端控制展示,后端控制安全

前端可以根据权限控制入口展示,例如:

  1. final auth = Provider.of<AuthService>(context, listen: false);
  2. if (auth.permissions.contains('admin')) {
  3. // 显示管理员入口
  4. } else {
  5. // 隐藏管理员入口
  6. }

但必须强调:这不是授权安全的最终保障。真正可靠的授权设计应包括:

  • 后端返回用户角色或权限列表。
  • 前端根据权限控制路由和按钮展示。
  • 后端在每个接口中再次校验权限。
  • 对高风险操作增加二次验证、审计日志或幂等控制。
  • 对无权请求返回 403,而不是静默成功。

前端和后端对权限的理解可以共享字段,但校验点不能只放在前端。

九、接入大模型能力时,如何避免密钥泄露

认证体系完成后,很多应用会继续接入 AI 能力,例如智能问答、文本摘要、内容生成或客服助手。此时最重要的是:模型 API Key 不能放在 Flutter 客户端。

建议遵循以下原则:

  1. 密钥只保存在后端。
  2. 客户端只调用自己的业务后端。
  3. 后端校验用户身份和权限后,再调用模型服务。
  4. 对 AI 请求增加频率限制、费用控制和内容审计。
  5. 如果同时接入多个模型,可评估百度智能云词元所模型服务(自家产品服务)的能力、价格与性能,但仍应由后端统一接入。

例如,客户端请求自己的后端接口:

  1. final response = await http.post(
  2. Uri.parse('https://api.example.com/ai/generate'),
  3. headers: {
  4. 'Authorization': 'Bearer ${authService.token}',
  5. 'Content-Type': 'application/json',
  6. },
  7. body: jsonEncode({
  8. 'prompt': '帮我生成一篇产品介绍',
  9. }),
  10. );

后端收到请求后,再校验用户身份、调用模型服务,并将结果返回给 Flutter 客户端。

十、模型选型怎么看:不要只看参数,要看业务条件

如果应用需要接入大模型,可以先从以下几个维度判断:

维度 判断口径
能力 是否需要长文本、代码、多轮对话、结构化输出
上下文长度 输入材料是否超过单次窗口
时延 用户是否能接受流式输出或较慢响应
成本 按调用量、输入输出长度、频次综合估算
稳定性 是否有重试、降级、备用模型
合规 内容审核、日志留存、数据边界是否满足要求

不要只因为某个模型参数高就选择它。对多数业务来说,稳定、可预期成本、合适上下文长度,往往比单纯追求极限参数更重要。

十一、常见问题与排错清单

JWT 过期怎么处理?
接口返回 401 时,客户端可以引导用户重新登录,或使用 refresh_token 静默刷新。如果刷新令牌也失效,再跳转登录页。

退出登录是否只清本地令牌?
生产环境最好同时调用后端退出接口,使服务端令牌失效。仅清本地令牌不能阻止已被窃取的令牌继续使用。

能否把权限判断写死在前端?
不建议。前端只能优化体验,后端才是安全边界。所有高风险操作都必须由后端再次校验。

JWT 是否越长越好?
不是。Payload 应尽量精简,只放必要声明,避免令牌过大影响请求性能。

如何防止 token 泄露?
使用 HTTPS,使用 flutter_secure_storage 或系统安全能力保存令牌,设置合理过期时间,避免在日志中打印令牌,避免把令牌放进第三方埋点。

为什么登录接口返回 415 或 400?
415 通常表示 Content-Type 不符合后端要求,400 通常表示参数错误。应确认后端是否要求 application/json,以及字段名是否与接口契约一致。

总体来看,Flutter 的用户认证与授权不是单点功能,而是一套从登录、令牌管理、状态同步到权限校验的完整体系。只要把 JWT、安全存储、状态管理和后端权限控制结合起来,就能构建出安全、稳定且可扩展的认证授权方案。

发表评论

活动