YuE2模型部署实战：AR-NAR混合架构落地指南
2026/9/17 8:27:27
gogcligog classroom students list命令完全指南：在终端中查询 Google Classroom 学生名单
【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli
本篇技术指南围绕 gogcli（Google Workspace in your terminal）的gog classroom students list命令展开，讲解如何通过终端快速列出指定 Google Classroom 课程的学生名单，包括命令语法、全部可用标志（Flags）、分页与 JSON 输出、--fail-empty脚本化退出码以及底层分页实现原理。读完本指南，你将能在日常管理与自动化脚本中熟练使用该命令，并理解其与 classroom API 的映射关系。
gog classroom students list是 gogcli 中面向 Google Classroom 课程花名册（Roster）管理的只读查询命令，归属于gog classroom students子命令组，该组还包含get（查询单个学生）、add（添加学生）、remove（移除学生）三个操作，见 gog-classroom-students.md。列表查询本身不会修改任何数据，因此非常适合用于巡检、导出与 CI 集成。
命令语法与别名
gog classroom (class) students (student) list (ls) <courseId> [flags]该语法中的括号表示命令级别名（alias）：
classroom可缩写为class；students可缩写为student；list可缩写为ls。
因此下面三种写法完全等价：
gog classroom students list <courseId> gog class student list <courseId> gog classroom students ls <courseId>别名定义在源码 internal/cmd/classroom.go（ClassroomCmd中Students的aliases:"student"）与 internal/cmd/classroom_rosters.go（ClassroomStudentsCmd.List声明为default:"withargs" aliases:"ls"）。需要说明的是，由于list是students组的默认子命令（default:"withargs"），gog classroom students <courseId>这种省略list的写法同样会被解析为列出学生。
<courseId>是唯一的必填位置参数（positional argument），它对应 Google Classroom API 中的 course ID，也接受课程别名（alias），其定义见 internal/cmd/classroom_rosters.go 中CourseID string字段的arg:"" name:"courseId"声明。
分页与结果控制标志
gog classroom students list专有的分页与结果控制标志定义在ClassroomStudentsListCmd结构体中，直接映射到 Google Classroom API 的courses.students.list接口（分页字段为pageSize/pageToken/nextPageToken）。
| 标志 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--max--limit | int64 | 100 | 单页最多返回的学生数，作为 API 的pageSize传入；取值必须大于 0，否则命令报max must be > 0 |
--page--cursor | string | （空） | 分页令牌（page token），用于从指定页继续拉取；令牌来自上一轮输出的nextPageToken |
--all--all-pages--allpages | bool | false | 自动翻页拉取全部学生，忽略nextPageToken分页 |
--fail-empty--non-empty--require-results | bool | false | 当结果为空时以退出码 3 结束，便于脚本判断"无结果"状态 |
这四个标志的解析逻辑位于 internal/cmd/classroom_rosters.go，其中Run方法将参数装配成classroomPagedListOptions后交给通用分页器runClassroomPagedList执行（见 internal/cmd/classroom_list_helpers.go）。
分页行为解析
分页核心由 internal/cmd/paged_list_helpers.go 的loadPagedItems实现：
- 未开启
--all：只请求当前页，返回该页学生列表及nextPageToken（若还有下一页）； - 开启
--all：循环调用collectAllPages直至翻完所有页，此时结果不再附带nextPageToken。
实际发起 API 请求的是 internal/cmd/classroom_list_helpers.go 的fetchClassroomStudentPage，它调用svc.Courses.Students.List(courseID).PageSize(pageSize).PageToken(pageToken)，读取响应中的Students与NextPageToken。当返回内容有更多页时，非 JSON 模式下会在 stderr 输出类似# Next page: --page <token>的提示（--all/--all-pages可跳过翻页）。
注意：Google Classroom API 单次
pageSize的上限为 1000，而本命令默认--max 100。若课程人数较多，建议显式增大--max或直接使用--all一次性获取完整名单。
输出格式：表格、TSV 与 JSON
gog classroom students list的输出由 gogcli 的 outfmt 组件统一管理，核心命令标志如下：
| 标志 | 类型 | 默认值 | 说明 |
|---|---|---|---|
-j--json--machine | bool | false | 输出 JSON 到 stdout，最适合脚本处理 |
-p--plain--tsv | bool | false | 输出稳定的 TSV 纯文本（无颜色），便于 parse |
--results-only | bool | （空） | JSON 模式下只输出主结果，去掉nextPageToken等信封字段 |
--select--pick--project | string | （空） | JSON 模式下按逗号分隔选择字段（支持点路径，尽力而为） |
--color | string | auto | 颜色输出：auto/always/never |
默认表格输出
默认情况下按表格输出三列，列定义见 internal/cmd/classroom_presentation.go 的classroomStudentColumns：
| 列名 | 数据来源 |
|---|---|
USER_ID | student.UserId，Google Classroom 的学生用户 ID |
EMAIL | profileEmail(student.Profile)，即UserProfile.EmailAddress |
NAME | profileName(student.Profile)，优先取Name.FullName，否则拼接 GivenName + FamilyName |
姓名/邮箱的取值辅助函数profileName与profileEmail定义在 internal/cmd/classroom_helpers.go。
JSON 输出（脚本友好）
gog classroom students list <courseId> --jsonJSON 负载为信封结构：{"students": [...], "nextPageToken": "..."}。其中students是 Google Classroom API 的Student对象数组（含userId、profile、studentWorkFolder等完整字段）。nextPageToken存在时表示还有更多页，可作为下一轮--page的值；追加--results-only可只保留students主结果，方便 jq 等工具直接消费：
gog classroom students list <courseId> --json --results-only信封组装与--results-only的行为在 internal/cmd/classroom_list_helpers.go 的writeClassroomPagedList中实现：JSON 模式下写jsonKey（此处为students）+nextPageToken，非 JSON 模式走表格渲染。
空结果与退出码
当没有学生时：
- 非 JSON 模式在 stderr 输出
No students，并提示用--all/--all-pages获取全部页； - 无论哪种输出格式，若指定了
--fail-empty，命令以退出码3结束（见 internal/cmd/paging.go 的failEmptyExit），未指定则正常退出码 0。
这在自动化巡检中非常实用，例如：
gog classroom students list <courseId> --json --fail-empty \ || [ $? -eq 3 ] && echo "该课程暂无学生"全局标志与认证
除命令专属标志外，所有 gogcli 命令共享一批全局标志，students list同样适用：
| 标志 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--access-token | string | （空） | 直接使用提供的访问令牌（绕过存储的 refresh token；令牌约 1 小时过期） |
-a--account--acct | string | （空） | 认证账号邮箱、别名或auto，用于所有 Google API 命令 |
--client | string | （空） | OAuth 客户端名称（选择存储的凭据与令牌桶） |
--quota-project | string | （空） | 计费用的 Google Cloud 项目（作为X-Goog-User-Project头发送；部分 API 在--access-token或 ADC 下需要它） |
--readonly | bool | false | 运行时阻止一切变更类 API 请求；auth add也会请求只读 OAuth scope |
--home | string | （空） | 覆盖 gogcli 配置/数据/状态/缓存根目录（等价于环境变量GOG_HOME） |
-n--dry-run--dryrun--noop--preview | bool | false | 不执行变更，仅打印预期操作并以成功退出（对只读命令无副作用） |
--gmail-no-send | bool | false | 阻止 Gmail 发送操作（Agent 安全开关） |
--enable-commands/--enable-commands-exact/--disable-commands | string | （空） | 按逗号分隔的命令前缀/精确路径启用或禁用命令，可限制 CLI 暴露范围 |
--no-input--non-interactive--noninteractive | bool | （空） | 禁止交互式提示，否则直接失败（适合 CI） |
-v--verbose | bool | false | 开启详细日志 |
--version | kong.VersionFlag | （空） | 打印版本并退出 |
-h--help | kong.helpFlag | （空） | 显示上下文相关的帮助信息 |
--wrap-untrusted | bool | false | JSON/raw 输出中，为抓取的外部文本字段加上"不可信内容"包裹标记 |
使用前需先完成认证：gog auth add <account> --services classroom，确保账号对目标课程具有查看学生名单的权限（老师身份）。认证与服务管理见 gog-auth.md 与 gog-auth-add.md。若遇到权限或启用问题，命令会给出针对性提示——internal/cmd/classroom_helpers.go 的wrapClassroomError会识别两类典型错误：
accessNotConfigured/Classroom API has not been used：提示先在 Google Cloud Console 启用 Classroom API；insufficientPermissions/insufficient authentication scopes：提示执行gog auth add <account> --services classroom重新授权。
使用示例
1. 列出某课程的学生（默认前 100 条）
gog classroom students list 1234567890 gog classroom students ls 1234567890 # 别名写法 gog classroom students 1234567890 # 默认子命令写法2. 一次性获取全部学生
gog classroom students list 1234567890 --all3. 增大单页大小并控制页大小
gog classroom students list 1234567890 --max 5004. 翻页遍历
先取第一页，记录输出的nextPageToken，再带入--page：
gog classroom students list 1234567890 --max 200 --json gog classroom students list 1234567890 --max 200 --page <nextPageToken>5. 输出 TSV 用于管道处理
gog classroom students list 1234567890 --plain | awk -F '\t' '{print $2}'6. 脚本化检查空课程
if gog classroom students list 1234567890 --json --fail-empty >/tmp/students.json 2>/dev/null; then echo "有学生，数量：$(jq '.students | length' /tmp/students.json)" else echo "退出码 $?：无学生或出错" fi底层实现与测试验证
从源码结构看，students list的实现是 gogcli 通用的"分页列表"模式的一个实例：
- 命令入口 internal/cmd/classroom_rosters.go 的
Run把courseId、max、page、all、failEmpty与 JSON 键名students组装进classroomPagedListOptions； - 通用分页器 internal/cmd/classroom_list_helpers.go 校验
courseId非空、max > 0，然后通过loadPagedItems（internal/cmd/paged_list_helpers.go）驱动分页循环； - 每页数据由
fetchClassroomStudentPage（internal/cmd/classroom_list_helpers.go）调用Courses.Students.List获取； - 最终由
writeClassroomPagedList（internal/cmd/classroom_list_helpers.go）按 JSON / 表格两种模式渲染，并处理空结果提示与--fail-empty退出码。
同一分页骨架也被classroom teachers list（fetchClassroomTeacherPage）、classroom topics list等命令复用，体现了 gogcli 对 Classroom 各列表类命令的统一抽象。
对应的测试在 internal/cmd/classroom_list_helpers_test.go 中：TestClassroomDirectListJSONEmptyArray通过 mock HTTP 服务模拟GET /courses/c1/students返回{"nextPageToken":""}，断言students键在 JSON 输出中序列化为[]而非null，保证脚本侧对空结果的解析稳定；测试还覆盖了 invitations 等其他列表命令的同一契约。此外 internal/cmd/classroom_presentation_test.go 验证了classroomStudentColumns的列渲染逻辑。
相关命令
- gog classroom students —— students 子命令组（add / get / list / remove）
- gog classroom students get —— 查询单个学生详情（含
StudentWorkFolder） - gog classroom students add —— 添加学生（支持
--enrollment-code） - gog classroom students remove —— 移除学生
- gog classroom roster —— 同时列出老师与学生的完整花名册
- gog classroom —— Classroom 命令组入口
- Command index —— 全部命令索引
【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考