Unleash 领域语言Domain Language规范以 Change Request 为例的统一术语体系解析【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleash导读本文基于 domain-language.md 这份架构决策记录ADR系统讲解 Unleash 开源特性管理平台中领域语言Domain Language的治理思路与落地实践。领域语言是团队在代码库、API、UI 与文档之间共享的一套统一术语它决定了同一件事在不同地方应该叫同一个名字。通过本文你将掌握 Unleash 针对 Change Request变更请求功能定义的核心术语Change request / Change / Changes / Discard / Pending / Closed理解这些术语如何与源码中的状态机、数据模型和查询逻辑一一对应并能将这套方法论复用到你自己项目的术语治理中。一、背景为什么一个开源项目需要领域语言在 domain-language.md 的 Background 一节中Unleash 团队明确说明了引入领域语言的原因在代码库中我们看到了定义一套领域语言的需求用来统一指称功能与方法保证整个代码库的一致性。随着代码库规模不断增长当前仓库包含数百个服务、存储层与路由模块同一概念很容易出现多种叫法开发者在后端叫 change request前端组件里叫 edit request 或 proposal数据库字段里又叫 state。这种术语漂移会直接导致跨模块沟通成本上升Pull Request评审中反复争论命名搜索代码时漏掉关键实现同一概念的关键词不统一OpenAPI 生成的接口与前端类型定义产生语义偏差新成员上手成本变高难以判断某个词是否是该领域的官方术语。领域语言Domain Language正是为了解决这一问题而设立的统一词汇表它是代码库内部的一份活词典随功能演进持续扩充。二、决策每个功能维护自己的领域语言ADR 的 Decision 一节给出了核心决策我们决定对我们开发的功能使用相同的领域语言。每个功能都应有属于自己的领域语言以保持整个代码库的一致性。这段决策包含两个层次的含义全局一致同一概念在代码库的任何位置后端服务、数据库列、API 参数、前端组件、测试、文档都必须使用同一术语按功能域划分不同的功能模块各自维护一份术语表例如 Change Request 有 Change Request 的术语Segment、Release Plan 等模块可以有自己的术语避免用一套全局词汇生硬套用所有场景。这是一种分而治之的术语治理模式既保证单个功能域内部严格统一又允许不同功能域使用各自贴切的词汇。三、Change Request 领域语言核心术语逐条解析ADR 文档主体用列表形式定义了 Change Request 功能域的六个核心术语这是全文最重要的部分逐条展开如下。3.1 Change request变更请求Change request指变更请求的整体数据结构overarching data structure。一个变更请求包含若干 changes变更可以被批准approved或拒绝rejected。在 Unleash 中Change Request 是让特性开关feature flag的修改如启用/禁用开关、调整策略、修改 Segment 引用走审批流程的机制常用于生产环境的变更管控。它是一个容器型实体自身不直接代表某个具体改动而是承载一组改动及其生命周期状态。从源码看该实体在数据库中以change_requests表存储例如 feature-search-store.ts 中通过change_requests AS cr关联查询并用cr.id、cr.state、cr.environment等字段描述其身份与状态。OpenAPI 侧也有对应 schema如feature-environment-schema.ts中提及 change request 列表的语义。3.2 Change变更Change指变更请求中的单个变更。例如把 production 环境中 feature A 的 flexibleRollout 策略的 rollout 从 50% 调整为 100%就是一条 change。源码中的addChangeRequestChange正是向某个 change request 追加单条 change 的落库操作见 change-request-segment-usage-read-model.test.ts其中包含updateStrategy这类单条变更动作及其完整 payload。3.3 Changes变更集合Changes指变更请求中一组变更的集合。一个 change request 内部可以有零到多条 changeChanges就是这组变更的统称。在数据模型上单条 change 通过change_request_id外键归属到某个 change request查询时以聚合aggregation方式组织例如 feature-search-store.ts 中array_agg(distinct cre.change_request_id) AS change_request_ids就是把属于同一特性、同一环境的 change request id 聚合成数组。3.4 Discard丢弃Discard用于删除某个变更请求中的单条变更或整体丢弃整个变更请求。Discard 是不采纳改动的动作语义它有两种粒度丢弃单条 change从 change request 中移除某一条改动丢弃整个 change request取消整个变更请求。在状态机的落地上整体丢弃通常对应Cancelled已取消状态而单条 change 的丢弃则是对集合内元素的删除操作。之所以用 discard 而非 delete/cancel是为了与删除功能开关、取消部署等其他领域的动作语义区分开。3.5 Pending待处理Pending指尚未被应用applied或丢弃discarded的变更请求即处于以下三种状态之一Draft草稿In review评审中Approved已批准Pending 是领域语言中的状态分组概念它把三个仍在生命周期中、还可以继续演进的状态归为一类。源码中大量查询正是以是否为 Pending/Active为过滤条件segment-store.ts 在查询 Segment 在哪些活跃变更请求中被使用时排除[Applied, Rejected, Cancelled]剩余即为 Pending 类状态feature-search-store.ts 同样以whereNotIn(cr.state, [Applied, Cancelled, Rejected])来圈定可操作的变更请求sql-change-request-segment-usage-read-model.ts 的 SQL 写法WHERE cr.state NOT IN (Applied, Cancelled, Rejected)与上述逻辑完全一致。3.6 Closed已关闭Closed指已经被应用或取消、不能再被修改的变更请求。状态为Applied已应用或Cancelled已取消的变更请求均视为 Closed。Closed 是 Pending 的互补分组一旦变更请求进入Applied或Cancelled它就进入终态不再接受任何修改。四、源码中的状态全集领域语言与状态机的对应ADR 文档定义了 PendingDraft / In review / Approved与 ClosedApplied / Cancelled两组状态而仓库源码与测试进一步给出了更完整的状态全集。从 change-request-segment-usage-read-model.test.ts 的参数化测试可以看出实际代码中出现的状态还包括状态归属分组源码证据测试断言是否活跃DraftPending活跃该变更请求中的改动会被计入活跃结果In reviewPending活跃同上ScheduledPending活跃已排期、尚未执行仍视为活跃ADR 未单列为源码补充状态ApprovedPending活跃已批准但未应用仍可被计入活跃结果RejectedClosed非活跃测试断言返回空结果CancelledClosed非活跃同上AppliedClosed非活跃同上说明Scheduled已排期与Rejected已拒绝并未出现在 ADR 文档中但仓库的测试与 SQL 查询证实它们存在于实际状态机中。从实现看Scheduled与 Draft/In review/Approved 一样属于尚在生命周期中的活跃状态而Rejected与 Applied/Cancelled 一样属于终态。ADR 作为活文档其术语表会随功能演进持续扩充——这正是文档开头growing list不断增长的列表的题中之义。同时OpenAPI 侧 feature-environment-schema.ts 对可操作的变更请求也给出了与源码一致的语义注释尚未被 Cancelled、Rejected 或 Approved 的变更请求列表Experimental 字段。五、领域语言如何驱动实际业务逻辑访问控制与绕过领域语言不仅是命名规范它还直接映射为业务规则。以 Change Request 访问控制为例change-request-access-read-model.ts 定义的读模型接口清晰地体现了术语驱动的领域逻辑canBypassChangeRequest(project, environment, user?)判断某用户是否可以绕过该项目的变更请求流程即不经审批直接改canBypassChangeRequestForProject(project, user?)项目维度的绕过能力判断isChangeRequestsEnabled(project, environment)判断某项目某环境是否启用了变更请求isChangeRequestsEnabledForProject(project)项目维度的启用状态判断。在这套逻辑中变更请求是否启用、用户能否绕过与变更请求处于何种状态共同决定了用户的写操作是否需要进入审批流。领域语言中的 Pending / Closed 分组正是这类规则落地的公共词汇基础只有 Pending 状态的变更请求才参与审批、才可能被 Approve/Discard。六、如何为你的项目建立领域语言结合 domain-language.md 与 Unleash 的实践可以提炼出一套可复用的术语治理方法用 ADR 固化词汇表以架构决策记录的形式把术语定义写入仓库随代码一起评审、一起演进而不是散落在口头约定或聊天记录里按功能域组织每个核心功能模块维护自己的术语小节如本文的 Change requests domain language先定实体名词如 Change request再定动作动词如 Discard最后定状态分组如 Pending / Closed定义到可判定的粒度每个术语都要给出明确判定标准例如 Pending 必须能枚举出它包含的具体状态而不是一句模糊的还没结束与代码互相印证术语定义后要让数据库枚举值、OpenAPI schema、服务方法命名与之一一对应Unleash 中whereNotIn(state, [Applied, Cancelled, Rejected])就是 Pending 判定在 SQL 层的投影保持活文档心态文档明确标注为 growing list当状态机新增状态如 Unleash 后来加入的Scheduled、Rejected时术语表应及时补充避免文档与实现脱节。七、总结Unleash 的 domain-language.md 展示了一种轻量而有效的领域术语治理模式以 ADR 为载体、以功能域为粒度、以状态枚举为落点让术语成为代码、测试、API 与文档之间的事实连接点。在 Change Request 这一功能域中Change request / Change / Changes / Discard / Pending / Closed 六个术语构成了完整的概念骨架而仓库源码feature-search-store.ts、segment-store.ts、change-request-access-read-model.ts则以可运行的查询与测试验证了这套术语的真实语义。对于任何正在长大的代码库这套先定词、再写码、代码反哺词表的方法论都值得借鉴。【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考