gogcli 实战使用gog gmail settings filters export将 Gmail 过滤器导出为 WebUI 兼容 XML 与 JSON【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligogcligog是一个把 Google Workspace 放进终端的开源命令行工具。本文围绕gog gmail settings filters export命令展开讲解如何把当前账号的全部 Gmail 过滤器一次性导出为 Gmail WebUI 可直接导入的 XML 文件或导出为符合 Gmail API 结构的 JSON用于备份、迁移与脚本化处理。读完本文你将掌握该命令的完整用法、全部标志参数、XML 与 JSON 两种输出格式的区别以及其底层实现原理从 API 拉取、标签 ID 到名称的反查到 Atom/apps 命名空间的序列化过程。命令定位过滤器家族中的导出能力在gogcli的命令体系中Gmail 过滤器相关操作统一挂在gog gmail settings filters之下export是其子命令之一。完整的过滤器子命令族包括gog gmail settings filters create— 创建新过滤器别名add,newgog gmail settings filters delete— 删除过滤器别名rm,del,removegog gmail settings filters export— 将过滤器导出为 Gmail WebUI 兼容 XML本文主题gog gmail settings filters get— 获取单个过滤器别名info,showgog gmail settings filters list— 列出全部过滤器别名ls在 internal/cmd/gmail_filters.go 的GmailFiltersCmd结构体中可以看到export子命令与list、get、create、delete平级且GmailFiltersExportCmd只声明了--out与--format两个专有标志其余均为全局通用标志。基本用法export命令的标准调用形式为gog gmail (mail,email) settings filters export [flags]其中(mail,email)表示gmail关键字可以用mail或email替换三种写法等价。导出为 Gmail WebUI 兼容 XML默认默认--format为空时导出格式为 XML输出目标是标准输出stdout。官方工作流文档 docs/gmail-workflows.md 推荐将结果写入文件便于直接导入 Gmail 网页端gog gmail settings filters export --out filters.xml不带--out时XML 直接打印到终端适合预览gog gmail settings filters export导出为 Gmail API JSON当脚本需要 Gmail API 原生结构时使用--format jsongog gmail settings filters export --format json --json注意这里同时使用了--format json和全局--json--format决定导出内容的序列化格式--json则让命令整体以 JSON 模式工作后者是多数 gogcli 命令的标准 JSON 开关。格式选择规则源码确认在 internal/cmd/gmail_filters.go 中格式解析逻辑如下若--format为空默认xml但当未指定--out且处于 JSON 输出模式outfmt.IsJSON(ctx)时默认改为json——这是为了兼容只传--json的老写法--format只接受xml或json否则报usage(--format must be xml or json)。也就是说gog gmail settings filters export --json也能直接输出 JSON等价于--format json。若同时给出--format xml --json则仍输出 XML--format优先。两种导出格式详解XMLGmail WebUI 可直接导入的格式XML 导出采用 Atom 订阅源feed结构融合了 Google Apps 命名空间正是 Gmail 网页端「设置 → 过滤器 → 导入过滤器」功能所期望的格式。由 internal/cmd/gmail_filters_export.go 可见两个命名空间常量?xml version1.0 encodingUTF-8? feed xmlnshttp://www.w3.org/2005/Atom xmlns:appshttp://schemas.google.com/apps/2006每个过滤器对应一个entry其中apps:property属性对完整描述了筛选条件与动作。以TestGmailFiltersExport见 internal/cmd/gmail_filters_cmd_test.go构造的示例过滤器为例导出的 XML 核心片段为entry category termfilter/ titleMail Filter/title idtag:mail.google.com,2008:filter:f1/id apps:property namefrom valueaexample.com/ apps:property nameto valuebexample.com/ apps:property namesubject valueAamp;B/ apps:property namehasTheWord valuefrom:alerts has:attachment/ apps:property namedoesNotHaveTheWord valuecategory:promotions/ apps:property namehasAttachment valuetrue/ apps:property nameexcludeChats valuetrue/ apps:property namesize value1024/ apps:property namesizeUnit values_sb/ apps:property namesizeOperator values_sl/ apps:property nameshouldStar valuetrue/ apps:property nameshouldAlwaysMarkAsImportant valuetrue/ apps:property namesmartLabelToApply value^smartlabel_social/ apps:property nameshouldArchive valuetrue/ apps:property nameshouldMarkAsRead valuetrue/ apps:property nameshouldNeverSpam valuetrue/ apps:property namelabel valueNotifications amp; Alerts/ apps:property nameforwardTo valuefexample.com/ /entry从源码实现看XML 序列化由marshalGmailFiltersXML完成internal/cmd/gmail_filters_export.go它做了几件关键事情feed 级元数据title固定为Mail Filtersid使用tag:mail.google.com,2008:filters:毫秒时间戳保证唯一性updated取导出时刻的 UTC RFC3339 时间author.name与author.email均为当前账号账户参数来自requireGmailService返回的account。XML 转义通过 Go 标准库encoding/xml编码器自动转义例如测试断言中的AB输出为Aamp;B标签名Notifications Alerts输出为Notifications amp; Alerts保证特殊字符不会破坏 XML 结构。缩进与编码使用enc.Indent(, )两级空格缩进先写入 XML 头再编码 feed末尾追加换行。筛选条件Criteria属性映射gmailFilterCriteriaXMLPropertiesinternal/cmd/gmail_filters_export.go负责把 Gmail API 的FilterCriteria映射为 XML 属性API 字段XML 属性名说明Fromfrom发件人匹配Toto收件人匹配Subjectsubject主题匹配QueryhasTheWord高级搜索查询包含词NegatedQuerydoesNotHaveTheWord排除词查询HasAttachmenthasAttachment值固定为trueExcludeChatsexcludeChats排除聊天值固定为trueSizeSizeComparisonsize/sizeUnit/sizeOperator尺寸条件sizeUnit固定s_sbsizeComparison为larger时sizeOperators_slsmaller时s_ss动作Action属性映射与系统标签语义gmailFilterActionXMLPropertiesinternal/cmd/gmail_filters_export.go将动作字段映射为 Gmail WebUI 语义来自AddLabelIds加标签动作标签 IDXML 属性STARREDshouldStartrueIMPORTANTshouldAlwaysMarkAsImportanttrueTRASHshouldTrashtrueCATEGORY_PERSONAL等智能分类smartLabelToApply^smartlabel_personal等普通标签 IDlabel 标签名称ID 反查为可读名称来自RemoveLabelIds移除标签动作标签 IDXML 属性INBOXshouldArchivetrue归档即移出收件箱UNREADshouldMarkAsReadtrueSPAMshouldNeverSpamtrue永不标记为垃圾邮件IMPORTANTshouldNeverMarkAsImportanttrue其余标签统一走label属性。注意AddLabelIds中的STARRED/IMPORTANT/TRASH与RemoveLabelIds中的INBOX/UNREAD/SPAM/IMPORTANT都对应 Gmail 的系统标签system label导出时被翻译成 WebUI 可识别的动作属性——这正是「WebUI 兼容」的核心所在。智能标签映射由gmailFilterSmartLabelXMLValueinternal/cmd/gmail_filters_export.go完成API 分类标签 IDXML 值CATEGORY_PERSONAL^smartlabel_personalCATEGORY_SOCIAL^smartlabel_socialCATEGORY_PROMOTIONS^smartlabel_promoCATEGORY_UPDATES^smartlabel_notificationCATEGORY_FORUMS^smartlabel_group标签 ID → 名称反查marshalGmailFiltersXML会先调用fetchLabelIDToNameinternal/cmd/gmail_labels.go调用Users.Labels.List(me)拉取全部标签建立标签ID → 标签名称映射导出普通标签动作时XML 中使用人类可读的标签名称而非晦涩的 ID确保导入 Gmail WebUI 后标签仍然有效。JSON保持 Gmail API 原生结构--format json输出的是 Gmail API 返回的过滤器原始结构包含id、criteria、action三个顶层字段外包一层{filters: [...]}容器见 internal/cmd/gmail_filters.go。典型的 JSON 输出片段{ filters: [ { id: f1, criteria: { from: aexample.com, to: bexample.com, subject: AB, query: from:alerts has:attachment, negatedQuery: category:promotions, hasAttachment: true, excludeChats: true, size: 1024, sizeComparison: larger }, action: { addLabelIds: [Label_1, STARRED, IMPORTANT, CATEGORY_SOCIAL], removeLabelIds: [INBOX, UNREAD, SPAM], forward: fexample.com } } ] }行为差异源码确认当 JSON 格式且未指定--out时通过outfmt.WriteJSON直接输出到 stdout当指定了--out时使用json.MarshalIndent以两空格缩进写入文件internal/cmd/gmail_filters.go。JSON 模式适合后续用jq、脚本或 AI Agent 继续加工。完整标志参考export命令除两个专有标志外还继承 gogcli 的全局标志体系。下表完整列出信息源自命令文档 docs/commands/gog-gmail-settings-filters-export.mdFlagTypeDefaultHelp--access-tokenstringUse provided access token directly (bypasses stored refresh tokens; token expires in ~1h)-a--account--acctstringAccount email, alias, or auto for authenticated Google API commands--clientstringOAuth client name (selects stored credentials token bucket)--colorstringautoColor output: auto|always|never--disable-commandsstringComma-separated list of disabled commands; dot paths allowed-n--dry-run--dryrun--noop--previewboolDo not make changes; print intended actions and exit successfully--enable-commandsstringComma-separated list of enabled command prefixes; dot paths allowed (restricts CLI)--enable-commands-exactstringComma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children-y--force--assume-yes--yesboolSkip confirmations for destructive commands--formatstringExport format: xml or json (default: xml; --json without --out uses json for compatibility)--gmail-no-sendboolfalseBlock Gmail send operations (agent safety)-h--helpkong.helpFlagShow context-sensitive help.--homestringOverride gogcli config/data/state/cache root (equivalent to GOG_HOME)-j--json--machineboolfalseOutput JSON to stdout (best for scripting)--no-input--non-interactive--noninteractiveboolNever prompt; fail instead (useful for CI)-o--outstringWrite export to this file (defaults to stdout)-p--plain--tsvboolfalseOutput stable, parseable text to stdout (TSV; no colors)--quota-projectstringGoogle Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC)--readonlyboolfalseBlock mutating API requests at runtime; auth add also requests read-only OAuth scopes--results-onlyboolIn JSON mode, emit only the primary result (drops envelope fields like nextPageToken)--select--pick--projectstringIn JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands.-v--verboseboolEnable verbose logging--versionkong.VersionFlagPrint version and exit--wrap-untrustedboolfalseIn JSON/raw output, wrap fetched text fields in external untrusted-content markers其中与export命令关系最紧密的几个标志--out-o导出文件路径。源码中会先经config.ExpandPath展开路径支持~等扩展再写入文件若未提供则输出到 stdoutinternal/cmd/gmail_filters.go。--formatxml或json默认xml特殊兼容逻辑见上文。--account-a/--acct指定账号邮箱、别名或auto。导出的 XML 中author元素会使用该账号作为作者邮箱因此指定正确账号会影响 XML 元数据内容。--dry-runexport同样支持 dry-run 语义——打印将要导出的格式与目标位置stdout 或文件后直接退出不会真正访问 Gmail API。实现见dryRunExit(ctx, flags, gmail.filters.export, ...)internal/cmd/gmail_filters.go。--json/--plain控制整体输出形态与--format相互独立。底层调用链与实现原理export的执行流程internal/cmd/gmail_filters.go可拆解为 7 步参数校验解析--format与--out非法格式直接报错展开输出路径dry-run 短路若开启--dry-run打印{format: ..., out: ...}计划并成功退出加载 Gmail 服务requireGmailService(ctx, flags)依据账号与 OAuth 客户端配置初始化 Gmail API 客户端拉取过滤器调用svc.Users.Settings.Filters.List(me).Do()获取全部过滤器与list子命令同源规范化normalizeGmailFilters保证 nil 切片转为空切片internal/cmd/gmail_filters_helpers.go避免 JSON 输出null测试TestGmailFiltersExport_JSONEmptyArray验证了空账号导出{filters: []}而非null序列化JSON 直接封装输出XML 则先反查标签名再经marshalGmailFiltersXML生成 Atom feed写文件/输出无--out时写 stdout有--out时经createUserOutputFile创建用户目录下的文件写入成功后JSON 模式下输出{exported: true, path: ..., count: N, format: ...}信封文本模式下打印Exported N filters to path。该流程由 internal/cmd/gmail_filters_cmd_test.go 的TestGmailFiltersExport端到端覆盖测试用httptest模拟 Gmail APIlabels 与 filters 两个端点断言 XML 头、apps命名空间、全部属性对、XML 可回解析以及author.email正确性可作为理解命令行为的参考样例。典型应用场景备份与迁移定期将过滤器导出为 XML 存档迁移账号时在 Gmail 网页端「设置 → 过滤器 → 导入过滤器」直接导入gog gmail settings filters export --out ~/gmail-backup/filters-$(date %F).xml脚本化处理与审计结合--format json --json用 jq 等工具统计、筛选或二次加工# 查看所有转发类过滤器的目标地址 gog gmail settings filters export --format json --json | jq .filters[] | select(.action.forward ! null) | .action.forward无写入风险评估先用 dry-run 确认导出目标gog gmail settings filters export --out filters.xml --dry-run只读模式若只需备份而无需任何写操作可叠加--readonly从运行时层面阻断一切变更型 API 请求适合 CI 与自动化巡检。相关资源命令文档docs/commands/gog-gmail-settings-filters-export.md父命令gog gmail settings filters含 create/delete/get/list/export 完整子命令列表命令索引docs/commands/README.md工作流指南docs/gmail-workflows.mdFilters 一节给出导出、JSON 两种推荐用法源码实现internal/cmd/gmail_filters.go命令主体XML 序列化internal/cmd/gmail_filters_export.go过滤器公共辅助internal/cmd/gmail_filters_helpers.go标签 ID/名称反查internal/cmd/gmail_labels.go端到端测试internal/cmd/gmail_filters_cmd_test.goTestGmailFiltersExport及其子测试【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考