Initial commit: 91dj android client dev_1.0.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,177 @@
|
||||
// lib/utils/page_name_mapper.dart
|
||||
|
||||
import 'package:analytics_sdk/utils/logger.dart';
|
||||
|
||||
/// 统一的页面 pageKey → pageName 映射管理器
|
||||
/// 支持静态默认映射 + 动态添加/覆盖(业务方可在初始化时自定义)
|
||||
///
|
||||
/// ## 两种注册格式
|
||||
///
|
||||
/// **老格式(精确匹配)**:值为字符串,pageKey 与路由名称完全一致时命中
|
||||
/// ```dart
|
||||
/// PageNameMapper.addMappings({'home': '首页'});
|
||||
/// ```
|
||||
///
|
||||
/// **新格式(支持 `:param` 动态路由)**:值为 `{'key': ..., 'name': ...}`
|
||||
/// - `key`:上报时使用的稳定 pageKey(替换掉含真实 ID 的原始路由名)
|
||||
/// - `name`:页面展示名称
|
||||
/// ```dart
|
||||
/// PageNameMapper.addMappings({
|
||||
/// '/video/:id': {'key': 'video_detail', 'name': '视频详情'},
|
||||
/// });
|
||||
/// ```
|
||||
class PageNameMapper {
|
||||
// 默认映射表(SDK 内置,精确匹配)
|
||||
static const Map<String, String> _defaultMap = {};
|
||||
|
||||
// 老格式:精确匹配映射表(路由名 → pageName)
|
||||
static final Map<String, String> _customMap = {};
|
||||
|
||||
// 新格式::param 模式映射表(pattern → ResolvedPageInfo)
|
||||
static final Map<String, ResolvedPageInfo> _patternMap = {};
|
||||
|
||||
// 新格式 resolvedKey 缓存(resolvedKey → pageName),与 _customMap 隔离
|
||||
// 供 getPageName 在 currentPageKey 已被解析为稳定 key 时反查 pageName
|
||||
static final Map<String, String> _resolvedKeyMap = {};
|
||||
|
||||
static const String _tag = 'PageNameMapper';
|
||||
|
||||
/// 去除 pageKey 前导斜杠,结果为空时保留原值(如纯 "/" 保持为 "/")
|
||||
static String normalizeKey(String pageKey) {
|
||||
if (!pageKey.startsWith('/')) return pageKey;
|
||||
final stripped = pageKey.substring(1);
|
||||
return stripped.isEmpty ? pageKey : stripped;
|
||||
}
|
||||
|
||||
/// 获取页面名称(老格式精确匹配,行为与之前完全一致)
|
||||
///
|
||||
/// 同时查 _resolvedKeyMap,确保新格式解析后的稳定 key 也能反查到 pageName
|
||||
static String getPageName(String pageKey) {
|
||||
final key = normalizeKey(pageKey);
|
||||
return _customMap[key] ?? _resolvedKeyMap[key] ?? _defaultMap[key] ?? key;
|
||||
}
|
||||
|
||||
/// 解析路由名称,返回上报用的稳定 [ResolvedPageInfo]。
|
||||
///
|
||||
/// 查找优先级:
|
||||
/// 1. 老格式精确匹配(_customMap / _defaultMap)
|
||||
/// 2. 新格式精确匹配(_patternMap)
|
||||
/// 3. 新格式 `:param` 通配匹配(_patternMap)
|
||||
/// 4. Fallback:key = name = 归一化后的路由名
|
||||
static ResolvedPageInfo resolvePageInfo(String routeName) {
|
||||
final normalized = normalizeKey(routeName);
|
||||
|
||||
// 1. 老格式精确匹配(只查 _customMap / _defaultMap,不查 _resolvedKeyMap)
|
||||
final directName = _customMap[normalized] ?? _defaultMap[normalized];
|
||||
if (directName != null) return ResolvedPageInfo(normalized, directName);
|
||||
|
||||
// 2. 新格式精确匹配
|
||||
final exactPattern = _patternMap[normalized];
|
||||
if (exactPattern != null) return exactPattern;
|
||||
|
||||
// 3. 新格式 :param 通配匹配
|
||||
for (final entry in _patternMap.entries) {
|
||||
if (_matchesPattern(entry.key, normalized)) {
|
||||
return entry.value;
|
||||
}
|
||||
}
|
||||
|
||||
// 4. Fallback
|
||||
return ResolvedPageInfo(normalized, normalized);
|
||||
}
|
||||
|
||||
/// 动态添加或覆盖单个映射
|
||||
///
|
||||
/// [value] 可为字符串(老格式)或 `{'key': String, 'name': String}`(新格式)
|
||||
static void addMapping(String routePattern, dynamic value) {
|
||||
final normalized = normalizeKey(routePattern);
|
||||
if (value is String) {
|
||||
_customMap[normalized] = value;
|
||||
} else if (value is Map) {
|
||||
// ── 风险 1 修复:严格校验 key / name 字段,避免运行时 crash ──
|
||||
final resolvedKey = value['key'];
|
||||
final name = value['name'];
|
||||
if (resolvedKey is! String || resolvedKey.isEmpty) {
|
||||
Logger.warn(_tag, 'addMapping("$routePattern") 的 key 字段无效或为空,已忽略');
|
||||
return;
|
||||
}
|
||||
if (name is! String || name.isEmpty) {
|
||||
Logger.warn(_tag, 'addMapping("$routePattern") 的 name 字段无效或为空,已忽略');
|
||||
return;
|
||||
}
|
||||
|
||||
// ── 风险 3 修复:检测与已注册 pattern 的歧义冲突 ──
|
||||
if (_hasConflictingPattern(normalized)) {
|
||||
Logger.warn(
|
||||
_tag,
|
||||
'addMapping("$routePattern") 与已注册的某个 pattern 存在歧义,'
|
||||
'将按注册顺序匹配,请检查是否重复注册',
|
||||
);
|
||||
}
|
||||
|
||||
_patternMap[normalized] = ResolvedPageInfo(resolvedKey, name);
|
||||
// ── 风险 2 修复:写入独立的 _resolvedKeyMap,不污染 _customMap ──
|
||||
_resolvedKeyMap[resolvedKey] = name;
|
||||
}
|
||||
}
|
||||
|
||||
/// 批量动态添加或覆盖映射,兼容老格式与新格式混传
|
||||
static void addMappings(Map<String, dynamic> mappings) {
|
||||
for (final entry in mappings.entries) {
|
||||
addMapping(entry.key, entry.value);
|
||||
}
|
||||
}
|
||||
|
||||
/// 清空自定义映射(测试或重置用)
|
||||
static void clearCustom() {
|
||||
_customMap.clear();
|
||||
_patternMap.clear();
|
||||
_resolvedKeyMap.clear();
|
||||
}
|
||||
|
||||
/// 判断路由名称是否匹配某个 :param 模式
|
||||
static bool _matchesPattern(String pattern, String routeName) {
|
||||
final patternParts = pattern.split('/');
|
||||
final routeParts = routeName.split('/');
|
||||
if (patternParts.length != routeParts.length) return false;
|
||||
for (int i = 0; i < patternParts.length; i++) {
|
||||
if (patternParts[i].startsWith(':')) continue; // 通配符,跳过
|
||||
if (patternParts[i] != routeParts[i]) return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
/// 检测新 pattern 是否与已注册的 pattern 存在歧义(可能命中同一路由)
|
||||
static bool _hasConflictingPattern(String newPattern) {
|
||||
for (final existing in _patternMap.keys) {
|
||||
if (existing == newPattern) continue; // 相同 pattern,属于覆盖,不是冲突
|
||||
if (_patternsConflict(existing, newPattern)) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
/// 判断两个 pattern 是否可能匹配同一条路由
|
||||
static bool _patternsConflict(String p1, String p2) {
|
||||
final parts1 = p1.split('/');
|
||||
final parts2 = p2.split('/');
|
||||
if (parts1.length != parts2.length) return false;
|
||||
for (int i = 0; i < parts1.length; i++) {
|
||||
final isParam1 = parts1[i].startsWith(':');
|
||||
final isParam2 = parts2[i].startsWith(':');
|
||||
// 两段都是固定字面量且不相等 → 不可能同时匹配
|
||||
if (!isParam1 && !isParam2 && parts1[i] != parts2[i]) return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
/// [PageNameMapper.resolvePageInfo] 的返回值:路由解析后的稳定标识
|
||||
class ResolvedPageInfo {
|
||||
/// 上报用的稳定 pageKey(新格式下为业务方自定义 key,老格式下为归一化路由名)
|
||||
final String key;
|
||||
|
||||
/// 页面展示名称
|
||||
final String name;
|
||||
|
||||
const ResolvedPageInfo(this.key, this.name);
|
||||
}
|
||||
Reference in New Issue
Block a user