15.3 与卷三发行衔接
15.2 把接入工程写成规范:谁先初始化、挂了怎么降级、健康报告怎么出。这一节把这些规范收口成「可以拿去上架的那一版」——发行就绪检查清单。上架前跑一遍清单,回答八个问题:登录了吗、AppID 对吗、在 public 分支吗、BuildID 对得上发行标签吗、DLC 归位了吗、云存档通了吗、统计就绪吗、库存就绪吗。全绿才准发。
本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/ 各接口头文件。
本章与站内既有内容的分工
- Steam 发行专题 (操作手册)讲「后台表单怎么填、上架步骤怎么做」;本节讲「代码侧怎么证明自己可以上架」。
- 卷三《发行、定价与商业化》讲发行定价;本节是卷二接入侧对卷三交付的「就绪检查」接口。
- 15.1/15.2 给全景图与规范;本节把规范落到「发行前最后一次自检」。
就绪检查的对象:发行相关的平台状态
发行就绪检查读的是一组跨接口的只读状态:登录态来自 ISteamUser,AppID 与 BuildID 来自 ISteamUtils/ISteamApps,DLC 来自 ISteamApps,云存档来自 ISteamRemoteStorage,统计/库存来自 ISteamUserStats/ISteamInventory。检查层只读、不写:
// isteamapps.h:bIsDlcInstalled / isteamutils.h:GetAppBuildId(SDK v1.65 头文件摘录,已删减)
virtual bool BIsDlcInstalled( AppId_t appID ) = 0;
virtual int GetAppBuildId() = 0;
工程语义:
- 检查项是「状态 × 预期」的断言。每个检查函数读一个平台状态,与预期比较,失败给一条可读原因。比如「BuildID 与发行标签不符」而不是裸的
false——原因直接进发行阻断记录。 - 检查层与功能层分离。库存功能(第 13 章)管「怎么用库存」;检查层只管「库存就绪快照拿到了没有」。功能层失败未必阻断发行,检查层失败要能直接说明「哪个接口域没就绪」。
- 预期值来自配置而非硬编码。发行标签对应的 BuildID、应安装的 DLC AppID 都是发布配置项;检查函数带预期参数,不能把「这一版」写死在代码里。
必需与可选:谁阻断发行
发行就绪检查同样分必需/可选,语义比初始化更严——必需项失败是发行阻断:
| 检查项 | 分类 | 失败原因示例 |
|---|---|---|
| steam_logged_on | 必需 | Steam client not logged on |
| app_id_matches | 必需 | unexpected app id |
| beta_public | 必需 | not on public beta branch |
| build_matches_release | 必需 | build id mismatch with release tag |
| dlc_owned | 可选 | DLC not owned or not installed |
| cloud_save_present | 可选 | cloud save missing |
| stats_ready | 必需 | user stats not ready |
| inventory_ready | 可选 | inventory snapshot not ready |
// isteamuser.h:BLoggedOn / isteamuserstats.h:RequestCurrentStats(SDK v1.65 头文件摘录,已删减)
virtual bool BLoggedOn() = 0;
virtual bool RequestCurrentStats() = 0;
工程语义:
- 「全部必需通过」才算绿灯。清单引擎先跑全部检查,再判定
allRequiredPass;可选失败不阻断,但失败计数要进报告——「云存档缺失」是发布当天值得看一眼的警告,不该被吞掉。 - 第一个阻断原因就是发行阻塞点。发行流水线只需要第一项阻断原因即可决定「打回」;原因要可读、可直接发给负责的开发者。
- 红灯不能靠「再跑一次」侥幸通过。修复后重跑绿灯才算数;清单引擎记录每次 run 的时间戳,发行记录里能看出「什么时候检查过、当时什么状态」。
结果确定性与发行记录
清单的工程价值在确定性:结果顺序与注册顺序一致、每次 run 全量重算、计数口径成立(通过 + 失败 = 总检查数)。这保证「发行前自检」是一份可信的审计记录。
工程语义:
- 顺序即文档。检查按注册顺序执行,报告顺序稳定;人审和机器读都从同一份顺序得到结论。
- 全量重算,不缓存。玩家登录态变了、BuildID 换了,
run()重新读一遍状态,不沿用上次结果——这是发行检查与「运行时缓存状态」最根本的区别。 - 计数口径可断言。
passed + failed == total、必需项数量可数;这些不变量在测试里断言,保证报告不被统计 bug 污染。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteamuser.h | BLoggedOn() | 登录态(必需检查之一) |
isteamutils.h | GetAppID() | 当前进程 AppID |
isteamapps.h | GetCurrentBetaName(out) | 当前 Beta 分支名 |
isteamutils.h | GetAppBuildId() | 当前 BuildID |
isteamapps.h | BIsDlcInstalled(AppId_t) | DLC 是否拥有并安装 |
isteamremotestorage.h | FileExists(name) | 云存档文件是否存在 |
isteamuserstats.h | RequestCurrentStats() | 统计就绪触发(异步) |
isteaminventory.h | GetAllItems(handle) | 库存快照触发(异步) |
数据口径与来源
- 接口签名与字段:SDK v1.65
public/steam/各头文件可实证(本机镜像已核对)。 - 检查项分类、阻断语义、发行标签匹配:本节为接入工程模型(模型假设),随发行流水线取舍;Steam 官方不规定「哪些检查项必须阻断」。
- 实际发行门槛、BuildID 对应关系、Beta 分支命名:以 partner 后台与发行工具当前为准。
以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。
可运行产物:C++ 最小验证
下面的仿真复现「与卷三发行衔接」的工程语义:8 项就绪检查(5 必需 + 3 可选)、全部就绪绿灯、未登录/旧 BuildID/统计未就绪红灯并给出首个阻断原因、可选失败仅记警告不阻断、修复后重跑绿灯、结果顺序与注册顺序一致、每次 run 记录时间戳、必需项计数与通过+失败口径成立。它与 src/15-3-bridge-to-launch.cpp 逐字节一致,mock 接口签名对照 SDK v1.65 头文件:
// file: src/15-3-bridge-to-launch.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/15-3-bridge-to-launch.cpp -o bin/15-3-bridge-to-launch && ./bin/15-3-bridge-to-launch
//
// mock:复现「与卷三发行衔接」的工程语义——发行前就绪检查清单:
// 登录态、AppID、Beta 分支、BuildID、DLC 拥有、云存档、统计就绪、库存就绪。
// 方法名对照 SDK v1.65 isteamuser.h / isteamutils.h / isteamapps.h /
// isteamremotestorage.h / isteamuserstats.h / isteaminventory.h,mock 接口,
// 非 Valve 实现。
#include "verify.h"
#include <cstdint>
#include <string>
#include <vector>
namespace steam_repro {
constexpr uint32_t kExpectedAppID = 480;
constexpr uint32_t kDlcAppID = 480001;
// 发行就绪检查使用的平台状态(字段为 mock 数据,方法名对照真实接口)。
class MockPlatformState {
public:
bool bLoggedOn() const { return loggedOn; }
uint32_t getAppID() const { return appId; }
std::string getCurrentBetaName() const { return betaName; }
int getAppBuildId() const { return buildId; }
bool bIsDlcInstalled(uint32_t dlcAppID) const {
return dlcAppID == kDlcAppID && dlcOwned && dlcInstalled;
}
bool fileExists(const std::string& /*name*/) const { return cloudSaveExists; }
bool loggedOn = false;
uint32_t appId = 0;
std::string betaName;
int buildId = 0;
int releaseBuildId = 0;
bool dlcOwned = false;
bool dlcInstalled = false;
bool cloudSaveExists = false;
bool statsReady = false;
bool inventoryReady = false;
};
struct MockCheckResult {
std::string name;
bool required;
bool pass;
std::string reason;
};
using CheckFn = bool (*)(const MockPlatformState&, std::string* reason);
class MockLaunchChecklist {
public:
void addCheck(const std::string& name, bool required, CheckFn fn) {
items_.push_back({name, required, fn});
}
// 按注册顺序执行全部检查,记录结果。
void run(const MockPlatformState& s) {
results_.clear();
++runCount_;
lastRunTime_ = 1735000000 + runCount_;
for (const Item& item : items_) {
std::string reason;
bool pass = item.fn(s, &reason);
results_.push_back({item.name, item.required, pass, reason});
}
}
// 全部必需检查通过才算绿灯。
bool allRequiredPass() const {
for (const MockCheckResult& r : results_) {
if (r.required && !r.pass) return false;
}
return true;
}
size_t passedCount() const {
size_t n = 0;
for (const MockCheckResult& r : results_) n += r.pass ? 1 : 0;
return n;
}
size_t failedCount() const {
size_t n = 0;
for (const MockCheckResult& r : results_) n += r.pass ? 0 : 1;
return n;
}
size_t checkCount() const { return results_.size(); }
const std::vector<MockCheckResult>& results() const { return results_; }
uint32_t lastRunTime() const { return lastRunTime_; }
// 第一个未通过的必需检查原因(发行阻断)。
std::string firstBlockingReason() const {
for (const MockCheckResult& r : results_) {
if (r.required && !r.pass) return r.reason;
}
return "";
}
private:
struct Item {
std::string name;
bool required;
CheckFn fn;
};
std::vector<Item> items_;
std::vector<MockCheckResult> results_;
uint32_t runCount_ = 0;
uint32_t lastRunTime_ = 0;
};
// ---- 检查函数 ----
bool checkLoggedOn(const MockPlatformState& s, std::string* reason) {
if (!s.bLoggedOn()) {
if (reason) *reason = "Steam client not logged on";
return false;
}
return true;
}
bool checkAppID(const MockPlatformState& s, std::string* reason) {
if (s.getAppID() != kExpectedAppID) {
if (reason) *reason = "unexpected app id";
return false;
}
return true;
}
bool checkBeta(const MockPlatformState& s, std::string* reason) {
if (s.getCurrentBetaName() != "public") {
if (reason) *reason = "not on public beta branch";
return false;
}
return true;
}
bool checkBuild(const MockPlatformState& s, std::string* reason) {
if (s.getAppBuildId() != s.releaseBuildId) {
if (reason) *reason = "build id mismatch with release tag";
return false;
}
return true;
}
bool checkDlc(const MockPlatformState& s, std::string* reason) {
if (!s.bIsDlcInstalled(kDlcAppID)) {
if (reason) *reason = "DLC not owned or not installed";
return false;
}
return true;
}
bool checkCloudSave(const MockPlatformState& s, std::string* reason) {
if (!s.fileExists("save.bin")) {
if (reason) *reason = "cloud save missing";
return false;
}
return true;
}
bool checkStats(const MockPlatformState& s, std::string* reason) {
if (!s.statsReady) {
if (reason) *reason = "user stats not ready";
return false;
}
return true;
}
bool checkInventory(const MockPlatformState& s, std::string* reason) {
if (!s.inventoryReady) {
if (reason) *reason = "inventory snapshot not ready";
return false;
}
return true;
}
} // namespace steam_repro
int main() {
using namespace steam_repro;
MockLaunchChecklist checklist;
checklist.addCheck("steam_logged_on", true, checkLoggedOn);
checklist.addCheck("app_id_matches", true, checkAppID);
checklist.addCheck("beta_public", true, checkBeta);
checklist.addCheck("build_matches_release", true, checkBuild);
checklist.addCheck("dlc_owned", false, checkDlc);
checklist.addCheck("cloud_save_present", false, checkCloudSave);
checklist.addCheck("stats_ready", true, checkStats);
checklist.addCheck("inventory_ready", false, checkInventory);
// 全部就绪:绿灯
MockPlatformState ready;
ready.loggedOn = true;
ready.appId = kExpectedAppID;
ready.betaName = "public";
ready.buildId = 20261112;
ready.releaseBuildId = 20261112;
ready.dlcOwned = true;
ready.dlcInstalled = true;
ready.cloudSaveExists = true;
ready.statsReady = true;
ready.inventoryReady = true;
checklist.run(ready);
CHECK(checklist.allRequiredPass());
CHECK(checklist.failedCount() == 0);
CHECK(checklist.checkCount() == 8);
// 1. 未登录:必需项失败,红灯,原因可读
MockPlatformState noLogin = ready;
noLogin.loggedOn = false;
checklist.run(noLogin);
CHECK(!checklist.allRequiredPass());
CHECK(checklist.firstBlockingReason() == "Steam client not logged on");
// 2. BuildID 与发行标签不符:红灯
MockPlatformState oldBuild = ready;
oldBuild.buildId = 20261101;
checklist.run(oldBuild);
CHECK(!checklist.allRequiredPass());
CHECK(checklist.firstBlockingReason() == "build id mismatch with release tag");
// 3. 可选检查失败:仍是绿灯,但失败计数记录了警告
MockPlatformState noCloud = ready;
noCloud.cloudSaveExists = false;
checklist.run(noCloud);
CHECK(checklist.allRequiredPass());
CHECK(checklist.failedCount() == 1);
// 4. 可选 DLC 未装:不阻断发行
MockPlatformState noDlc = ready;
noDlc.dlcOwned = false;
checklist.run(noDlc);
CHECK(checklist.allRequiredPass());
// 5. 统计未就绪:必需项失败
MockPlatformState noStats = ready;
noStats.statsReady = false;
checklist.run(noStats);
CHECK(!checklist.allRequiredPass());
CHECK(checklist.firstBlockingReason() == "user stats not ready");
// 6. 修复后重跑:绿灯
noLogin.loggedOn = true;
checklist.run(noLogin);
CHECK(checklist.allRequiredPass());
CHECK(checklist.passedCount() == 8);
// 7. 结果顺序与注册顺序一致
const std::vector<MockCheckResult>& res = checklist.results();
CHECK(res.size() == 8);
CHECK(res[0].name == "steam_logged_on");
CHECK(res[7].name == "inventory_ready");
// 8. 每次 run 记录时间戳
uint32_t t1 = checklist.lastRunTime();
checklist.run(noLogin);
CHECK(checklist.lastRunTime() > t1);
// 9. 必需检查数量(绿灯时必需项全部通过)
checklist.run(ready);
size_t requiredCount = 0;
for (const MockCheckResult& r : checklist.results()) requiredCount += r.required ? 1 : 0;
CHECK(requiredCount == 5);
CHECK(checklist.passedCount() == 8);
// 10. 计数口径:通过 + 失败 = 总检查数
CHECK(checklist.passedCount() + checklist.failedCount() == checklist.checkCount());
return lab::report("15-3 与卷三发行衔接");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 21/21 通过。
小结
- 发行就绪检查清单:8 项跨接口只读检查,5 必需 + 3 可选。
- 全部必需通过才是绿灯;第一个阻断原因即发行阻塞点。
- 可选失败不阻断但记入报告;修复后重跑绿灯才算数。
- 结果顺序稳定、全量重算、计数口径成立,保证发行自检是一份可信审计记录。
阅读导航:上一节:15.2 接入工程规范 · 下一节:卷二目录 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。