gogcli `gog youtube subscriptions list` 命令完全指南：分页、输出格式与源码实现解析

gogcligog youtube subscriptions list命令完全指南分页、输出格式与源码实现解析【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog youtube subscriptions list别名gog yt subscriptions ls是 gogcli 中用于列出已认证用户authenticated user所订阅频道的只读命令。它通过 OAuth 账户身份调用 YouTube Data API v3 的subscriptions.list并支持单页读取、全量分页拉取以及表格 / JSON 多种输出模式是订阅管理配合subscribe/unsubscribe与自动化脚本中最常用的人口命令之一。读完本文你将掌握该命令的全部参数、分页与输出机制并能从源码与测试层面理解其实现细节。命令定位为什么订阅列表必须使用账户 OAuth与gog yt videos list、gog yt channels list等可以用API key读取公开数据的命令不同订阅列表属于按用户per-user读取subscriptions.list必须携带minetrue参数只有登录用户的 OAuth 身份才能查询因此不能使用 API key 模式。该命令在命令树中的位置internal/cmd/youtube.gotype YouTubeSubscriptionsCmd struct { List YouTubeSubscriptionsListCmd cmd: name:list aliases:ls help:List subscriptions for authenticated user Subscribe YouTubeSubscriptionsSubscribeCmd cmd: name:subscribe help:Subscribe to a channel Unsubscribe YouTubeSubscriptionsUnsubscribeCmd cmd: name:unsubscribe help:Unsubscribe from a channel }官方用法完整命令名圆括号内为可省略的别名gog youtube (yt) subscriptions (subscription) list (ls) [flags]也就是说gog yt subscriptions list、gog youtube subscription ls、gog youtube subscriptions list三种写法等价。从源码看命令执行的第一步是强制要求账户参数internal/cmd/youtube.goaccount, err : requireAccount(flags) if err ! nil { return err } svc, err : getYouTubeServiceForAccount(ctx, account) if err ! nil { return err }随后通过getYouTubeServiceForAccountinternal/cmd/youtube_services.go构建服务最终经由NewYouTubeForAccountinternal/googleapi/youtube.go以 OAuth 身份初始化 YouTube Data API v3 客户端。这里使用的是youtube服务默认的youtube.readonly只读 scope见 internal/googleauth/service.go无需额外申请youtube.force-ssl扩展 scope——只有订阅/播放列表的写入操作才需要。前置配置添加 YouTube 账户在运行本命令前需要先完成账户授权详见 docs/youtube.mdgog auth add yougmail.com --services youtube gog yt subscriptions list --max 50 --account yougmail.com基本用法与快速验证最简单的调用只需指定账户gog yt subscriptions list --account yougmail.com输出为表格形式表头固定为ID CHANNEL_ID TITLE SUBSCRIBED_AT对应源码中的fmt.Fprintln(w, ID\tCHANNEL_ID\tTITLE\tSUBSCRIBED_AT)见 internal/cmd/youtube.go。每行包含订阅 ID、被订阅频道的 Channel ID、频道标题以及订阅时间其中 Channel ID 取自订阅的snippet.resourceId.channelIdprintSubscriptionRow。当没有任何订阅时命令不会报错而是在 stderr 输出一行No subscriptions后正常退出internal/cmd/youtube.go方便脚本据此判断空结果。Flags 全量参考表本命令继承了 gogcli 的全局根级 flags并附加了三个订阅列表专属参数--max、--page、--all。以下为完整参数表默认值均与当前仓库生成的命令参考 gog-youtube-subscriptions-list.md 保持一致FlagTypeDefaultHelp--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--all--all-pages--allpagesboolFetch all pages--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--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)--max--limitint6450Max results per page--no-input--non-interactive--noninteractiveboolNever prompt; fail instead (useful for CI)--page--cursorstringPage token-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与订阅列表强相关的三个专属参数订阅列表命令自身的参数结构定义在 internal/cmd/youtube.gotype YouTubeSubscriptionsListCmd struct { Max int64 name:max aliases:limit help:Max results per page default:50 Page string name:page aliases:cursor help:Page token All bool name:all aliases:all-pages,allpages help:Fetch all pages }--max/--limit默认 50每页返回的最大订阅数。注意该值存在硬性校验validateYouTubeMax要求1 --max 50超出范围会直接提示--max must be between 1 and 50internal/cmd/youtube.go。这是 YouTube Data API 对maxResults的上限约束。--page/--cursor分页游标传入上一页返回的nextPageToken即可从指定位置继续读取。--all/--all-pages/--allpages是否自动抓取所有页。开启后命令会循环请求直到没有下一页无需手动拼接 token适合订阅数量很多的频道关注者。分页机制单页读取 vs 全量拉取订阅列表的核心调用链在Run方法中internal/cmd/youtube.gofetch : func(pageToken string) ([]*youtube.Subscription, string, error) { resp, callErr : svc.Subscriptions.List([]string{snippet}). Mine(true). MaxResults(c.Max). PageToken(pageToken). Do() if callErr ! nil { return nil, , callErr } return youtubeItemsOrEmpty(resp.Items), resp.NextPageToken, nil } items, nextPageToken, err : loadPagedItems(c.Page, c.All, fetch)三个要点Mine(true)是订阅列表的语义核心它告诉 YouTube API 返回当前认证用户的订阅这是该命令只能走账户 OAuth 的根因。part 固定为snippet命令只请求snippet字段含标题、订阅时间、被订阅频道的 resourceId不请求contentDetails等更重的内容保证列表响应轻量。分页逻辑由通用助手loadPagedItems承载internal/cmd/paged_list_helpers.go--all开启时调用collectAllPages循环翻页并合并全部结果此时nextPageToken为空否则只抓取当前页并原样透传下一页 token。翻页的实用写法方式一手动逐页单页 50 条gog yt subscriptions list --account yougmail.com --max 50 gog yt subscriptions list --account yougmail.com --max 50 --page NEXT_PAGE_TOKEN方式二全量拉取适合脚本与数据迁移gog yt subscriptions list --all --account yougmail.com --json方式三分页批量落地到文件for t in $(gog yt subscriptions list --account yougmail.com --json | jq -r .nextPageToken // empty); do gog yt subscriptions list --account yougmail.com --page $t --json subs.jsonl done输出格式表格、TSV 与 JSON命令根据输出标志自动切换格式internal/cmd/youtube.go默认终端表格Tab 分隔的文本行表头ID CHANNEL_ID TITLE SUBSCRIBED_AT若还有下一页会在 stderr 提示--all/--all-pages以便继续翻页printNextPageHintWithAll见 internal/cmd/output_helpers.go。--json/-j输出结构化的{items: [...], nextPageToken: ...}信封结构nextPageToken直接供--page回传使用gog yt subscriptions list --all --account yougmail.com --json--plain/-p输出稳定的 TSV无颜色、无额外修饰适合管道处理。--results-only在 JSON 模式下只输出主结果数组丢弃nextPageToken等信封字段适合只关心数据本身的场景。--select在 JSON 模式下按逗号分隔的字段支持点路径做尽力而为的字段裁剪。此外人类可读的进度、提示与警告信息一律输出到stderr保证 stdout 纯净、可被程序直接消费——这是 gogcli 面向自动化设计的统一约定参见 docs/youtube.md 的Automation and safety小节。源码与测试印证仓库中的单元测试直接验证了本命令的关键行为。以 internal/cmd/youtube_test.go 中的TestYouTubeSubscriptionsListMine为例断言请求路径为/youtube/v3/subscriptions且查询参数minetrue、maxResults2对应--max 2通过注入的Account服务工厂断言账户参数被正确传递meexample.com校验 stdout 包含订阅 IDSUB123、频道 IDUCcool与标题Cool Channel校验nextPageTokentok1作为翻页提示出现在 stderr 中。这从测试层面确认了账户参数 → OAuth 服务 →minetrue请求 → 表格输出 翻页提示的完整链路。结合订阅管理闭环使用subscriptions list返回的订阅 IDSUB123之类的值是unsubscribe --id的直接输入也可以直接使用列表中的 Channel ID 通过unsubscribe --channel-id退订gogcli 会自动帮你做订阅查找。因此一个典型的管理闭环是# 1. 全量导出当前订阅 gog yt subscriptions list --all --account yougmail.com --json subs.json # 2. 从订阅 ID 退订 gog yt subscriptions unsubscribe --id SUBSCRIPTION_ID --account yougmail.com --force # 3. 从频道 ID 订阅新频道 gog yt subscriptions subscribe --channel-id UC_x5XG1OV2P6uZZ5FSM9Ttw --account yougmail.com订阅与退订均支持--dry-run预演不会发起网络请求退订为破坏性操作默认要求确认自动化场景请显式组合--no-input --force。关于subscribe/unsubscribe的完整参数可查阅 gog-youtube-subscriptions.md 及其子命令参考YouTube 模块的整体配置API key、scope、权限问题参见 docs/youtube.md。命令总索引位于 docs/commands/README.md。常见问题与注意事项account required错误本命令不支持 API key 模式必须提供--account或--acct、配置默认账户。这是requireAccount的硬性约束。--max超出 50 被拒绝YouTube Data API 的maxResults上限为 50gogcli 在本地即拦截不会发起到 Google 的无效请求。空订阅列表不是错误输出No subscriptions到 stderr 并正常退出脚本中可通过 stderr 内容或 JSON 空数组判断。youtubeSignupRequired若账户尚未拥有 YouTube 频道相关读取可能报此错误需先在 YouTube 站点初始化频道后重试见 docs/youtube.md。--results-only与分页该标志会丢弃nextPageToken如果同时需要全量数据请优先使用--all一次性拉完。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考