【HarmonyOS 7新能力｜050】Core File Kit mmap工程封装：把接入逻辑放进可维护的分层结构

处理大型索引、离线词典、模型分片或媒体元数据时，频繁 read 加手工缓冲会带来额外复制与复杂的游标管理。内存映射把文件的一段映射到进程虚拟地址空间，让程序像访问内存一样按需读取页面，是一项很有吸引力的性能工具。但 mmap 并不是"打开就会更快"：偏移对齐、文件截断、映射释放、并发写入和异常降级都可能成为稳定性风险。本文围绕 Core File Kit mmap 场景给出一套工程封装思路。示例中的接口是便于讲解的抽象，实际 API、参数、权限和 Native 互操作方式应以当前 HarmonyOS SDK 与官方文档为准。

一、先判断场景是否真的适合 mmap

mmap 更适合较大文件的随机读取、重复扫描、只读索引和多个逻辑视图共享页缓存。一次性读取几 KB 配置、小文件顺序写入、需要强事务语义的记录更新，通常用普通文件 API 更简单。性能决策应基于访问模式，而不是文件扩展名。

ts 复制代码

export interface FileAccessProfile {
  fileBytes: number
  access: 'sequential' | 'random'
  mode: 'readOnly' | 'readWrite'
  expectedReads: number
  windowBytes: number
}

export function shouldMap(p: FileAccessProfile): boolean {
  return p.fileBytes >= 1024 * 1024 &&
    (p.access === 'random' || p.expectedReads > 2) &&
    p.windowBytes > 0
}

阈值没有通用答案，应通过目标设备基准测试校准。内存紧张、文件来自不可信来源或生命周期极短时，也应保留普通读取路径。

二、用五层结构隔离业务与映射细节

推荐拆成五层：页面或业务服务提出读取需求；文件访问服务检查来源与范围；窗口管理器负责偏移、长度和复用；平台适配层执行映射、刷新和解除映射；底层文件系统与页缓存由系统管理。ArkTS 业务侧不直接持有裸指针或文件描述符。

ts 复制代码

export interface BinaryWindow {
  readonly offset: number
  readonly length: number
  read(index: number): number
  slice(start: number, end: number): Uint8Array
  close(): void
}

export interface MappedFileGateway {
  openWindow(path: string, offset: number, length: number): Promise<BinaryWindow>
}

适配层可以基于平台支持选择 mmap 或缓冲读取，业务侧获得同一个 BinaryWindow 契约，便于测试与降级。

三、页对齐是正确映射的第一道门槛

许多映射实现要求起始偏移按系统页大小对齐。业务请求往往从任意字节开始，因此需要向下对齐映射起点，再在映射内部增加 delta。映射长度则覆盖 delta + requestedLength，同时不得越过文件末尾。

ts 复制代码

export interface AlignedRange {
  mappedOffset: number
  mappedLength: number
  delta: number
}

export function alignRange(offset: number, length: number, pageSize: number): AlignedRange {
  const mappedOffset = Math.floor(offset / pageSize) * pageSize
  const delta = offset - mappedOffset
  return { mappedOffset, mappedLength: delta + length, delta }
}

任何负偏移、零长度、溢出或 offset + length 超过文件尺寸的请求都应在进入底层前拒绝。

四、大文件采用窗口化映射而不是一次映射全部

把几十 GB 文件一次性映射不等于立即占用同等物理内存，但会扩大地址空间管理和故障范围，也不利于控制工作集。窗口化映射只保留当前解析所需区域，并根据访问方向预取相邻窗口。

ts 复制代码

export class WindowPlanner {
  constructor(private readonly windowBytes: number) {}

  rangeFor(position: number, fileBytes: number): { offset: number; length: number } {
    const offset = Math.floor(position / this.windowBytes) * this.windowBytes
    return { offset, length: Math.min(this.windowBytes, fileBytes - offset) }
  }
}

窗口大小需要平衡映射切换次数与内存压力。随机查询可用较小窗口，连续扫描可适度放大，并通过指标验证而非凭感觉设定。

五、生命周期必须满足反向释放顺序

正确顺序通常是验证文件、打开描述符、创建映射、完成访问、按需同步、解除映射、关闭描述符。若异常路径跳过解除映射，长期任务会积累地址空间与句柄。封装对象应支持幂等关闭，并阻止关闭后的再次访问。

ts 复制代码

export abstract class ManagedWindow implements BinaryWindow {
  private closed = false
  abstract readonly offset: number
  abstract readonly length: number

  read(index: number): number {
    this.assertOpen(index)
    return this.readUnsafe(index)
  }

  close(): void {
    if (this.closed) return
    this.closed = true
    this.releaseNative()
  }

  protected abstract readUnsafe(index: number): number
  protected abstract releaseNative(): void

  private assertOpen(index: number): void {
    if (this.closed) throw new FileMapError('WINDOW_CLOSED')
    if (index < 0 || index >= this.length) throw new FileMapError('OUT_OF_RANGE')
  }
}

业务会话结束、页面销毁或解析取消时都要走统一释放入口，不能等待垃圾回收替代资源管理。

六、文件变化可能让现有映射失效

如果另一个线程或进程截断、替换文件，旧映射访问可能失败甚至触发进程级异常。只读资源应优先采用不可变文件与版本化文件名；更新时写入新文件，校验完成后原子切换引用，而不是原地缩短正在使用的文件。

ts 复制代码

export interface FileIdentity {
  path: string
  size: number
  modifiedAt: number
  version: string
}

export function sameFile(a: FileIdentity, b: FileIdentity): boolean {
  return a.path === b.path && a.size === b.size &&
    a.modifiedAt === b.modifiedAt && a.version === b.version
}

打开映射前记录身份，关键阶段再次确认。发现文件变化就关闭旧窗口并重新打开，不能继续在旧地址上猜测数据是否有效。

七、读写映射必须明确一致性与落盘语义

可写映射的内存修改何时可被其他观察者看到、何时真正持久化，取决于映射模式、同步调用与文件系统行为。业务不能把"数组已修改"当作"数据已可靠落盘"。重要数据建议采用日志、校验和或写新文件再替换的策略。

ts 复制代码

export interface MappedWriter {
  write(offset: number, bytes: Uint8Array): void
  flush(): Promise<void>
  close(): Promise<void>
}

export class SafeCommitter {
  async commit(writer: MappedWriter): Promise<void> {
    await writer.flush()
    await writer.close()
  }
}

如果应用被杀死也必须保证原子性，单纯调用 flush 仍未必足够，应从数据格式层设计可恢复提交协议。

八、并发访问按文件与区间建模

多个读取者通常可以共享只读窗口；写入者则需要明确互斥范围。全局大锁实现简单但会降低吞吐，按文件或区间锁能提高并行度，却必须避免重叠区间和锁顺序死锁。先从单写多读的清晰模型开始，再按真实瓶颈细化。

ts 复制代码

export class FileLeaseRegistry {
  private readonly writers = new Set<string>()

  acquireWrite(fileKey: string): void {
    if (this.writers.has(fileKey)) throw new FileMapError('WRITE_CONFLICT')
    this.writers.add(fileKey)
  }

  releaseWrite(fileKey: string): void {
    this.writers.delete(fileKey)
  }
}

锁只保护应用内规则；跨进程共享还需使用平台支持的同步机制或不可变数据设计，不能假设另一个进程会遵守内存中的锁。

九、所有输入都要在 Native 边界前校验

文件映射往往进入 Native 层，错误偏移或整数溢出的后果比普通业务异常更严重。路径必须限定在应用允许的目录或经过授权的 URI，长度采用安全整数运算，映射权限不能超过文件打开权限。

ts 复制代码

export function validateRange(fileBytes: number, offset: number, length: number): void {
  if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length)) {
    throw new FileMapError('INVALID_RANGE')
  }
  if (offset < 0 || length <= 0 || offset > fileBytes - length) {
    throw new FileMapError('OUT_OF_RANGE')
  }
}

不要把任意外部路径直接传给底层，也不要记录文件内容、用户目录或敏感 URI。错误日志保留匿名文件键和范围即可。

十、映射失败必须有可预期降级

mmap 可能因为地址空间、权限、文件系统类型或资源压力失败。只读场景通常可以退回分块读取；写入场景是否降级取决于一致性要求。降级应由策略决定，并记录发生原因，避免静默变慢后无人知晓。

ts 复制代码

export class ResilientFileGateway implements MappedFileGateway {
  constructor(
    private readonly mapped: MappedFileGateway,
    private readonly buffered: MappedFileGateway
  ) {}

  async openWindow(path: string, offset: number, length: number): Promise<BinaryWindow> {
    try {
      return await this.mapped.openWindow(path, offset, length)
    } catch (error) {
      if (!(error instanceof FileMapError) || !error.fallbackAllowed) throw error
      return this.buffered.openWindow(path, offset, length)
    }
  }
}

数据损坏、范围错误和权限拒绝不能降级后继续读取；只有明确的资源或能力不可用错误才适合走备用路径。

十一、性能测试同时观察速度、缺页与内存

只比较一次耗时会被系统缓存误导。基准应覆盖冷启动、热缓存、顺序扫描、随机读取、不同窗口大小与不同文件规模，并记录总耗时、吞吐、峰值内存、映射次数、降级率和错误率。测试前明确是否清理缓存，结果才可比较。

ts 复制代码

export interface MappingMetric {
  fileBytes: number
  windowBytes: number
  accessPattern: 'sequential' | 'random'
  durationMs: number
  mappedWindows: number
  fallbackCount: number
  peakMemoryBytes: number
}

同时在低内存、后台切前台和长时间循环读取下做稳定性测试，确保所有窗口最终释放，文件更新后不会继续访问旧映射。

十二、上线检查表：把性能工具关进安全边界

发布前确认：适用场景经过基准验证；偏移按页对齐；范围不越界；大文件使用窗口；关闭幂等；异常路径释放资源；文件更新采用不可变或版本化策略；写入语义明确；并发规则可解释；Native 输入已校验；映射失败有受控降级；指标不含敏感数据。

ts 复制代码

export class FileMapError extends Error {
  constructor(
    readonly code: 'WINDOW_CLOSED' | 'OUT_OF_RANGE' | 'INVALID_RANGE' |
      'WRITE_CONFLICT' | 'MAP_UNAVAILABLE' | 'FILE_CHANGED',
    readonly fallbackAllowed = code === 'MAP_UNAVAILABLE'
  ) { super(code) }
}

Core File Kit mmap 的价值，是为特定访问模式提供更直接的数据路径，而不是替代所有文件读写。通过窗口管理器隔离页对齐与生命周期，通过文件服务约束来源、版本和并发，再用基准测试决定是否启用，才能同时获得性能与稳定性。真正成熟的封装应让业务只看到安全的字节窗口：底层映射成功时享受性能，映射不可用时有明确降级，任何异常都不会留下失效地址或未关闭句柄。