Context 进阶：applicationContext、abilityContext、extensionContext 的边界

Context 混用会导致服务层依赖过重、生命周期错乱和后台能力异常。最典型的写法是把 UIAbilityContext 传进所有工具类，短期方便，后期测试和重建都会痛苦。 这类问题通常不是某个 API 写错，而是工程边界没有提前定好。本文从 ContextScope 这条主线出发，把场景判断、协议设计、代码封装、异常兜底和验证方法串成一套可落地方案。

本文围绕 全局配置、页面入口、扩展能力、文件访问 展开，重点解决四个问题：

1. 这类能力应该放在入口、页面、服务层还是扩展能力里。
2. 协议字段怎样设计，后续排查才不会靠猜。
3. 代码如何封装，才能避免每个页面各写一套。
4. 异常、重试、日志和验证用例应该怎样补齐。

1. 先明确适用场景和边界

实际项目里，全局配置、页面入口、扩展能力、文件访问 经常横跨多个模块。如果边界不清，调用方会把临时字段塞进参数里，接收方也只能被动兼容。更稳的做法是先明确“谁发起、谁处理、失败谁兜底”。

判断点	推荐做法	不建议做法
调用来源	明确 source 或 owner	只看当前页面路径
业务目标	用 scene 或 type 表达	直接传内部实现名
异常处理	启动前校验，接收方兜底	等页面空白后再排查
日志字段	从入口生成 traceId	出问题后再补日志

2. 先定义稳定协议模型

协议模型要比页面实现更稳定。页面可以改名，Ability 可以迁移，但 ContextScope 这类入口模型不要频繁变。

export interface ContextScope {
  scope: string;
  filesDir: string;
  cacheDir: string;
  abilityName: string;
  lifecycle: string;
}

export interface ContextScopeResult {
  ok: boolean;
  reason?: string;
}

代码解释：

1. ContextScope 把 全局配置、页面入口、扩展能力、文件访问 需要的最小字段收敛到一个结构里。
2. 字段不是为了“传得多”，而是为了启动、接收和日志三端都能对齐。
3. 后续扩展字段可以新增，但核心字段不要随意改名。

3. 字段设计要面向排查

很多线上问题不是无法修，而是无法定位。下面这些字段看起来简单，但能把调用来源、业务目标和链路日志串起来。

字段	类型	工程作用
scope	协议关键字段	启动、解析、日志都围绕它对齐
filesDir	协议关键字段	启动、解析、日志都围绕它对齐
cacheDir	协议关键字段	启动、解析、日志都围绕它对齐
abilityName	协议关键字段	启动、解析、日志都围绕它对齐
lifecycle	协议关键字段	启动、解析、日志都围绕它对齐

4. 启动前先做校验

不要把所有异常都留给接收方。启动前能发现的问题，应该在封装层直接拦住，并给出可记录的原因。

export class ContextBoundaryService {
  static validate(input: ContextScope): ContextScopeResult {
    if (!input.scope) return { ok: false, reason: 'scope is empty' };
    if (!input.filesDir) return { ok: false, reason: 'filesDir is empty' };
    if (!input.cacheDir) return { ok: false, reason: 'cacheDir is empty' };
    return { ok: true };
  }
}

代码解释：

1. ContextBoundaryService 是协议入口的第一道门。
2. 空字段、非法来源、缺少 traceId 这类问题越早拦截越好。
3. 返回结构带 reason，页面可以提示，日志也能直接记录。

5. 构造系统参数要集中到工厂

如果每个页面都自己拼系统参数，字段名迟早会分裂。把转换逻辑收敛到 ContextCapabilityFactory，调用方只提交业务模型。

import { Want } from '@kit.AbilityKit';

export class ContextCapabilityFactory {
  static create(input: ContextScope): Want {
    return {
      abilityName: 'ContextScopeChecker',
      parameters: {
        ...input,
        generatedAt: String(Date.now())
      }
    };
  }
}

代码解释：

1. 工厂只负责从业务协议转换到系统入口参数。
2. generatedAt 这类辅助字段统一补，避免调用方各自处理。
3. 以后目标 Ability 或参数结构变化，只改工厂和路由表。

6. 接收方必须再次解析和兜底

启动前校验不能替代接收方校验。来自通知、卡片、外部入口、系统恢复的参数都有可能缺失或过期。

export class ContextScopeCheckerHandler {
  async handle(input: ContextScope): Promise<void> {
    const result = ContextBoundaryService.validate(input);
    if (!result.ok) {
      StageIssueStore.save('21', result.reason ?? 'unknown');
      return;
    }
    StageTraceLogger.info(input.traceId, '全局配置、页面入口、扩展能力、文件访问');
  }
}

代码解释：

1. ContextScopeCheckerHandler 不相信外部输入，先走同一套校验。
2. 失败时写入 StageIssueStore，页面可以展示错误态，而不是直接白屏。
3. 成功后记录 trace 日志，方便跨生命周期排查。

7. 生命周期里要处理重复进入

Stage 模型下，入口可能来自冷启动，也可能来自已有实例的重复拉起。只在首次创建时处理参数，后面就容易丢入口。

export class Stage21EntryBridge {
  private latest?: ContextScope;

  update(input: ContextScope, lifecycle: 'onCreate' | 'onNewWant' | 'onForeground'): void {
    const result = ContextBoundaryService.validate(input);
    if (!result.ok) {
      StageIssueStore.save('21', result.reason ?? 'invalid input');
      return;
    }
    this.latest = input;
    StageTraceLogger.info(input.traceId, lifecycle);
  }

  current(): ContextScope | undefined {
    return this.latest;
  }
}

代码解释：

1. update 同时支持 onCreate、onNewWant 和前台恢复。
2. 最新入口保存在桥接层，页面只读取解析后的安全数据。
3. 生命周期名进入日志，能判断问题发生在哪个阶段。

8. 失败补偿要有明确策略

不是所有失败都应该重试，也不是所有失败都要提示用户。可以按错误来源做分层：参数错误直接兜底，系统约束延后处理，业务失败进入可重试队列。

export enum Stage21FailureAction {
  ShowFallback = 'show_fallback',
  RetryLater = 'retry_later',
  Ignore = 'ignore'
}

export function resolveStage21Failure(reason: string): Stage21FailureAction {
  if (reason.includes('empty') || reason.includes('unknown')) {
    return Stage21FailureAction.ShowFallback;
  }
  if (reason.includes('network') || reason.includes('timeout')) {
    return Stage21FailureAction.RetryLater;
  }
  return Stage21FailureAction.Ignore;
}

代码解释：

1. 参数类错误通常没有重试价值，应该展示兜底。
2. 网络、超时、系统约束类问题可以进入延迟重试。
3. 失败策略写成函数，后续能加日志、埋点和实验开关。

9. 验证用例要覆盖正常和异常

只验证正常路径没有意义。下面这些用例能覆盖 全局配置、页面入口、扩展能力、文件访问 的核心边界。

export const stage21CheckCases = [
  { name: 'Ability 重建', expect: '可复现并有明确结果' },
  { name: '扩展能力启动', expect: '可复现并有明确结果' },
  { name: '服务层单测', expect: '可复现并有明确结果' },
  { name: '目录读取', expect: '可复现并有明确结果' },
  { name: '资源读取', expect: '可复现并有明确结果' }
];

代码解释：

1. 用例名称直接对应真实问题，方便测试和产品一起确认。
2. 每个用例都要有明确期望，不能只写“能打开”。
3. 如果后续改协议，这组用例就是回归清单。

10. 常见问题排查表

现象	高概率原因	处理方式
服务层测试困难	直接依赖 UIAbilityContext	改成能力接口
后台扩展异常	误用页面 Context	使用 ExtensionContext
重建后引用失效	长期持有旧 Context	生命周期内重新注入
路径混乱	各层直接拼目录	抽出 AppEnvironment

11. 小结

Context 进阶 的关键不是把代码写到能跑，而是把边界提前设计清楚：入口模型要稳定，启动前要校验，接收方要兜底，生命周期要覆盖重复进入，日志要能串起整条链路。这样文章里的方案迁移到真实 Stage 工程后，才不会随着入口变多而失控。