更新日志：版本、契约变更与迁移指引
内容层 API 的版本记录与变更政策：近期版本事实（v4.8→v4.9.1）、契约变更的三级分类（兼容增量/行为变更/破坏性）、迁移指引的固定格式，以及「怎么订阅变更」的机器可读入口。
更新日志是 API 提供方的信用记录：改了什么、什么时候改的、你需要做什么——三问都有答案的日志才是日志，只有版本号的叫计数。本页记录内容层 API 的近期版本事实与变更政策，机器可读的版本入口是 GET /api/health（version/build 字段实时可查）。本文属于开发者中心栏目；契约全貌在API 参考总览。
近期版本记录（事实口径，可在 health/审计面对照）
| 版本 | 变更摘要 | 契约影响 |
|---|---|---|
| v4.9.1 | 行情数值字段支持显式 null（POST/PUT /api/admin/markets）：无实测数据存 NULL 而非 0；控制台行情表 null 显示「—」 | 兼容增量：公开 /api/markets 响应中 price 等字段可能为 null——数值消费方需判空（此前无 null 行） |
| v4.9.0 | 雷达页共享控制台会话（免二次登录）；管理端新增 GET /api/admin/credentials-status（凭据轮换状态，无明文）；docs 端点数改由注册表注入（=56，单一事实来源） | 兼容增量：新端点 + 文案数字修正（73→56 为勘误，旧数字从未对应真实注册表） |
| v4.8.2 | 管理端文章列表 SELECT 补 primary_kw/cta 字段（修复六维统计恒 4/6） | 兼容增量：列表响应字段补全 |
| v4.8.1 | 内容页 aria 全链路补全；课时页 pager 规格化（rel=prev/next）；课程页章节导航 | 无 API 影响（渲染层） |
| v4.8.0 及更早 | 草稿预览令牌化（axs_* 会话 + no-store/noindex）、内容体检 stats 字段、批量发布动作、题库独立端点（/api/admin/quiz）等 | 见各版本当期公告 |
记录纪律：只写可验证的事实（health 的版本号、审计日志的动作、端点注册表的数字）——「性能提升 200%」这类无对照口径的句子不进本页。
变更政策：三级分类
- L1 兼容增量（加端点/加字段/加可选参数）：随版本直接上线，日志记录——调用方无需动作（前提：你忽略未知字段，见总览的兼容承诺节）；
- L2 行为变更（同字段语义调整/默认值变化，如 v4.9.1 的 null 语义）：提前在本页公告 + 控制台横幅，给≥2 周对照期；受影响面（哪些端点哪些字段）逐项列出；
- L3 破坏性变更（删端点/改字段类型/收紧鉴权）：原则上不发生；确需发生时提前≥90 天公告 + 双轨过渡期（新旧并行）+ 逐调用方的迁移指引——v1 公开契约至今零 L3 变更，这是要维持的记录。
迁移指引的固定格式
每次 L2/L3 变更的指引都按四段写（历史指引同格式可溯）：①变了什么（端点/字段/行为，前后对照代码块）；②谁会受影响（按调用模式列出，如「对 price 直接 .toFixed() 的前端代码」）；③怎么改（最小 diff 示例）；④怎么验证改对了（可复制的断言命令）。示例（v4.9.1 的 null 语义）：
# ①变了什么：/api/markets 的 price/change_* 可能为 null（此前恒为数字）
# ②谁受影响：对数值字段直接运算/格式化的消费方
# ③怎么改：判空分支
# 旧: const label = "$" + m.price.toFixed(2)
# 新: const label = m.price == null ? "待实测" : "$" + m.price.toFixed(2)
# ④验证：
curl -s https://axionserve-portal.aeronest-global.workers.dev/api/markets | python3 -c "
import json,sys; rows=json.load(sys.stdin)
nulls=[r['symbol'] for r in rows if r.get('price') is None]
print('null 价格的 symbol 数:', len(nulls))" # 你的 UI 对这个数字都应显示「待实测」而非 $0两个真实案例：契约演进长什么样
- 案例一（勘误型，v4.9.0）：docs 页文案曾写「73 个 API 端点」，与端点注册表实数不符——修复方式不是改数字，而是把数字改为从注册表注入（单一事实来源），文案与数据从此不可能漂移。启示：数字类文案的正确形态是「生成」不是「手写」；
- 案例二（语义型，v4.9.1）：行情 price 字段从「恒为数字（无数据存 0）」变为「可为 null（无实测即 null）」——0 是编造的实测值，null 才是诚实的未知。影响面：对 price 直接格式化的消费方需要判空分支（迁移模板见上文）。这是 L2 行为变更的标准处理：公告 + 影响面清单 + 对照期 + 验证命令。
订阅变更：机器可读入口
- 轮询 health：
GET /api/health的 version/build 变化 = 有新部署（ETag 条件请求，成本近零——模板在Webhook 与事件）； - 本页 RSS 化：站点 feed（/feed.xml 类端点）覆盖内容更新；本页重大变更会同步发布一篇 articles 类公告（可被 feed 捕获）；
- 控制台公告：L2 级以上的变更在控制台顶部横幅提示（登录即见）。
版本语义与部署形态
本站版本号为 v4.x.y 三段式：x 段对应架构级演进（含数据库迁移与渲染层重构的里程碑版本），y 段对应功能批次（一轮迭代的补丁集，如 v4.9.0 的三项功能），修订位对应单点修复与语义微调（如 v4.9.1 的 null 支持）。部署形态是单文件 Worker + 构建标签：每次部署的产物哈希写入 x-axion-build 响应头，与本页版本记录一一对应——你在任何响应头里看到的 build 值，都能在本页找到它属于哪个版本、改了什么。这个对应关系是可验证性的最小闭环：版本号说谎容易，构建哈希对不上就难了。
给对接方的三条建议
- 把 health 检查放进你的 CI：每天一次，version 变化时自动跑你的集成测试——契约漂移在当天发现而不是用户投诉时；
- 错误码分支写全：40xxx（改参数）、401xx/403xx（查令牌）、429xx（退避）、5xx（重试）——四类分支齐全的客户端对任何变更都有基本韧性；
- 记录你依赖的行为：把「我依赖列表按 published_at 倒序」这类隐性依赖写进你的测试断言——变更公告再完善，也不如你自己的断言先红。
相关文档：API 参考总览 · Webhook 与事件 · SDK 与库。调试台 /docs 实时反映当前版本端点面；栏目首页回开发者中心。