@bikefinder/ api-客户端
生成 REST 和 SignalR 客户端 API 服务. Hey API 从 OpenAPI 生成命名为 HTTP 的方法,类型和 Zod 验证. 已打入信号R. 客户端. TypeScript 从服务器执行的 C# 接口生成中枢代理. 官员 @microsoft/signalr 客户端拥有流和连接管理. 版本 1 是从以前的窄端 SDK; 旧的 /admin 财务报告和审定财务报表 /v1 软件包条目被删除.
import { createBikeFinderClient } from "@bikefinder/api-client";
const api = createBikeFinderClient({
baseUrl: "https://api.example.com",
getToken: () => auth0.getAccessTokenSilently(),
});
const result = await api.requests.getTracker({ path: { id: trackerId } });
if (result.error) showProblem(result.error);
else render(result.data.data);
await api.realtime.connection.start();
const subscription = api.realtime.hub.watchTracker(trackerId).subscribe({
next: (document) => render(document.data),
error: (error) => showSubscriptionError(error),
complete: () => showSubscriptionEnded(),
});
// Cancel this native SignalR stream and its server-side Firestore listener.
subscription.dispose();
// On sign-out/account change, discard account data and dispose this client.
await api.dispose();
使用 staffRealtime.connection 财务报告和审定财务报表 staffRealtime.hub 工作人员业务。 连接不开始创建; 只启动应用程序所用的连接 。 页面流接受一个查询对象, 例如 api.realtime.hub.watchTrackers({limit: 50})。通过返回 nextCursor 作为 cursor 用于另一页.
该应用程序拥有订阅共享,保留数据和账户范围. 订阅本地 connection.onreconnecting, (中文(简体) ), onreconnected 财务报告和审定财务报表 onclose 用于更新UI的事件。 每个连接上都配置了自动再连接,但不重试初始 start() 失败或恢复流引用:在重新连接后再创建订阅. 终止的流已完成 。 没有自定义的监视状态或订阅协调器 .
应用程序的 Auth0 SDK 提供符和手柄刷新. 为新的账户会话创建新客户端 . dispose() 中止 HTTP 请求并停止两个连接 。 请求使用无记名认证,省略 cookie并拒绝重定向. 网络/ 验证失败拒绝; HTTP 问题细节作为 result.error 默认。 写字永远不会自动重试; a 503 operation_unconfirmed 可能已经承诺了.
REST响应使用生成了Zod验证. 流值生成了静态类型并使用本地信号R解码器;用于运行时间验证,导入 zTrackerDocument 从 @bikefinder/api-client/schemas 打电话 .parse(value)两种运输都提到相同的有效载荷类型。 Firestore 响应来自 C# DTO 中的实际 Firestore/TrackerData.cs 财务报告和审定财务报表 Firestore/ResourceData.cs。API在回复前转换所储存的数据; readIssues 识别无法使用的存储字段。 额外的元数据仍然存在于明确的JSON扩展字段中. 服务器序列化响应固定装置通过API和生成客户端测试验证. 身份证就是Firestore身份证.
其他土著资源通过特定资源文件类型暴露其已知领域。 他们的C#合同只暴露了被解释的字段;无关的被储存的字段留在API内. 跟踪报告和统计有具体的模型,访问码存储从回复中省略. 观测值产生结合: observation.definitionId === 5, (中文(简体) ), observation.value.percent 是一个数字。 当前读取显示同一歧视者; 检查 observationId !== null 在使用本读数之前。 设备设置,内置的工作流程描述符和命令参数tuple都是由Cononical协议JSON合同产生的. 自行车和首选补丁暴露了所支持的属性并区分了遗漏和明示的无效. 响应验证器在检查已知值、所需属性和enum时保留了额外的API字段。 请求模型保留其已声明的限制,被关闭的对象拒绝未知的写字字段. 共享的有效载荷产生了读取的变体,因此宽容的反应绝不会削弱请求计划.
手写入口只配置客户端,认证和处理. 生成了枢纽方法,线名和流式签名. 所生成的只类型桥重用OpenAPI有效载荷定义,而不是发布第二套模型. 没有RxJS或MQTT依赖.
AWS的工作人员方法涉及一般观察,指挥和设置资源. 使用 requests.readAwsObservations 选择当前观测系列, getAwsSettings 读取单子设置阴影,以及 updateAwsSettings 以预期版本补丁输入的设置。 生成的 staffRealtime.hub.watchAwsObservations, (中文(简体) ), watchAwsCommand 财务报告和审定财务报表 watchAwsSettings 方法返回本地信号流。 见 AWS 资源映射 用于数据库和命令接受语义.
运行时间需要标准的获取、请求、 Blob、 中止控制器和 AbortSignal.any编号 :throwIfAborted,加由 SignalR 支持的 WebSocket 执行。 在需要时创建客户端之前,先提供相关的平台多填充.
改造和建造
这个 协议所有权指南 识别来源
每个合同和上游生成步骤。 编辑这些来源之前
重新生成这个客户端. openapi/api.json, (中文(简体) ), src/generated, (中文(简体) ), src/signalr, (中文(简体) ),
src/device-schema.ts 财务报告和审定财务报表 src/workflow-schema.ts 产出
由客户建设和消费者.
从寄存器根 :
dotnet tool restore
dotnet restore services/api/src/Api.csproj --locked-mode
dotnet build services/api/src/Api.csproj --no-restore
npm ci --ignore-scripts
npm run contract --workspace @bikefinder/api-client
npm run generate --workspace @bikefinder/api-client
npm run check --workspace @bikefinder/api-client
npm test --workspace @bikefinder/api-client
npm run build --workspace @bikefinder/api-client
被绑定的.NET工具配置于 .config/dotnet-tools.json. 合同导出在当地运行已建服务以获取 OpenAPI;不需要Firebase 证书或实时请求。 如果任一生成器都失败, 则生成失败 。 生成源是承诺的,必须一起再生. tsc-alias 在汇编无害环境管理包时解决产生的无扩展进口。 重点测试包括认证、文件忠诚、二进制写作、不确定的写作答复、本地代理引用/取消和处置.
发布
弹出此软件包的版本和根锁文件 . 发布 API 客户端
(单位:千美元)publish-client.yml当软件包显示在 main;也可以手工操作. 工作流程检查生成的策略, 运行
使用 GitHub OIDC 创建并发布 SDK 测试。 它没有部署AWS
服务,不需要 npm 令牌或每版浏览器批准.
Npm 软件包的可信任的出版商必须命名组织 bikefinder, (中文(简体) ),
仓库 aws_cloud工作流程 publish-client.yml直接 npm publish
允许且没有环境名称。 此账户设置在
软件包的 npm 设置。 见 npm 信任的出版。 。 。 .
命令 HTTP 和信号R 方法返回 AwsCommand请求、中介出版物和 execution.accepted编号 :execution.completed 这些是资源中独特的阶段。 客户端不再加入命令-结果观测或暴露出单独的结果端点. 完成部分包括一个输入的响应数据联盟和经认证的接收时间.
观察时间戳
观测历史和当前阅读 measuredAt 财务报告和审定财务报表 receivedAt。 。 。 .
观察ID是不透明的服务器生成的引用. 他们没有靴子或
序列信息。 不同的行可以有相同的捕获时间戳;
客户不得推断其身份证上的人身订单。 历史可以包含
单独一行,用于同一读数的一次发送.
源合同在SDK 1.0.14后有所改变. 在部署消费者之前, 发布下一次 SDK 发布并更新其注册依赖和锁定文件. 本地验证可以使用新建的 SDK; 保留该临时覆盖 承诺的消费者依赖.
设置响应使用 API 拥有 AwsSettingsSnapshot hTTP 和信号: 已读 desired, (中文(简体) ), reported, (中文(简体) ), application、能力和计划/版本证据. readIssues 识别无法解释的 API 存储值。 该资源不会暴露潜在的AWS阴影文档或其独立所有者. 设置字段和界限来自与固件相同的协议注册.
指挥部读取验证所储存的身份、目录论据、文物和执行证据。 错误的单命令读取返回 command_unreadable; 命令页面保存有效项目并附加请求 readIssues。两个命令流都发出 AwsCommandUpdate 或经过验证 command 或一个 readIssue,允许随后的事件继续下去.
支持的API消费者
SDK 2.0.0是明确批准的发射前模式之后的支持基线
对齐。 代替实验 powerSaving编号 :precision 模式名称和
它们的时间设置名称使用 standard编号 :security更早的客户需要
这些AWS资源一次性升级. 采取的宽容应对政策
在1.0.27中保留。 模式可用性是一个 ID 列表, 和选中的模式 ID
是对每个跟踪器的云目录进行验证的打开字符串。 添加或删除
目录选择不需要再发布 SDK .
API CI 安装所选择的最古老支持的不可移动 npm 释放
tools/check-api-compatibility.mjs。它验证新服务器序列化
使用已出版的读取器的防火炉、指令和设置装置
其HTTP变压器和流电源计划,并检查信封中的添加
和筑巢水平。 软件包包括它出口的 OpenAPI 合同
下级 @bikefinder/api-client/openapi 为了比较.
这个 compatibility 职务与公布的合同相对应
对这两份文件都采取同样的宽容政策。 请求验证必须严格.
门拒绝删除的端点或响应字段、不兼容类型和
界限、新需要的输入和互不相容的符号更改。 添加单独的 API
用于打破更改并保留所支持的 v1 路由的版本。 提高
最古老的支持SDK版本是明确的退休决定,而不是例行公事
通过CI的方式。 开发部署和生产促进都需要这项工作.
运行时验证仍然拒绝错误的已知数据. 申请应予保留 最后一个有效的流消息,并隔离每个资源的失败。 补丁时 设置, 只发送已更改的支持字段; 保存不熟悉的响应字段 并且不将完整答复复制到书面有效载荷中.