evernote-data-handling

Evernote 数据处理

概述

处理 Evernote 数据的最佳实践，包括 ENML 内容处理、附件管理、本地数据库同步以及 ENEX 导出/导入。

前提条件

• 了解 Evernote 数据模型（笔记、笔记本、标签、资源）
• 用于本地存储的数据库（SQLite、PostgreSQL 等）
• 用于存储附件的文件存储

说明

步骤 1：设计数据架构

设计一个映射 Evernote 数据模型的本地数据库架构。关键表包括：notes（guid、title、content、notebookGuid、created、updated、USN）、notebooks（guid、name、stack）、tags（guid、name）、resources（guid、noteGuid、mime、hash、size）。跟踪更新序列号（USN），以支持增量同步。

CREATE TABLE notes (
  guid TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  content TEXT,
  notebook_guid TEXT REFERENCES notebooks(guid),
  created BIGINT,
  updated BIGINT,
  usn INTEGER DEFAULT 0
);

步骤 2：处理 ENML 内容

解析 ENML 以提取纯文本（去除标签）、转换为 HTML（将 <en-note> 替换为 <body>，将 <en-media> 转换为 <img>/<a> 标签），或转换为 Markdown。发送到 API 之前，通过检查必需的声明和禁止使用的元素来验证 ENML。

function enmlToPlainText(enml) {
  return enml
    .replace(/<\?xml[^>]*\?>/g, '')
    .replace(/<!DOCTYPE[^>]*>/g, '')
    .replace(/<[^>]+>/g, ' ')
    .replace(/\s+/g, ' ')
    .trim();
}

步骤 3：处理资源（附件）

通过 noteStore.getResource(guid, withData, ...) 下载资源。将二进制数据保存到本地，并以 MD5 哈希作为文件名。跟踪 MIME 类型，以便正确提供内容类型。计算哈希以验证完整性。

步骤 4：同步数据管理器

使用 getSyncState() 获取当前服务器 USN，然后使用 getSyncChunk() 获取自上次同步以来的变更，实现增量同步。按顺序处理数据块：先处理笔记本，然后是标签、笔记，最后是资源。

const syncState = await noteStore.getSyncState();
if (syncState.updateCount > lastSyncUSN) {
  const chunk = await noteStore.getSyncChunk(lastSyncUSN, 100, true);
  // Process chunk.notebooks, chunk.tags, chunk.notes, chunk.resources
}

步骤 5：导出数据

将笔记导出为 ENEX（Evernote 的 XML 导出格式）、JSON 或 Markdown。ENEX 会保留完整的笔记结构，包括资源，并且兼容 Evernote 导入。

完整的数据架构、同步管理器、ENML 处理器和导出实现，请参阅实现指南。

输出

• 用于本地存储 Evernote 数据的 SQL 架构
• ENML 转文本和 ENML 转 HTML 转换器
• 资源下载和本地存储管理器
• 使用 USN 跟踪的增量同步引擎
• ENEX、JSON 和 Markdown 导出工具

错误处理

错误	原因	解决方案
BAD_DATA_FORMAT	更新时 ENML 格式错误	在调用 API 前使用 DTD 检查验证 ENML
QUOTA_REACHED	超出上传限制	创建笔记前检查 user.accounting.uploaded
DATA_CONFLICT	笔记自上次读取后已被修改	按 GUID 重新获取笔记并合并变更
同步数据块缺失	USN 范围遗漏	从 USN 0 开始请求完整同步

资源

• Evernote 数据模型
• ENML 参考
• 同步
• ENEX 导出格式

后续步骤

有关企业功能，请参阅 evernote-enterprise-rbac。

示例

本地镜像：使用增量同步将所有笔记同步到本地 SQLite 数据库。以 MD5 哈希为键将资源存储到磁盘。使用本地镜像进行全文搜索，无需调用 API。

Markdown 导出：将笔记本中的所有笔记转换为 Markdown 文件，保留笔记本堆栈中的文件夹结构，并将附件保存到 assets/ 目录。