# @fabricorg/ports 中文文档

规范地址：https://npmcn.com/package/%40fabricorg/ports/

版本：0\.5\.11
npm 元数据更新时间：2026-10-31T06:29:55.276Z
中文译文更新时间：2026-11-14T08:02:33.456Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fabricorg/ports
原文对照：https://npmcn.com/package/%40fabricorg/ports/?lang=original
项目主页：https://github.com/Fabric-Pro/fabric-platform/tree/main/packages/ports#readme
源码仓库：https://github.com/Fabric-Pro/fabric-platform

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：629 kB，16 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-08-27T00:19:37.372Z
- 最新版本发布：2026-10-31T06:29:55.086Z
- 近 30 天下载量：2145（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

供应商中立端口接口,DTCG标志解析器,每个适配器都必须通过合同测试包.

## 安装

```sh
npm install @fabricorg/ports
```

也可以使用：`pnpm add @fabricorg/ports`、`yarn add @fabricorg/ports`、`bun add @fabricorg/ports`

## README

# @fabricorg/ports (英语)

供应商中性端口接口,一个W3C DTCG标志解析器,每个适配器都必须通过合同测试包.

能力宣称它需要一个端口—— `CapabilityPortRequirement` 在它的表里, 直到现在,这个名字 解决不了任何问题。 这个软件包提供名称后方的接口,检查一个已注册的适配器是否真正满足了声明,并给每个适配器一个相同的套件来通过.

```bash
pnpm add @fabricorg/ports
```

## 如果有标准,端口会说

`FlagsPort` 与 OpenFeature 提供者的评价表面结构相容,因此 OpenFeature 提供者是一个薄的适配器而不是一个翻译层. `DesignTokensPort` 消耗 W3C DTCG 文档,所以一个设计工具是任意之一的出口国. `IdentityPort` 是 OAuth2/OIDC 形状的,所以一个已经验证了 JWTs 的网关在没有第二个身份模型的情况下执行它.

## 身份是平台停止信任打电话者的地方

每一项管理下的行动、预测决定、赠款和审计记录都来自行为者. `IdentityPort.verify` 将提交证书转换为 `ActorClaims`返回时 `null` 对于任何它不能肯定而不是部分信任的主张.

```ts
import { actorContextFromClaims } from "@fabricorg/ports";

const claims = await identity.verify(credential);
if (!claims) throw new Error("unauthenticated");

// Refuses expired, not-yet-valid, cross-tenant and out-of-space claims.
const actor = actorContextFromClaims(claims, { tenantId, spaceId });
```

核实证明打电话的人是谁. `assertActorClaimsCoverScope` 执行一半不执行:他们可以在租户和空地上行事。 一个租户对另一个租户的证书无效,但不得迟到。 空间覆盖是拼写 `"tenant-wide"` 因此,仅仅忽略覆盖面的说法永远不能被理解为涵盖一切.

这里没有进口的供应商SDK。 一个端口是形状;一个适配器是任何满足它的东西.

## 把声明变成大门

```ts
import { assertPortRequirementsSatisfied } from "@fabricorg/ports";

assertPortRequirementsSatisfied({ capability, adapters });
```

当一个已申报的端口没有注册的适配器,没有适配器说出需要的标准,或者没有提供需要的版本——每个不满意的端口都取名时失败. 版本匹配是准确的;范围谈判属于安装适配器的任意,半执行的semver会比没有更糟糕.

## 适配器合同

```ts
import { flagsPortChecks, runPortContract } from "@fabricorg/ports";

const { passed, failures } = await runPortContract(adapter, flagsPortChecks());
```

每个旗子适配器必须默认而不是丢入未知的密钥,返回每个解析器自己的类型,重复评价,并容忍缺失上下文. 每个被设计到的适配器都必须将一个主题解决到至少一个符号,跟随每个别名,并保持名字的独特性. `runPortContract` 报告每一次失败,而不是在第一次停止,所以一次运行告诉一个适配器作者所有需要修复的东西.

因此,将销售商换成适配器,加上配置变化而不是迁移.

## DTCG 分辨率

`resolveDesignTokens` 将 DTCG 文档平整为点名, 如下 `{alias}` 参考其具体价值,继承 `$type` 从最近的祖先组 宣布一个, 并拒绝 夹杂的别名和别名循环.

### 付款意见(附加合同)

`PaymentObservationsPort` 财务报告和审定财务报表 `PAYMENT_OBSERVATIONS_PORT` (从) `@fabricorg/ports/catalog`(中文(简体) ) 让外部结算来源报告准确的付款分配,而不执行 `PaymentsPort.charge`。现有的电荷接口和 `fabric.payments` 1.0.0不变.

打电话 `assertPaymentObservationRequest` 在提供商查询之前 `assertPaymentObservationMatches` 在记录结果之前 供应服务器的租户, 商家和付款人的参考文献、犬类源名称空间/账户/付款/分配身份, 货币, 和有界限的观察年龄。 连接别名不是源身份 。 失踪, 无法获取、未成型和呆滞的观测结果仍然未知。 结果包含累计小单位 事实,绝不是webhook deltas;仅授权或捕获不是和解.

重新供资和转回数额对不同的退还借项进行分类;负面更正可能作出 其金额超过总结算额。 保留这些意见以进行赤字调节。 待退款 争端可以重叠;这些都是观察, **非可用余额计算**应用程序 保留持久的分配所有权和不良历史,并管理每个由此产生的国家变化 通过主机。 观察不能储备资金、批准退款、担保结算直至 供应商承诺或认证其来源.

认证使用独立种子 未付、授权、捕获、部分结算、结算, 退款、倒置、争议和待退款案件;每个身份方面都有拒绝. 读取和重复读取的独立效果计数检查不会移动金钱。 固定线 不得从认证的适配器获取真相. 套房没有认证 手写证书:部署录用仍需要信任的签发人/证明和准确性 适配器、源账户和能力约束。 本合同不得有生产适配船舶.

托管的收款创建,退款请求和退款查询仍然是单独的生命周期工作. 此只观察添加既不执行操作,也不更改主机补全 或重试语义.

观测 将时间戳与 UTC ISO 格式统一为毫秒(`YYYY-MM-DDTHH:mm:ss.sssZ`) (中文(简体) ). `PaymentObservationContractError.rejection` 是打入的、稳定的(例如) `foreign_scope`, (中文(简体) ), `stale_observation`, (中文(简体) ), `invalid_amount` 或者说 `unexpected_effect`);其消息中没有原始源值. 观察定义载于 `REFERENCE_PORTS`,虽然集会只要求 表示可选观察依赖的能力.

### 付款周期和准确的登记时间

`HostedCollectionsPort` 在完全不可更改的请求下创建/ 查看主机收藏 . 托管的 URL 绝不是授权、 捕获或和解证据 . `PaymentRefundsPort` 请求 并查找单独核准的确切退款; 暂停或缺失的查询仍然未知. 提供者必须解剖地执行稳定的钥匙和剩余可退还数额,包括 同时提出请求。 这些添加剂接口保存 `PaymentsPort.charge`。 。 。 . `assertHostedCollectionResult` 仅允许在服务器认证的源头上使用 HTTPS 目标 ; `assertPaymentRefundResult` 检查准确的原始金额/货币。 他们是安全的解码器, 没有效果认证 。 实施者还必须证明已放弃反应/重新启动恢复, 拒付更改的钥匙、单独的退款授权和同时的对独立退款的拒付 效果在启用突变能力之前计数。 没有任何突变适配器通过这些类型认证.

`admitPaymentRuntime` 读取当前 `PaymentRuntimeAuthority`,需要准确的租户/空间, 港口/合同、适配器/供应商版本、罐头来源/账户和商家,以及检查签发、, 期满,成型良好的证据摘要并撤销. 当局认证其签发来源; 调用者 JSON 从未被信任的权威。 交易消费者拥有权威和连接吊销锁 通过承诺,或为远程商店使用单独认证的栅栏式调度协议。 重新检查 在每一个相应的边界。 这并不能取代东道国的业务授权或付款人授权.

`assertPaymentRequestAdmission` 在发送之前,对照被接纳的租户、空间、商家和商家的账户检查申请。 其规定的合同论据将操作端口和版本标出;观察允许不能授权退款操作.

### 结清收款请求并解决退款

`HostedCollectionClosurePort.close` 需要单独的管制关闭当局和整个 原始主机采集请求 . `lookupClosure` 读取同样的不可改变的操作。 A 类 `closed` 结果约束了该页收集的确切请求和最后总金额。 它保证所有 原创建密钥的原始 URL 和每个未来的重试都无法再次收集 - 即使当 结束尚未创建的请求。 飞行中俘虏必须独立 和解,不可撤销地无效,或先在提供方过期。 关闭本身永远不会失效。 直至 然后关闭并查看 Closure 返回相同的待参考文献, 重放为一元, 页面 无法接受新的付款。 关闭既不退钱也不取消订单。 缺少搜索, URL 过期、拒绝和暂停从未证明关闭。 使用 `assertHostedCollectionClosureRequest` 财务报告和审定财务报表 `assertHostedCollectionClosureResult` 在发出和保留证据之前.

`PaymentRefundResolutionPort.resolve` 只读,并绑定确切的原退款请求。 A 类 `final` 结果确定准确的返回数额(全额、部分或零),并保证 其余部分无法通过原键重试执行。 正数需要不透明 退款引用;零要求无效. 在供应商有 独立的终端围栏。 验证为 `assertPaymentRefundResolution`普通退款请求 拒绝不是这一证据,仍然需要单独核对源余额.

关闭和退款-最终认证帮助者需要独立的提供者的真相和效果 数据库,包括从未打开的页面,等待抓取、准确身份否认和 全额/部分/零退款结果。 与应用程序所属的创建/退款请求一起运行 认证。 这些合同不提供生产适配器、授权企业行动,或 替换当前运行时间录入。 现有的生命周期接口和版本保持不变.

关闭栅栏钥匙包括被接纳的租户、空间、商家、地名空间和账户以及 原始创建密钥 。 整个请求仍然是不可改变的;一项关闭行动声称 收藏密钥。 更改的操作返回被拒绝/更改 请求或拒绝/未授权 不得对有效请求投毒; 外国绑定书总是回回被拒绝/未授权的。 东道国和 信任的调度执行精确的关闭权限; 不透明的引用不是自我认证 . 关闭后, 旧生命周期创建/ 抬头返回 `rejected/unsupported`时 `lookupClosure` 保留不可改变的证据。 搜索从未关闭或等待更改或外国约束 请求: 它返回未知、 被拒绝/ 不被批准或 被拒绝/ 更改的请求, 没有效果 . 退款完成后, 旧的请求/查询无法返回; 只有全额退款才能返回 匹配确认的结果,否则返回时不支持.

核证内容包括独立的部分/完整页、零效果墓碑,同时 关闭/创建、同时等待退款请求/解决、只读和拒绝操作检查, 更改键/权威/源重放,以及操作、关闭和货币效应计数器。 创建 在关闭比赛中获胜的,可以创建一页;关闭后不得保留可收.

应用程序根据独立来源观察计算替换金额,保留关闭 金额作为证据,而不是作为余额处理。 结算报告毛额,不 获取或净资金。 提供商无法将银行转账指示与迟到者隔离 没有资金支持。 超出原请求的数额不能作为有效终结 证明,并且必须保持未决。 从未退还供应商的退款也同样保留 直到独立证明为最终; 此只读解析端口不能创建放弃 栅栏.

## 常见问题

### @fabricorg/ports 是什么？

供应商中立端口接口,DTCG标志解析器,每个适配器都必须通过合同测试包\.

### 如何安装 @fabricorg/ports？

在项目目录运行 npm install @fabricorg/ports，或使用 pnpm add / yarn add / bun add。

### @fabricorg/ports 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fabricorg/ports 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @fabricorg/ports 可以商用吗？

@fabricorg/ports 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fabricorg/ports 的下载量有多少？

根据 npm 官方下载统计，@fabricorg/ports 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,145 次，日均约 72 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fabricorg/ports 还在维护吗？

最新版本 0\.5\.11 发布于 2026/10/31（14 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2026/08/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。