公开 API 准入与运行形态¶
{
"scope": "global",
"triggers": {
"public-api": [
"FR4",
"FR15",
"DEC-1",
"DEC-2",
"DEC-3",
"DEC-6",
"DEC-7",
"DEC-8"
]
}
}
意图¶
保持 Astryx 公开 API 具有意图性。公开 API 应代表调用者拥有的区分,而非暴露组件本身就能正确做出的选择。该需求只是第一道门槛。提案中的 API 还必须具有清晰含义、可靠行为,以及组件能够兑现的承诺。
每个公开的 prop、hook、工具函数和操作都会成为消费者、文档、测试、主题、迁移和审查者必须理解的永久概念。责任在于说明为什么调用者必须提供信息,而不仅仅是一个 API 能解决当前示例。
非目标¶
- 移除语义状态、受控值、可访问性或组合 API。
- 阻止工具组件暴露其核心目的所在的细粒度控制。
- 用组件专属的布局 props 取代现有样式逃生舱。
- 仅因实现困难而拒绝 API。
需求¶
公开 API 提案只有通过以下两道门槛才会被接纳:
- 需求: 调用者拥有组件无法推导的信息。
-
契约: API 清晰描述组件能够强制实现的可靠结果。
-
FR1 — 属性表示调用者拥有的意图。 新增公开 prop 仅在以下情况合理:两种原本相同的情境需要不同的最终设计结果,且由调用者决定哪种结果适用。
- FR2 — 可推导的差异保持内部化。 当组件能从其状态、内容、测量或 CSS 布局、父级上下文、平台能力或其他现有公开概念推导出正确结果时,不要添加 prop。
- FR3 — 实现选择不是公开概念。 内部阈值、光学调优、算法选择与一次性修复保持内部化,除非 FR1 证明调用者需要区分语义相同的案例。
- FR4 — 现有组合与样式接缝优先。 当现有的插槽、子组件契约、主题目标、
xstyle、className、style或所属布局组件已在正确层次上表达调用者意图时,组件不得添加专用 prop。 - FR5 — 准入论证可审查。 公开 API 提案须指明两种原本相同的案例、所需的不同结果、调用者为何知道差异,以及组件为何无法推导该差异。
- FR6 — 高层组件有更高门槛。 有主见的组合组件倾向于内部解析与组合,而非积累底层调优 props。
- FR7 — 公开概念可理解。 其名称与取值描述调用者意图,不要求使用者了解实现它的渲染技术。
- FR8 — 结果可预测。 每个取值都有稳定、可观察的效果,使用者能够解释、测试能够验证。单独的数据属性、主题钩子或实现差异不构成公开结果。
- FR9 — API 能兑现其承诺。 API 形态承载或拥有产生所声称结果所需的信息。文档和审查论证不得将枚举或样式开关归功于其无法执行的可访问性、关联或验证行为。契约仅依赖组件可以验证的 props、所属子组件、所属上下文和平台事实。
- FR10 — 每个受支持状态独立正确。 可访问性、行为和必要的视觉传达不得仅在假定未经证实的外部条件时才成立。先解决基础组件问题,再增加 API 在不完整方案之间做选择。
- FR11 — 一个语义动作只有一个规范操作。 在一个组件模块内,任何实现同一调用者所有动作的公开或包内部操作都使用一个规范操作名称。公开契约可以暴露更窄的选项集,而包内部实现在同一操作名下接受更宽的语义选项。仅为具有不同契约的真正不同调用者意图才添加另一操作。
- FR12 — 机械筛选不超出契约覆盖。 每次公开 API 新增或语义行为变更在接纳前须指明其精确的 before → after、规范所有者及适用的现行记录。组件局部语义属于组件规范;家族、架构或系统级语义则改由该所有者更新。草稿记录是有效的审查上下文,但不是政策,不能通过授权门槛。机械审查还会拒绝可推导选择、重载输入、隐藏的条件优先级和重复操作。
- FR13 — 存活的变更使语义增量显式化。 所有者审查会收到指向规范当前所有者的链接、一句说明语义 before → after 的话、来自
architecture:knowledge-contracts的适用授权结果,以及仅在公开语法变化时给出的代表性语法。 - FR14 — 契约修复属于 preserves。 修复只有在恢复现行契约或标准、且不超出该授权增加公开 API 或公开行为时才属于
preserves。它需提供回归证据。任何额外的公开增量即使随 bug 修复 pull request 一并提交,也须独立遵循 FR12。 - FR15 — 在可行处预防无效状态。 公开 API 在不使 API 更难理解的前提下预防坏结果。在可行处,使静态可知的无效组合不可表示;否则进行验证或告警,或选择有文档记录的安全回退。不得静默渲染损坏状态,也不得过度限制合法的组合。
- FR16 — 公开输入保持单一语义职责。 在其完整取值域和每种接受的输入形态中,每个公开输入具有一个稳定的语义职责,其名称和类型披露调用者拥有的含义。一个语义输入可以推导多种视觉细节,只要它们构成一个内聚的命名结果,例如同时拥有色调和标记物的语义状态或变体。当输入的值或形态改变了它所控制的轴线,或当使用者需要实现知识才能预测受控轴线时,应拒绝该输入。独立由调用者拥有的轴线使用独立输入,无效与冲突组合按 FR15 预防;由系统拥有的协调暴露语义概念并推导其细节,而不是以某一机制来命名输入。并行输入不产生隐藏的条件优先级:只有当覆盖项的名称、类型及在所有组合中的行为构成显式连贯契约时,覆盖项才有效。
- FR17 — 公开模块与工具函数名披露单一原子角色。 从函数的主要调用者可观察结果和副作用中选择动词,而非取自内部实现步骤。区分构造、检查、查找、转换、注册和保证状态。
define*构造或规范化并返回受支持使用者使用的持久类型化值。它可以复用验证作为前置条件,但仅检查输入或原样返回同一输入的函数不是define*。validate*和check*检查输入并返回结构化结果;其契约声明哪些失败以返回值形式给出,哪些条件抛出异常。如果构造、验证、注册或其他能力是公开的,应将其作为独立可调用函数暴露,而不是将两个公开角色隐藏在同一个名称后面。已发布的错配按兼容性契约弃用并迁移,而非静默改名。只有在已发布的仓库证据支持时,其他动词才获得相应规则。组件 prop 和事件命名保持独立。CLI 命令动词及其编程式命令孪生属于 CLI 表层架构 和 CLI 约定;本要求不定义它们的命令语义。 - FR18 — 公开原语有意支持组合。 Astryx 倾向于为产品构建者必须在多个调用点组合、协调或依赖的稳定行为提供公开契约。这种偏好并不推广原始实现机制。提案中的原始 API 须命名语义化的调用者意图,定义接受和拒绝的操作与结果,并在接纳前获得所属现行契约。内部焦点目标、手势记忆、DOM 插槽、定时器及等效机制保持私有,除非它们被独立接纳为持久的调用者所有概念。
- FR19 — Bug 修复不夹带 API 设计。 能够在不超出现行授权改变公开 API 或行为的前提下恢复当前行为的 bug 修复,MUST 这样做。任何额外公开增量都独立遵循
architecture:knowledge-contracts。可分离的矛盾或未定附带变更必须在审查要求修复承担新所有者决策之前被移除或拆分,但未声明的公开 API 行除外——它交由人工审查以作出所有者决策,而非由审查移除或拆分(architecture:knowledge-contracts变更耦合步骤 6)。现有现行授权可以定夺有意的剩余增量;只有存活的、有意的缺口或未声明的公开 API 行才需要所有者判断。实现便利、移除内部包装器或暴露现有内部字段,都不是 API 应当存在的证据。 - FR20 — 调用点影响与决策负担显式化。 公开 API 变更须展示有代表性的调用点 before 和 after,包括默认值与兼容性,并指明调用者必须理解或做出的每个新选择。只有 FR1 证明该区分由调用者拥有、组件按 FR2 无法推导、且该选择按 FR7–FR10 具有可预测含义时,该负担才被接纳。审查生成的冲击性文字仅是上下文;它不能弥补缺失的调用者所有权,也不能授权该 API。
平台支持¶
- 支持的特性/引擎下限:该规则适用于每个受支持渲染器上的每个导出组件、钩子和工具 API。
- 不支持的行为:浏览器或渲染器的实现限制本身并不是调用者应获得永久 API 的证据。
- 浏览器证据:基于布局的可推导性声明会在真实受支持的浏览器中进行验证,然后才得出结论认为公共 API 是必要的。
当前状态影响¶
- API 审查指南要求在新公共 API 被接受之前,同时具备调用者需求论证和可靠的当前契约论证。
- 每项公共 API 新增和公共行为变更都会识别当前已提交的权威记录,然后遵循由
architecture:knowledge-contracts拥有的结果和处置安排。本规范不重新定义这些结果。 - 精确头部(exact-head)所有者的讨论或批准可以提供决策证据,但在规范的归属记录将该决策提交为
current之前,它不会成为可复用或可清除验收障碍的权威。 - 组件规范拥有组件局部的语义 API 契约,包括它们明确共同拥有的公共钩子和工具。家族、架构和系统记录分别拥有各自的共享语义。组件的
.doc.mjs仍然是使用者语法和参考权威。 module:Markdown/headingLinks将 FR18 和 DEC-8 应用于一个被接纳的公共模块:其工厂为现有插件列表返回一个不透明条目,而不是添加一个宽泛的 Markdown 属性。该模块记录拥有 API 和行为;本系统记录只拥有该接纳结果。- 组件规范继承当前家族契约,并且只记录局部的公共概念、新增和显式例外;它们不复制共享规则。
- 公共模块和工具函数的审查会比较动词与函数的返回值、验证契约、副作用以及受支持的消费者。组件属性/事件命名和 CLI 命令语义保持各自独立的负责人。在显式的弃用和迁移方案设计完成之前,已发布的不匹配项继续保持兼容;本规则不会静默重命名或更改它们。
当前权威依赖¶
对于每个公共 API 或公共行为变化,识别规范所有者并应用由 architecture:knowledge-contracts 定义的路由。本规范拥有 API 接纳和语义形态要求;发布兼容性和版本控制规范 拥有生命周期、分类、弃用、更正和发布处理。两份记录都不会复制审查结果或拉取请求处置。
草稿记录可以提供上下文并路由未解决的问题,但不能清除当前权威。exact-head 所有者的讨论提供决策证据;在实现被接受之前,规范记录必须将已接受的决策提交为 current。
这种权威依赖并不会让公共 API 变得不可取。一旦当前权威确定了语义契约,普通的正确性和证据审查仍然决定实现是否满足它。
- 现有属性和操作不会自动移除。它们会在被触及、邻近 API 被提议,或引发具体维护或一致性问题时被评估。
- 提议的 PowerSearch 编辑器弹出层的最大宽度是需求门禁的动机案例:其宽度是内部已解决的设计选择,而非调用者拥有的区分点,因此新的公共调优属性无法通过。
- 样式开关不能以可访问性、关联、验证或其机制无法执行的任何其他行为来证明其合理性。先解决组件行为;只有在仍然存在清晰、可执行的调用者拥有区分点时,才考虑 API。
- PR #5373 证明,针对同一语义操作的并行公共操作和包内部操作会制造可避免的表面积。其具体的操作名称和选项并非策略。
TableRowStatus.color是过载输入的反例动机。其调色板和原始值仅控制色调,而success、warning和error还会选择默认主题图标;可选的icon随后有条件地覆盖该表示。在规范的component:Table契约到位之前,这种形态会根据 FR16 被拒绝。AST-002 并未规定替代 API。- 实现机械式 API 门禁及其基准测试是后续工作。本策略和模板变更不会添加门禁实现代码。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1, FR5 | 盲测历史 API 审查基准 | 近期工具、中等范围和组合式 API 新增 | 审查者接受了一个属性,却未识别出调用者拥有的语义变化 |
| FR2, FR3 | 组件测试和真实浏览器布局证据 | 内容、容器、视口、父级上下文和平台变化 | 公共 API 暴露了组件能够可靠推导出的值 |
| FR4, FR6 | 针对工具型、中阶与组合组件的 API 表面审查 | 现有的插槽、主题、样式、布局和行为接缝 | 高层组件累积一次性调优 prop,而不是使用其所属层 |
| FR7, FR8 | 使用方示例与行为测试 | 默认、每个公开值、组合使用与不支持的使用 | 含义依赖于实现知识,或测试仅断言类名/数据属性 |
| FR9, FR10 | 组件所有权与无障碍性审查 | 自有内容、外部兄弟内容、缺失或不正确的上下文 | 只有当调用方履行了组件无法验证的承诺时,状态才算正确 |
| FR11 | 公开与包内部操作清单;PR #5373 | 一个组件模块和一个语义操作 | 一个语义操作获得多个仅以实现需求区分的并行操作名称 |
| FR12, FR13 | 公开增量/规范所有者检查与精确的权限路由 | 缺失增量/更新;匹配、矛盾、仅草稿或不存在的权限 | 缺失的增量/所有者更新通过,矛盾被接受,草稿成为策略,或自动化决定语义 |
| FR14 | 针对当前契约或标准的聚焦回归测试 | 缺陷状态、代表性的未变更状态及任何相邻公开增量 | 一次修复引入了新的决策、缺乏回归证据,或在 bug 修复标签下隐藏了额外的公开变更 |
| FR15 | 类型级约束加上运行时验证与行为测试 | 无效值、不支持的组合与合法的组合方式 | API 静默渲染出损坏状态,或阻止有效的组合 |
| FR16 | 完整值域、输入形态与并行组合的契约审查 | 语义变体、原始值或调色板值、显式覆盖与默认值 | 某个值或形态切换了受控轴,或并行输入静默改变优先级 |
| FR17 | 公开模块/工具导出清单,加上实现、测试、使用方与发布历史审查 | 构造、检查、查找、转换、注册、hooks 与已发布的兼容性 | 某个动词隐藏了返回值或副作用,两个公开角色被融合,非 hook 工具使用 use*,或已发布的不匹配被静默重命名 |
| FR20 | 公开调用点与调用方负担审查 | 代表性的前后调用点、默认值、兼容性及每个调用方拥有的选择 | 新的调用方决策被隐藏、可推导、不可预测,或仅靠审查文字来证明合理性 |
| FR18 | 多调用方组合场景加上所属契约审查 | 共享语义操作、仅内部机制与两个代表性使用方 | 产品构建者无法组合出稳定行为,或实现字段在缺乏调用方拥有的语义的情况下被暴露 |
| FR19 | Bug 修复前后的权限差异,加上公开表面与行为清单 | 纯修复、修复加上可分离的新 API/视觉变更、内部包装器移除 | Bug 修复标签绕过权限,可移除的附带变更迫使规范扩大,或内部机制因暴露方便而成为公开内容 |
| 负担 | 基准分类:允许、正确暂停、错误阻止、不适用 | 最近被接受和拒绝的 API 变更 | 理由充分的 API 被反复暂停或阻止,却没有呈现真正的决策 |
决策日志¶
DEC-1 — 公开 prop 需要不可推导的调用方区分¶
参考: spec:AST-002/DEC-1
决策者: cixzhang, 2026-08-30
只有在原本相同的情境需要不同的已解析设计决策,且组件无法从自身可获得的信息中推导出该区别时,新的公开组件 prop 才是合适的。公开 prop 代表调用方拥有的意图,而非实现旋钮。
已拒绝:每当使用者需要不同的内部布局值时添加 prop。这种做法会在各个调用点重复设计决策,并使永久 API 持续膨胀,却没有增加任何语义信息。
DEC-2 —— 调用方需求不允许不清晰或不可执行的 API¶
参考: spec:AST-002/DEC-2
决策者: cixzhang,2026-08-30
一个不可派生的调用方区分仅能通过需求门禁。所提议的 prop 还必须命名一个可理解的概念,产生可靠的、可观察的结果,并使用一种能够兑现其论证所依据之承诺的机制。
已拒绝:仅仅因为审查文本赋予样式开关某种其机制无法提供的可访问性、关联性或验证含义,就接纳该开关。先解决基础组件行为;只有在仍存在清晰、可执行的调用方自有区分时,才考虑公共 API。
DEC-3 —— 一个语义动作使用一个规范操作名称¶
参考: spec:AST-002/DEC-3
决策者: cixzhang,2026-08-31
组件模块在公共形式和包内部形式中,对同一个语义动作使用同一个规范操作名称。公共契约可以暴露较窄的选项集,而包内部实现则在同一个名称下接受更宽的语义选项。只有确实存在不同的调用方自有意图和契约时,才接纳第二个操作。
已拒绝:因为某个内部调用路径需要额外控制,就创建并行操作。这种选择暴露了内部调用路径的差异,并让维护者或使用者必须为同一个动作区分两个名称。
DEC-4 —— API 审查将机械性证据与负责人判断分开¶
参考: spec:AST-002/DEC-4
决策者: cixzhang,2026-09-06
机械性审查会清点确切的公共 API 与行为增量(delta),识别规范负责人,并拒绝客观的 API 形态违规,例如可派生的选择、过载的输入、隐藏的条件优先级,或一个语义动作对应重复的操作名称。它不裁决未定论的语义。
当现行权威未能定论某个存续提案时,应将其私下转交给人类负责人。负责人接受、拒绝或完善语义契约;已接受的决策只有在以 current 状态提交到规范记录之后,才成为审查权威。
已拒绝:要求负责人从实现代码中发现机械性缺陷、将生成的证据视为语义决策,或在负责人定论缺失契约之前发布面向贡献者的裁决。
DEC-5 —— 公共变更要求已提交的现行权威¶
参考: spec:AST-002/DEC-5
决策者: cixzhang,2026-09-06
每一项公共 API 新增和公共行为变更,在实现验收之前都必须识别适用的、已提交的现行权威。草稿记录提供上下文并引导问题,但它们不是政策,也无法通过门禁。针对 exact-head 的负责人讨论或批准属于决策证据,不能替代将已接受的契约记录为 current。
权威缺失会创建由 architecture:knowledge-contracts 拥有的私有未定论路径;它既不是接受变更的许可,也不是自动的、面向贡献者的拒绝。在规范决策变为 current 之后,再对照它审查实现的 exact-head。
已拒绝:此前的阶段性例外,它允许单个拉取请求在负责人批准下继续进行,而其可复用契约仍只是草稿或缺失。该路径使得同一公共行为在一次审查中可接受,而在下一次审查中不可发现。
DEC-6 —— 公共输入保持一个语义职责¶
参考: spec:AST-002/DEC-6
决策者: cixzhang,2026-09-01
每个公共输入在其完整值域和每种被接受的输入形态中,都只有一个稳定的语义职责。其名称和类型披露调用方自有的含义。一个语义输入可以派生多个视觉细节,前提是这些细节构成一个内聚的、有名称的结果,例如一个状态(status)或变体(variant)拥有色调(tone)和指示符(signifier)。当属性的值或形态改变了它控制的轴线,或当使用者需要实现知识才能预测受控轴线时,该属性应被拒绝。
当两个轴线由调用方独立拥有时,应暴露独立的输入,并在 FR15 下防止无效或冲突的组合。当系统拥有它们的协调时,应暴露语义概念并派生两个细节,而不是以某个机制命名输入。并行输入只有在它们的名称、类型以及每种组合下的行为定义了明确、连贯的契约并防止无效或冲突状态时,才允许相互覆盖。
已拒绝:TableRowStatus.color,其调色板和原始值仅表示色调,而 success、warning 和 error 表示色调加默认主题图标,并带有一个可选的 icon,可条件性覆盖表现。在规范的 component:Table 契约出现之前,这种形态无法通过当前的 API 审查。本决策不规定替代 API。
DEC-7 —— 公共模块和工具函数动词披露原子角色¶
参考: spec:AST-002/DEC-7
决策者: cixzhang,2026-09-03
选择公共模块或工具函数的动词时,应依据其主要对调用方可观察的结果和副作用,而不是依据内部实现步骤。区分构造、检查、查找、转换、注册和保证状态。define* 构造或规范化并返回一个持久的类型化值,供受支持的使用者使用。验证可以成为其前置条件,但仅凭检查或不变的身份结果不构成定义。validate* 和 check* 检查输入并返回结构化结果;其契约说明哪些失败会被返回,哪些条件下会抛出异常。
当构造、验证、注册或其他能力为公共能力时,每种能力都有各自的可调用角色。已发布的不匹配应遵循明确的弃用和迁移流程,而不是静默重命名或静默更改行为。其他动词只有在交付证据支持时,才获得仓库级规则。组件 prop 和事件命名保持独立。CLI 命令动词及其编程式命令孪生仍由 CLI 表面负责人掌管。
否决:将仅验证并返回其输入的函数视为 define* 函数,从公共 validate* 或 check* 函数返回裸谓词,将 use* 用于非 Hook 工具,或在没有兼容计划的情况下将单独公开的注册隐藏在构造函数内部。
DEC-8 — 公共原语是有意为之的语义契约¶
参考: spec:AST-002/DEC-8
决策者: cixzhang,2026-09-06
当产品构建者需要在多个调用点组合稳定行为,且该契约能够在不暴露实现机制的情况下,指明调用者意图、操作、结果和失败行为时,应优先选择公共原语。在接纳公共表面之前,先将该契约记录为当前有效。
缺陷修复不构成例外。当它恢复当前有效权威时,应将其 API 和行为保持在该契约之内。任何额外的公共原语或可观察行为均遵循 architecture:knowledge-contracts:首先让任何可分离的矛盾或未定的伴随问题得到符合、移除或拆分;然后在有现有当前决策能解决一个有意的存续差异时,复用该决策。仅就团队实际想要推进的存续决策,向负责人征询。未声明的公共 API 行是例外:architecture:knowledge-contracts 的变更耦合第 6 步会将其交由人工审查以作出负责人决策,且审查不会移除或拆分它。
否决:仅仅因为移除内部包装器或修复某一条路径变得更简单,就把内部焦点目标、手势记忆、DOM 插槽、计时器或其他现有字段提升为公共 API。现有实现是机制方面的证据,而非永久公共 API 意图方面的证据。
DEC-9 — 调用方的决策负担必须可见且有据可依¶
参考: spec:AST-002/DEC-9
决策者: cixzhang,2026-09-12
公共 API 提案应展示变更前后的调用点,并指明调用方必须做出的每一个新决策。只有当该决策代表调用方拥有的、组件无法推导出的意图,且其结果在默认值、组合及受支持状态下保持可预测时,该决策才被接纳。
否决:将更简短的实现、有说服力的用户影响摘要或已完成的审查清单,视为调用方应当承担另一个选择的证据。
开放问题¶
无。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx