组合框架 HTTP 模块
@equinor/fusion-framework-module-http 是Fusion框架应用程序和模块的HTTP层。 它给了你一个有框架感知配置, MSAL感知请求, RxJS 观察器以及可重复使用的请求/响应管道的取取式客户端工厂.
如果您只记得关于此软件包的一件事, 请做这个: 您配置过一次客户端, 并在使用时创建新的客户端实例 .
如果您是新到Fusion框架, 或者只是想呼叫 API, 请从 configureHttpClient(...), (中文(简体) ), createClient(...),以及 json()。 。 。 .
如果您正在构建更高级的工作流程,此软件包也会支持 RxJS 的可观测组成,请求和响应流检查,自定义选择器,请求和响应操作器, MSAL 意识请求,以及服务器发送事件.
这个软件包给你什么
- 为您交谈的后端指定 HTTP 客户端配置 .
- 新的客户端实例,所以从一种用法发出的头和处理器不会漏入另一种用法.
- 承诺和可观察API在同一请求管道上.
- 内建支持JSON,blobs,和服务器发送事件.
- 交叉行为的请求和响应处理者.
- 当认证模块可用时, MSAL 范围支持 .
心理模式
将HTTP模块视为客户端工厂,而不是单通HTTP客户端.
- 在应用程序或模块设置时配置一个命名的客户端 .
- 打电话
createClient(name)当你需要提出请求. - 使用
fetch, (中文(简体) ),json, (中文(简体) ),blob,或sse$在客户的例子. - 在其中添加共享行为
onCreate, (中文(简体) ),requestHandler,以及responseHandler。 。 。 .
每个请求都经过同样的高层次流程:
- 决定
baseUri并请求路径进入完整的 URL. - 运行请求处理器 .
- 发送请求
request$。 。 。 . - 执行接取电话 .
- 运行响应处理器.
- 发送回复
response$。 。 。 . - 应用可选选择器.
新建时在此开始
最简单的有用路径是这样的:
- 为一个后端注册一个命名客户端 .
- 从该名称创建客户端 .
- 打电话
json()正常API电话.
这给你:
- 一致的基础 URL
- 共享认证范围配置
- 共享信头或卫士通过
onCreate - 每个用户使用一个新客户实例
如果你不确定是使用承诺还是观察,从 json()移动到 json$() 当您需要 RxJS 运算符时,通过不订阅取消,或流组成.
当使用哪个 API
| 需求 | 使用 |
|---|---|
| 调用正常的 JSON API | json() 或者说 json$() |
与生俱来 Response | fetch() 或者说 fetch$() |
| 下载文件或 blob 响应 | blob() 或者说 blob$() |
设定流线 text/event-stream 结束点 | sse$() |
| 每个后端应用标准页眉、范围或日志 | 命名客户端配置 + onCreate |
安装
pnpm add @equinor/fusion-framework-module-http
快速启动
设置时配置一个命名客户端 :
configurator.configureHttpClient('catalog', {
baseUri: '/api/catalog',
defaultScopes: ['api://catalog-api/.default'],
onCreate: (client) => {
client.requestHandler.setHeader('X-App-Name', 'portal');
},
});
初始化框架后使用配置的客户端 :
type CatalogItem = {
id: string;
title: string;
};
const client = framework.modules.http.createClient('catalog');
const items = await client.json<CatalogItem[]>('/items');
这里发生什么了
catalog是一个命名的配置,而不是一个长寿的共享客户端实例.createClient('catalog')创建新客户端, 包含配置的基础 URI, 处理器和默认范围 .json()运行请求的管道并返回解析的 JSON.
公共条目
| 入境点 | 目的 |
|---|---|
@equinor/fusion-framework-module-http | 模块定义、配置/提供者帮助、导出错误和共享客户端类型 |
@equinor/fusion-framework-module-http/client | HttpClient, (中文(简体) ), HttpClientMsal类型 |
@equinor/fusion-framework-module-http/operators | HttpRequestHandler, (中文(简体) ), HttpResponseHandler, (中文(简体) ), ProcessOperators, (中文(简体) ), capitalizeRequestMethodOperator, (中文(简体) ), requestValidationOperator, (中文(简体) ), sseMap类型 |
@equinor/fusion-framework-module-http/selectors | jsonSelector, (中文(简体) ), blobSelector, (中文(简体) ), createSseSelector, (中文(简体) ), ResponseSelector和 SSE 选择器类型 |
@equinor/fusion-framework-module-http/errors | HttpResponseError, (中文(简体) ), HttpJsonResponseError,以及 ServerSentEventResponseError |
对大多数球队来说,顶级包加 selectors 或者说 operators 子路径是足够的.
配置客户端
需要稳定配置后端时使用命名客户端:基础URL,默认的MSAL范围,共享头,以及请求或响应政策.
HTTP模块支持三种常见的配置风格:
- 名称客户端
configureHttpClient(name, options) - 低级模块配置
configureHttp(...) - 临时客户端
createClient({ baseUri })或者说createClient('https://...')
SAML 范围行为是客户端配置的一部分:
defaultScopes属于配置的客户端- 按请求数
scopes附录为defaultScopes - 仅当认证模块可用且最终范围列表为非空时, 才会获得符号
见 客户端配置 用于配置选项, onCreate,直接模块集成,定制客户类,临时客户类,以及 ClientNotFoundException 行为.
核心 API
每次打给 createClient() 返回具有自己处理器状态的新实例.
| 方法 | 回返 | 用它当 |
|---|---|---|
fetch(path, init?) | Promise<Response | T> | 你想生下来 Response,或者您想要提供自定义选择器 |
fetch$(path, init?) | Observable<Response | T> | 您想要通过不订阅来取消 RxJS 组成或取消 |
json(path, init?) | Promise<T> | 你给JSON API打电话 |
json$(path, init?) | Observable<T> | 你想要JSON API电话作为可观察 |
blob(path, init?) | Promise<BlobResult> | 您正在下载一个文件或二进制有效载荷 |
blob$(path, init?) | Observable<BlobResult> | 你想在可观察的管道中 做出零星的反应 |
sse$(path, init?, options?) | Observable<ServerSentEvent<T>> | 您正在消耗服务器发送事件 |
execute(method, path, init?) | fetch, (中文(简体) ), fetch$, (中文(简体) ), json,或 json$ 结果 | 你得动态地选一种方法 |
abort() | void | 您想要取消此客户端启动的每个飞行请求 |
折旧的别名仍然存在,但新的代码应该更可取 fetch() 财务报告和审定财务报表 json() 结束 fetchAsync() 财务报告和审定财务报表 jsonAsync()。 。 。 .
保证还是观察?
- 在您只想要单一请求的结果时使用承诺方法.
- 需要 RxJS 组成时使用可观察到的方法,通过未订阅取消,或者基于流集成.
- 可观察之法为寒. 直到你签了字,才发送任何信息.
- 采用承诺方法
firstValueFrom(...)使用相应的可观察方法. request$财务报告和审定财务报表response$请查看用户请求和回应.
实际上:
json('/items')是最简单的页面负荷或命令式调用选择.json$('/items')当请求依赖于另一个流时,例如路由参数、用户选择、已取消的搜索条件、刷新触发器或SSE事件处理时,是更好的选择.
见 可观察模式 用于RxJS构成、注销、请求和反应检查以及选择器再利用.
选择者和处理者
选择者和处理者解决不同问题:
- 选择器塑造应用程序所消耗的响应值
- 请求处理者形状向外传送行为
- 响应处理器在选择者解析运行前执行响应政策
内建选择器包括 jsonSelector, (中文(简体) ), blobSelector,以及 createSseSelector。默认请求管道包括 capitalizeRequestMethodOperator() 财务报告和审定财务报表 requestValidationOperator()。 。 。 .
见 选择者和处理者 用于指导何时使用每个API,如何添加可重复使用的运算符,以及如何将运输关切与响应解析分开.
服务器事件
使用 client.sse$() 当结束点返回时 text/event-stream 您想要解析事件对象而不是手动读取流。 对于较低级别的构成,使用 createSseSelector 或者说 sseMap。 。 。 .
见 服务器事件 页:1 sse$() 使用、事件过滤、心跳处理、中止行为、低级SSE 助手,以及 ServerSentEventResponseError 处理.
错误类型
| 错误 | 当使用时 |
|---|---|
ClientNotFoundException | createClient(name) 使用既不配置也不绝对的密钥调用 http: 或者说 https: 網址 |
HttpResponseError | 一般响应或选择器失败,包括同步选择器执行失败 |
HttpJsonResponseError | JSON分析失败或非OK JSON反应 |
ServerSentEventResponseError | 无效的 SSE 响应, 如非 OK 状态、 无法读取的正文或错误的内容类型 |
原生取回错误也仍然可以浮出水面,包括中止和网络故障.
测试
注册一个短路中间软件通过 configurator.http.addMiddleware(...) 在不触及网络的情况下回答请求——不需要单独的模拟客户端或配置器. createOpenApiMockMiddleware (单位:千美元)@equinor/fusion-framework-module-http/mock调整一个 @equinor/fusion-openapi-mock 实例,用于假冒整个 OpenAPI 文档.
见 测试 中间软件合同和 createOpenApiMockMiddleware。 。 。 .
高级指南
- 客户端配置: 命名客户端,
configureHttpClient, (中文(简体) ),configureHttp, (中文(简体) ),onCreate,定制客户类,以及临时客户类 - 可观察模式数字 :
fetch$, (中文(简体) ),json$, (中文(简体) ),request$, (中文(简体) ),response$,取消,以及 RxJS 组成 - 选择者和处理者数字 :
jsonSelector, (中文(简体) ),blobSelector,请求处理器,响应处理器和内置操作器 - 服务器事件数字 :
sse$, (中文(简体) ),createSseSelector, (中文(简体) ),sseMap,事件过滤、心跳和中止行为 - 测试:中间软件合同,
addMiddleware,以及createOpenApiMockMiddleware
记得的事
createClient(name)掷出ClientNotFoundException用于未知的客户端密钥.hasClient(name)当客户端配置可能是可选时,则有用.json()财务报告和审定财务报表json$()字符串对象体JSON.stringify(...)附加 JSON 请求标题.fetch()财务报告和审定财务报表fetch$()除非您提供selector。 。 。 .execute()当前支持fetch, (中文(简体) ),fetch$, (中文(简体) ),json,以及json$只有这个.- 如果您通过配置客户端
config.http.configureClient(name, callback),该调用存储为onCreate并运行每次创建新的客户端实例.