用途:为发布、文件、API、弃用与能力发现定义强制版本控制纪律,使版本变更明确、结构化、非破坏性、可发现且对消费方安全。
主要能力:发布版本固定为 v1.2.3.4,段位分别表示模型变更、服务或例程变更、缺陷修复或配置变更、自动构建版本。模型变更递增第 1 段并将后三段归零;服务变更递增第 2 段并将后两段归零;缺陷或配置递增第 3 段并将第 4 段归零;同一代码新构建只递增第 4 段。多类变更同时发生时最高阶变更胜出,低段归零。
文件版本:无版本文件夹视为 V0。模型变更必须在原位置下的 Vn 子文件夹新建版本化文件,如 Models/Foundations/Students/V1/StudentV1.cs,服务与异常同路径配套。仅服务行为变更时不新建版本文件夹:模型仍为 V0 时用 Services/Foundations/Students/StudentServiceV1.cs;模型已版本化时用 Services/Foundations/Students/V1/StudentV1ServiceV1.cs。模型与行为同时变更时只递增模型版本,行为版本重置为 V0 且不出现在文件名中,如 StudentV2Service.cs。命名规则为 {Entity}V{n}.cs、{Entity}V{n}Service.cs、{Entity}ServiceV{n}.cs、{Entity}V{m}ServiceV{n}.cs。旧版本代码保留,除非有显式弃用或移除策略。
API 版本:api/{resource} 表示 V0;api/Vn/{resource} 表示模型版本 n;api/Vn.m/{resource} 表示模型版本 n 加行为版本 m。
弃用:通过头部或特性发出弃用元数据,示例含 [DeprecatedApi(Sunset, Warning, Link)],可用 Attrify NuGet 包控制 API 可见性与生命周期;代码弃用使用 [Obsolete("...")]。
能力发现:建议暴露支持的功能、模型版本、行为版本与不可用可选功能,可通过 Swagger、中间件元数据、专用能力端点或提供程序专用端点实现,并给出基于特性的能力检查模式,将运行时不确定性转为确定性检查。
限制:必须严格遵循本技能定义的版本模型,不得替换为其他语义化版本策略、兼容性理论或推断约定。