【免费下载链接】App-Store-Connect-CLIFast, scriptable CLI for the App Store Connect API. Automate TestFlight, builds, submissions, signing, analytics, screenshots, subscriptions, and more项目地址https://gitcode.com/gh_mirrors/ap/App-Store-Connect-CLI点击查看免费下载本文基于仓库设计文档 docs/design/xcode-cloud-status-id-alias.md 展开并辅以命令实现、迁移指南与测试用例进行源码级印证。注意文档所描述的--id兼容别名已在 5.0.0 中移除asc xcode-cloud status目前只接受--run-id详见 migrate-to-5-0.mdx。导读asc xcode-cloud status是 App-Store-Connect-CLI 中用于查询 Xcode Cloud 构建运行build run状态的命令其核心入参是构建运行 ID。为了让从相邻 Xcode Cloud 命令如actions、artifacts、test-results、issues它们都用--run-id推断参数习惯的调用方平滑过渡项目曾在一段迁移窗口期内为它提供--id废弃别名。读完本文你将掌握为什么--run-id被定为唯一规范参数、别名在命令执行管线中的规范化时机、双拼写冲突的处理规则、5.0.0 移除别名的行为变化以及如何用源码与测试验证这些契约。背景asc xcode-cloud status的 build run 选择器Xcode Cloud 命令族以asc xcode-cloud subcommand组织覆盖触发、查询与管理构建运行的完整链路。命令参考见 commands/xcode-cloud.mdx其中status用于检查构建运行状态asc xcode-cloud status --run-id BUILD_RUN_ID asc xcode-cloud status --run-id BUILD_RUN_ID --output table asc xcode-cloud status --run-id BUILD_RUN_ID --wait asc xcode-cloud status --run-id BUILD_RUN_ID --wait --poll-interval 30s --timeout 1h从源码看status子命令由 internal/cli/xcodecloud/xcode_cloud.go 中的XcodeCloudStatusCommand()构造。flag 注册非常克制仅有五个Flag类型说明--run-id资源 IDBuild run ID必需通过shared.BindResourceIDFlag(fs, run-id, ciBuildRuns, ...)绑定--waitbool等待构建完成--poll-intervalduration等待时轮询间隔默认10s--timeoutdurationXcode Cloud 请求超时0 表示使用ASC_TIMEOUT或 30m 默认值--output/--prettystring/bool输出格式json、table、markdown及 JSON 美化执行逻辑中--run-id缺失时立即报错Error: --run-id is required并返回shared.MissingRequiredUsageError源码第 366-369 行随后才创建客户端、发起GET /v1/ciBuildRuns/{id}请求getCiBuildRun。这也印证了别名规范化必须先于必需参数检查这一设计约束——因为别名一旦存在就必须在是否缺参的判断之前完成归一。设计决策规范参数 废弃兼容别名的双轨策略设计文档给出的决策核心是asc xcode-cloud status始终以--run-id作为规范的 build run 选择器同时接受--id作为废弃的兼容别名。做出这一决策的直接动机来自对真实调用行为的观察重复的 Agent 调用显示调用方会从相邻的 Xcode Cloud 命令推断参数写法。也就是说一个写脚本的 Agent 看到asc xcode-cloud actions --run-id ...、asc xcode-cloud artifacts list --run-id ...、asc xcode-cloud test-results list --run-id ...后自然会推断status也用--run-id但另一些调用方看到workflows view --id、products view --id这类单数命名后则会写成status --id。两种拼写会在真实场景中长期共存与其让后一类调用直接失败不如在迁移窗口内提供别名让诊断信息逐步把调用方引导到规范参数上。该别名在迁移窗口内是可见的出现在命令帮助中而不是隐藏别名——设计文档明确说明别名在迁移窗口内可见于命令帮助因为重复的 Agent 调用显示调用方会从相邻 Xcode Cloud 命令推断它。这种可见废弃visible deprecation策略让用户与 Agent 都能在--help中直接发现规范拼写比静默吞掉别名更利于迁移。别名规范化时机早于一切副作用设计文档规定别名在必需输入检查、认证、HTTP 请求之前完成规范化。这一时序保证--id与--run-id在进入XcodeCloudStatusCommand的Exec前已被归一为同一个值规范化的过程不触发任何网络请求也不依赖认证状态——即使未配置凭证拼写错误也能以纯本地的方式被诊断出来后续所有环节缺参检查、GetASCClient、请求超时上下文只面对规范化后的--run-id。双拼写冲突即使用例相同也是用法错误设计文档特别强调同时提供两种拼写是用法错误usage error即使两个值相同也不行。也就是说asc xcode-cloud status --id run-1 --run-id run-1会被拒绝而不是被宽容地接受。理由很务实兼容别名存在的唯一目的是给旧调用方一个明确的迁移路径而不是让同一参数出现两种长期并存的拼写。一旦允许双拼写脚本就会开始混用未来的移除将变得异常困难。因此冲突诊断只提及规范参数名--run-id遥测telemetry中也只记录规范参数避免诊断与指标中出现别名拼写保持数据口径单一。兼容性与迁移警告、行为与发布说明在 4.x 迁移窗口期内行为契约如下仅使用--run-id的调用请求与 JSON 输出与之前完全一致无任何额外输出仅使用--id的调用执行完全相同的请求但向 stderr 打印一条警告Warning: --id is deprecated. Use --run-id.新脚本应直接使用asc xcode-cloud status --run-id BUILD_RUN_ID移除计划标准废弃窗口结束后下一个大版本中移除该别名。这一迁移过程被记录在发布说明 docs/release-notes-xcode-cloud-status-id-alias.md 中与设计文档互为印证发布说明面向升级读者给出警告文本、新写法示例与双拼写拒绝规则设计文档则解释决策依据与实现时机。5.0.0 移除从警告并继续到硬性用法错误设计文档顶部与发布说明均标注了状态该别名已在 5.0.0 中移除。移除后的行为不是仍接受但打印错误而是彻底不再注册该 flag——asc xcode-cloud status --id变为未知 flag。这符合 migrate-to-5-0.mdx 确立的总原则版本 5.0 移除了 4.x 在废弃警告后保留的每一个 CLI 侧兼容面把剩余的警告并继续输入变成硬性用法错误。未注册的 flag 会以退出码2退出。迁移文档的Removed flags表格中明确列出--idasc xcode-cloud status→ 替换为--run-id。在 cmd/removed_flags.go 中这一移除被登记为结构化条目{flag: id, commands: []string{xcode-cloud status}, replacement: --run-id},从 5.3.2 起这类已登记的移除 flag 在收到错误拼写时诊断信息会直接命名替换参数即给出--run-id的明确指引而非仅输出泛化的未知 flag 提示。退出码2ExitUsage无效用法定义于 cmd/exit_codes.go是全 CLI 统一的用法错误码。验证测试如何覆盖整条契约设计文档的 Verification 一节列举了完整的测试覆盖点这些点在 internal/cli/cmdtest/xcode_cloud_status_id_alias_test.go 中均有对应实现1. 规范路径--run-id无警告、单次请求、JSON 稳定TestXcodeCloudStatusRunIDReturnsJSONWithoutWarning用自定义http.DefaultTransport拦截网络层断言请求方法为GET请求路径精确等于/v1/ciBuildRuns/run-1对应ciBuildRuns资源与BindResourceIDFlag的ciBuildRuns资源类型一致使用--run-id时 stderr 为空无废弃警告请求计数为 1无多余探测请求JSON 输出中的buildRunId字段正确回显run-1。这验证了仅--run-id调用与既有行为完全一致的兼容性承诺。2. 移除路径--id未注册、退出码 2、零网络请求TestXcodeCloudStatusRejectsRemovedIDAliasAsUnknownFlagBeforeNetwork断言根命令与xcode-cloud status子命令的 FlagSet 中均查不到idLookup(id) nil证明别名已彻底注销--run-id仍然注册执行xcode-cloud status --id run-1返回ExitUsage退出码 2stdout 为空stderr 包含--id was removed in 5.0.0这一移除措辞的专用诊断并包含--run-id替换建议stderr 不再包含 deprecated 字样的废弃措辞因为别名已从废弃进入移除阶段网络传输层被断言为不允许任何请求——若发生网络调用测试直接失败证明该冲突在本地被拦截与别名规范化早于认证与 HTTP的设计时序完全一致。3. 双拼写与遥测设计文档要求测试覆盖双拼写拒绝、canonical 遥测、无请求冲突路径。可以推断测试套件通过构造--id与--run-id同时出现即使值相同的调用断言其被判定为用法错误、不发起任何请求且诊断与遥测字段仅命名--run-id——这与文档中冲突诊断和遥测只提及规范参数的约束一一对应。从设计文档到实战写脚本时应该怎么做综合设计文档、迁移指南与源码落地建议如下新脚本一律使用规范拼写asc xcode-cloud status --run-id BUILD_RUN_ID --wait触发构建后从 JSON 输出提取 ID 再查询状态的典型 CI 流程参考 commands/xcode-cloud.mdx 的 CI Integration 示例RUN_OUTPUT$(asc xcode-cloud run --app $APP_ID --workflow CI --branch $BRANCH --output json) BUILD_RUN_ID$(echo $RUN_OUTPUT | jq -r .buildRunID) asc xcode-cloud status --run-id $BUILD_RUN_ID --wait不要同时传--id与--run-id即使值相同也会被判定为用法错误4.x 行为5.0 起--id本身即未知 flag。升级到 5.0 前清理存量脚本搜索xcode-cloud status --id并替换为--run-id5.0 中该拼写将报未知 flag 并以退出码 2 失败且失败发生在任何网络请求之前——这既是契约也是可被 CI 立即捕获的信号。以 CLI 为唯一事实来源迁移文档明确CLI 是事实来源升级后请用asc --help与asc xcode-cloud status --help核对当前二进制实际接受的 flag。小结--id别名从引入到移除的完整生命周期展示了 App-Store-Connect-CLI 处理 CLI 兼容性的一贯手法规范参数先行、别名可见废弃、冲突即错误、诊断与遥测只谈规范名、移除时彻底注销 flag 并以退出码 2 硬性失败。这一契约的每一面设计决策、迁移记录、结构化移除登记、网络层测试都能在仓库对应文件中找到落点可作为设计参数别名/废弃参数功能时的参考范式。当前版本5.x请务必只使用--run-id。相关文档设计文档docs/design/xcode-cloud-status-id-alias.md发布说明docs/release-notes-xcode-cloud-status-id-alias.md迁移指南migrate-to-5-0.mdx命令参考commands/xcode-cloud.mdx实现internal/cli/xcodecloud/xcode_cloud.go移除登记cmd/removed_flags.go退出码cmd/exit_codes.go测试internal/cli/cmdtest/xcode_cloud_status_id_alias_test.go赞分享【免费下载链接】App-Store-Connect-CLIFast, scriptable CLI for the App Store Connect API. Automate TestFlight, builds, submissions, signing, analytics, screenshots, subscriptions, and more项目地址https://gitcode.com/gh_mirrors/ap/App-Store-Connect-CLI点击查看免费下载相关推荐App-Store-Connect-CLI 的 Xcode PKG 导出支持asc xcode export --pkg-path 设计解析App Store Connect CLI 的 Xcode PKG 导出支持 asc xcode export pkg path 设计解析 导读 macOSApp-Store-Connect-CLI 构建选择器标准化--build-id 标志的完整迁移指南App Store Connect CLI 构建选择器标准化 build id 标志的完整迁移指南 本文基于仓库文档 docs/release notes bRadix Vue PinInputRoot 组件完全指南构建高质量验证码与 OTP 输入框Radix Vue PinInputRoot 组件完全指南构建高质量验证码与 OTP 输入框 PinInputRoot 是 radix vueReka UI上一篇CMake安装与卸载完全指南基于libjsonutils项目的实践案例下一篇互联网 Java 工程师进阶Dubbo 通信协议与序列化协议全解析附 Hessian 数据结构与 PB 性能原理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考