《Kubernetes 分布式系统原理深入解析》13.3 API 发现与扩展路径选型
客户端怎么知道集群有哪些 API?靠发现机制(discovery):/apis 目录列出版本与资源,kubectl 与客户端据此构建请求。发现机制把核心资源、聚合层服务、CRD 全部汇入同一目录。扩展 API 有两条路径——聚合层(挂服务)与 CRD(声明资源)——本节给选型判据与发现机制的原理。lab 用 api 包验证统一存储的版本语义作为选型基础。
category
客户端怎么知道集群有哪些 API?靠发现机制(discovery):/apis 目录列出版本与资源,kubectl 与客户端据此构建请求。发现机制把核心资源、聚合层服务、CRD 全部汇入同一目录。扩展 API 有两条路径——聚合层(挂服务)与 CRD(声明资源)——本节给选型判据与发现机制的原理。lab 用 api 包验证统一存储的版本语义作为选型基础。
比聚合层更简单的扩展路径是 CRD(CustomResourceDefinition):只写 YAML 声明一个资源类型,apiserver 就提供完整的 REST 端点。CRD 的多版本是关键语义:一个 storage version 落盘 etcd,多个 served version 对外可见,版本间用转换函数互转。本节解剖 CRD 的存储/服务版本模型与版本转换。lab 用 api/crd.go 验证 v1alpha1 与 v1 的转换。
K8s 的核心 apiserver 不能什么都做,也不该什么都做。聚合层(kube-aggregator)把第三方 API 服务挂进统一的 API 入口:客户端从同一个 /apis 访问核心资源与扩展资源,聚合层做路由、鉴权委托与发现聚合。本节解剖聚合层的架构与『核心 + 扩展共享一条入口』的设计。lab 用 api 包的 store/crd 验证统一存储的版本语义。
配额的落地机制是令牌桶:优先级每秒获得一定令牌,每个请求消费一个令牌;令牌随时间匀速补充、有上限。令牌桶既能限『平均速率』(每秒预算),又能容忍『突发』(桶内积攒的令牌一次用掉)。本节解剖令牌桶算法、突发容忍的意义与配额预算的配置。lab 用 admission/apf.go 验证预算内放行、超预算排队。
全 45 篇的章节索引:从 SDK 全景、初始化与身份认证出发,依次处理成就与统计、云存储、覆盖层与好友、App 信息与 DLC、创意工坊、网络多人在线、游戏服务器与反作弊、构建分发、测试预览、回调异步、库存微交易、平台服务集成,最后以接入工程全景、工程规范与卷三衔接收口。
《Steam 游戏平台:开发与商业化》卷二《Steamworks 开发接入》全 45 篇的目录与学习路径:从 SDK 全景、初始化与身份认证出发,经成就统计、云存储、覆盖层与好友、App 信息与 DLC、创意工坊、网络多人在线、游戏服务器与反作弊,再到构建分发、测试预览、回调异步、库存微交易、平台服务集成,最后以接入工程全景与工程规范收口。
APF 的公平不止于优先级之间,还包括优先级内部的队列语义:请求超配额时进入 FIFO 队列等待,队列保证同一优先级内的先到先服务。配额耗尽时高优先级也排队,但不被低优先级饥饿。本节解剖 APF 的队列模型、出队顺序与公平性的两层含义——优先级间公平、优先级内公平。lab 用 admission/apf.go 验证高优先级优先与队内 FIFO。
本节接与卷三发行衔接:把接入工程收口成发行就绪检查清单——登录态、AppID、Beta 分支、BuildID、DLC 拥有、云存档、统计与库存就绪。lab 用 C++ mock 就绪检查清单引擎,验证必需项红灯阻断发行、可选项失败仅记警告、修复后重跑绿灯与结果顺序确定性。
本节接接入工程规范:把 15.1 的全景图写成可执行的工程约束——初始化顺序、必需/可选服务回退矩阵、临时故障重试、健康报告与收尾清理。lab 用 C++ mock 启动引擎与回退矩阵,验证依赖序、必需失败中止、可选失败降级与确定性回退选择。
本节接接入工程全景:把本卷已涉及的接口域组织成一个可运行的接入骨架——接口获取器注册表、依赖序全量初始化、每帧回调泵、SteamAPICall 异步调用跟踪与收尾重初始化。lab 用 C++ mock 接口注册表、回调队列与异步调用表,验证全景生命周期与可选服务降级。
本节接平台服务集成策略:如何把 ISteamUtils、ISteamInput、ISteamInventory 等平台服务按依赖关系组织进接入工程。lab 用 C++ mock 服务依赖图、初始化顺序与必需/可选服务治理,验证依赖未就绪拒绝、必需失败中止、可选失败回退与依赖环检测。
本节接 ISteamInput 手柄与输入机制:Init 生命周期、GetConnectedControllers 枚举、GetActionSetHandle/GetDigitalActionHandle 句柄查询、ActivateActionSet 动作集切换与 GetDigitalActionData 数字动作状态。lab 用 C++ mock 控制器连接、动作集/数字动作句柄与按键状态,验证同名句柄幂等与动作集切换后的可用性。
分布式系统没有全局时钟,事件的先后必须靠逻辑序而非墙钟判定。本节从 happens-before 关系出发,给出 Lamport 时钟与向量时钟的规则、性质与局限,并映射到 K8s/etcd 的真实机制:resourceVersion 来自 etcd 的 mvcc revision、事件 lastTimestamp 只是人类可读的注释。lab 用 TestLamportHappensBefore 验证 HB⇒LT 单向成立,用 TestVectorConcurrentDetection 验证向量时钟能判定并发。
第 6 章讲控制器自我节流,第 12 章讲服务端限流:APF(API Priority and Fairness)保护 apiserver 不被超载。APF 先把请求按 FlowSchema 归入优先级(PriorityLevel),再按优先级分配配额——高优先级(如 kube-controller-manager 的系统请求)不被低优先级(如非列表请求)饥饿。本节解剖 FlowSchema 分流与优先级分配。lab 用 admission/apf.go 验证高优先级优先放行。
本节接 ISteamUtils 平台工具机制:GetAppID/GetIPCountry/GetServerRealTime/GetSecondsSinceAppActive/GetCurrentBatteryPower 与硬件判定。SDK v1.65 已移除 IsRunningOnSteamDeck,改用 IsRunningOnSteamHardware(返回 ESteamHardwareType)与 IsRunningUnderProton。lab 用 C++ mock 平台状态与默认配置档选择,验证非布尔硬件判定与低电量兜底。
本节接库存商业模型的接口语义:ConsumeItem 消耗、ExchangeItems 原子合成、TransferItemQuantity 堆叠拆分、AddPromoItem 一次性促销、TriggerItemDrop 游玩时长掉落与 ESteamItemFlags 交易约束。lab 用 C++ mock 消耗、配方、拆分、促销与掉落,验证原子性、一次性授予与数量约束。
本节接库存微交易的接口语义:GenerateItems 生成条目、RequestPrices/GetItemPrice 价格模型、StartPurchase 触发购买、MicroTxnAuthorizationResponse_t 授权回调。lab 用 C++ mock 条目生成、价格表与购买-授权流程,验证价格可见性、生成唯一性与授权后才落库的机制。
本节接 ISteamInventory 库存机制:ItemDef 定义表、GetAllItems 异步快照、GetResultItems 两段式读取结果集、GetResultStatus 与 DestroyResult 的结果句柄生命周期。lab 用 C++ mock 库存条目、定义表与结果句柄,验证两段式读取、空间不足拒绝与句柄释放后的失效语义。
平台事件最终要映射成产品动作:覆盖层启停→暂停/恢复、富状态更新→展示、join 请求→连服、成就解锁→提示。本节讲事件翻译层与 FIFO 派发的产品设计,lab 用 C++ mock 验证回调 id→产品动作的映射与顺序稳定。
生产集群的准入链不止一两个 webhook:sidecar 注入、安全校验、资源限制可能来自不同团队。webhook 的排序(mutating 顺序影响结果)、作用域(namespaceSelector、matchPolicy)与多条 webhook 的共存,决定准入链能否扩展。本节解剖 webhook 排序的后果、作用域选择与链的可扩展性设计。lab 用 admission/admission.go 验证链式顺序与幂等。