gogcli 草稿列表指南gog gmail drafts list 命令的完整用法与分页原理【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli导读gog gmail drafts list是 gogcliGoogle Workspace in your terminal中用于列出 Gmail 草稿的核心只读命令。本文以 docs/commands/gog-gmail-drafts-list.md 为主线系统讲解该命令的调用形式、全部可用标志Flag及其含义并结合 gmail_drafts.go 与 paged_list_helpers.go 等源码深入剖析分页抓取、--max/--limit数量限制、JSON 输出结构以及--fail-empty非零退出码的底层实现。读完本文你将能在终端中熟练列出、筛选与脚本化消费 Gmail 草稿列表。说明该命令的文档页面由gog schema --json自动生成仓库中标注“Do not edit this page by hand; runmake docs-commands”因此本文所有参数均与 internal/cmd/gmail_drafts.go 中的命令结构体定义保持一致。命令概览从父命令到子命令gog gmail drafts list位于gmail → drafts → list的命令层级中其父命令为 gog gmail drafts该父命令同时管理草稿的 create / get / delete / send / update / reply / reply-all / forward 等操作。在源码中父命令定义为type GmailDraftsCmd struct { List GmailDraftsListCmd cmd: name:list aliases:ls help:List drafts Get GmailDraftsGetCmd cmd: name:get aliases:info,show help:Get draft details Delete GmailDraftsDeleteCmd cmd: name:delete aliases:rm,del,remove help:Permanently delete a draft (not recoverable; drafts are not moved to Trash) Send GmailDraftsSendCmd cmd: name:send aliases:post help:Send a draft Create GmailDraftsCreateCmd cmd: name:create aliases:add,new help:Create a draft Update GmailDraftsUpdateCmd cmd: name:update aliases:edit,set help:Update a draft Reply GmailDraftsReplyCmd cmd: name:reply help:Save a reply as a draft ReplyAll GmailDraftsReplyAllCmd cmd: name:reply-all aliases:replyall help:Save a reply-all as a draft Forward GmailDraftsForwardCmd cmd: name:forward aliases:fwd help:Save a forward as a draft }list子命令本身还提供别名ls因此以下三种写法等价gog gmail drafts list gog gmail drafts ls gog gmail ls同时顶层还允许把gmail简写为mail或email、把drafts简写为draft。完整的规范用法如下gog gmail (mail,email) drafts (draft) list (ls) [flags]命令专属标志控制返回数量、分页与空结果行为与gog gmail drafts父命令共享的全局标志不同list子命令在源码 gmail_drafts.go 中只声明了四个专属标志标志类型默认值说明--max--limitint6420每页最大结果数--page--cursorstring空分页游标page token用于翻页--all--all-pages--allpagesboolfalse自动抓取全部页面直到结束--fail-empty--non-empty--require-resultsboolfalse无结果时以退出码 3 结束下面逐个深入讲解其实现与使用要点。--max / --limit单页返回上限必须大于 0--max别名--limit默认值为20决定每次向 Gmail API 请求的maxResults。Run方法在一开始就会调用校验函数if err : validateGmailMaxResults(c.Max); err ! nil { return err }该校验定义在 gmail_search_request.gofunc validateGmailMaxResults(maxResults int64) error { if maxResults 0 { return usage(--max must be 0) } return nil }因此--max 0或负数会被直接拒绝并给出--max must be 0的错误信息。增大该值可减少分页往返次数但 Gmail API 本身对单次列表请求也有上限约束实际使用时建议根据草稿规模在 20500 之间权衡。注意--max只控制单页大小若要一次性取回全部草稿应配合下面的--all使用。--page / --cursor手动分页游标--page别名--cursor用于从指定页码游标继续拉取。源码中会把非空的 page token 透传给 Gmail APIfetch : func(pageToken string) ([]*gmail.Draft, string, error) { call : svc.Users.Drafts.List(me).MaxResults(c.Max).Context(ctx) if strings.TrimSpace(pageToken) ! { call call.PageToken(pageToken) } resp, callErr : call.Do() ... }也就是说命令内部通过Users.Drafts.List(me)调用 Gmail API使用固定的me作为用户标识即以当前登录账号为准。第一次调用无需携带--page每页返回的nextPageToken可在文本输出中看到提示见下文“分页与空结果提示”将其填入--page即可继续获取下一页。--all / --all-pages自动抓取全部分页--all别名--all-pages、--allpages会把分页逻辑交给统一的 loadPagedItemsfunc loadPagedItemsT any ([]T, string, error) { if all { items, err : collectAllPages(page, fetch) ... } return fetch(page) }collectAllPages进一步调用 collectPages其行为要点包括循环调用fetch直到返回的nextPageToken为空内置pageTokenGuard去重保护防止分页循环导致死循环单次调用最多抓取10_000页作为兜底上限collectAllPages传入maxPages10_000。因此--all适合脚本化地一次性导出全部草稿 ID例如gog gmail drafts list --all --json--fail-empty无结果时退出码为 3--fail-empty别名--non-empty、--require-results用于 CI 与脚本中判断“是否没有任何草稿”。其实现位于 paging.goconst emptyResultsExitCode 3 func failEmptyExit(failEmpty bool) error { if !failEmpty { return nil } return ExitError{Code: emptyResultsExitCode, Err: nil} }当列表为空且设置了该标志时命令以退出码3结束0表示成功非 0表示出错或条件未满足因此3为“结果为空”保留了语义化的独立退出码方便上层脚本区分“命令执行失败”与“没有数据”两种情形。共享的全局标志身份、输出与安全list命令继承父命令gog gmail drafts的全部全局标志。除上表列出的四个专属标志外实际执行时最常配合使用的是以下几组账号与认证相关标志类型默认值说明-a--account--acctstring空账号邮箱、别名或auto用于已认证的 Google API 命令--clientstring空OAuth 客户端名称选择已存储的凭据与 token 桶--access-tokenstring空直接使用提供的 access token绕过已存储的 refresh tokentoken 约 1 小时过期--quota-projectstring空用于计费的 Google Cloud 项目作为X-Goog-User-Project请求头部分 API 在使用--access-token或 ADC 时必需多账号场景下--account ab.com可以精确指定要列出哪个账号的草稿也可以使用别名。若未指定则按配置选择默认账号。输出格式相关标志类型默认值说明-j--json--machineboolfalse以 JSON 输出到 stdout最适合脚本化处理-p--plain--tsvboolfalse以稳定的可解析纯文本输出到 stdoutTSV无颜色--results-onlybool空JSON 模式下只输出主要结果丢弃nextPageToken等信封字段--select--pick--projectstring空JSON 模式下按逗号分隔选择字段尽力而为支持点路径多数命令推荐改用--fields--colorstringauto颜色输出策略auto/always/never安全与交互相关标志类型默认值说明--readonlyboolfalse运行时拦截所有变更类 API 请求auth add也只会请求只读 OAuth 作用域--gmail-no-sendboolfalse阻断 Gmail 发送类操作Agent 安全开关-n--dry-run--noop--previewbool空不执行变更只打印将要执行的动作并成功退出-y--force--assume-yesbool空跳过破坏性命令的确认提示--no-input--non-interactivebool空永不提示直接失败适合 CI--wrap-untrustedboolfalse在 JSON/raw 输出中为抓取到的文本字段包裹外部不可信内容标记由于list本身是只读命令--dry-run与--readonly对其影响较小但同一父命令下的delete、send等操作会严格受-y/--force、--readonly、--gmail-no-send约束。另有--disable-commands、--enable-commands、--enable-commands-exact以点路径限定命令白名单、--home覆盖 gogcli 的 config/data/state/cache 根目录等价于GOG_HOME、-v/--verbose、--version、-h/--help等通用标志完整列表见 gog-gmail-drafts-list.md。输出解析表格输出、JSON 结构与空结果提示默认文本输出ID 与 MESSAGE_ID 两列非 JSON 模式下命令通过outfmt.WriteTable输出表格列定义位于 gmail_presentation.gofunc gmailDraftColumns() []outfmt.Column[*gmail.Draft] { return []outfmt.Column[*gmail.Draft]{ {Header: ID, Value: func(draft *gmail.Draft) string { return draft.Id }}, {Header: MESSAGE_ID, Value: func(draft *gmail.Draft) string { if draft.Message nil { return } return draft.Message.Id }}, } }即默认表格包含ID草稿 ID与MESSAGE_ID对应消息 ID无消息时为空两列。compactGmailRows会先过滤掉响应中的空指针条目见 gmail_presentation.go避免 nil 行导致渲染异常。JSON 输出drafts 数组 信封字段加--json后输出结构定义在 gmail_drafts.gotype item struct { ID string json:id MessageID string json:messageId,omitempty ThreadID string json:threadId,omitempty }每条草稿被整理为id、messageId可选、threadId可选三个字段整体包裹在信封对象中{ drafts: [ { id: r123456789, messageId: 18abc..., threadId: 18abc... } ], nextPageToken: 0... }nextPageToken即为翻页游标若配合--results-only该信封字段会被丢弃只输出drafts主体方便下游直接消费。测试用例 execute_gmail_more_commands_test.go 中即以--json --account ab.com gmail drafts list的形式对列表、get、create、update、send、delete 等草稿全链路进行了端到端验证。分页与空结果提示若当前页仍有下一页命令会通过printNextPageHintWithAll打印提示告知可继续使用--page token翻页或改用--all/--all-pages一次抓全见 output_helpers.go当列表为空且未指定--fail-empty时文本模式会在 stderr 打印No drafts并正常退出退出码 0指定--fail-empty后则以退出码3结束JSON 模式下空结果同样通过writePagedJSONResult输出信封drafts为空数组并根据--fail-empty决定是否以退出码 3 结束见 paged_list_helpers.go。实战示例列出当前账号前 20 条草稿gog gmail drafts list列出草稿并输出为 JSON便于 jq 处理gog gmail drafts list --json指定账号与单页数量gog gmail drafts list --account meexample.com --max 50一次性抓取全部草稿 IDgog gmail drafts list --all --json --results-only在 CI 脚本中判断“是否有草稿”无结果时退出码为 3gog gmail drafts list --fail-empty --json延伸阅读父命令与同层级子命令gog gmail draftscreate / get / delete / send / update / reply / reply-all / forwardGmail 系列命令入口gog gmail全部命令索引Command index核心实现internal/cmd/gmail_drafts.goGmailDraftsListCmd定义于 L31-L36Run方法于 L38-L102分页基础设施internal/cmd/paged_list_helpers.go 与 internal/cmd/paging.go--all全量抓取、--fail-empty退出码 3、页游标去重保护输出列定义internal/cmd/gmail_presentation.go数量校验internal/cmd/gmail_search_request.go【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考