HttpAdapterOptions

Defined in: packages/rxdb-adapter-http/src/http.interface.ts:461

new RxDBAdapterHttp(rxdb, options) 的配置。

Extends

• Partial<HttpNumericConfig>

Properties

auth?

optional auth?: HttpAuthHook;

Defined in: packages/rxdb-adapter-http/src/http.interface.ts:465

---

baseUrl

baseUrl: string;

Defined in: packages/rxdb-adapter-http/src/http.interface.ts:463

相对 URL 的基地址；handler 返回绝对 URL 时忽略

---

changeFeed?

optional changeFeed?: HttpChangeFeedOptions;

Defined in: packages/rxdb-adapter-http/src/http.interface.ts:553

Experimental

启用变更通知通道（US-023 AC#12）。缺席即关闭。

Remarks

关着时行为与本故事之前逐字相同：零新增请求、零连接，远端变更靠下一次 find() 回远端校验发现。开着时远端一变，订阅同一实体的活查询立刻重跑。

与 conditionalRequests 同一条理由必须显式开启：不是所有后端都实现得了推送， 而适配器无从探测——一个不实现该端点的后端，表现是连接被拒，不是「没有变更」。

连不上时不降级成轮询。 偷偷切一条「每 N 秒问一次」的二等通道，会让接入方拿到一个 说不清延迟上界的实时性，出问题还查不出走的是哪条路。连不上就是连不上，按退避重连并 通过 HttpChangeFeedOptions.onUnavailable 报出来。

连接成功（含每次重连）会对所有走本适配器的实体各上报一次失效。 这是正确性要求 不是优化：断开期间发生的变更没有任何人会补发，不主动失效一次，客户端会把「没收到消息」 当成「没有变化」，而这次误判可能一直持续下去。代价是一次 metadata 往返，无变化则零行拉取。

Example

new RxDBAdapterHttp(rxdb, {
  baseUrl,
  handlers,
  changeFeed: `{ url: 'changes', onUnavailable: report => myLogger.warn(report.message, report) }`
});

不在 1.0 兼容承诺内：协议目前只有参考后端一个实现，wire 形态可能随第二个实现调整。 层级口径见 requirements/versioning-policy.md「实验性层级」。

---

conditionalCacheSize?

optional conditionalCacheSize?: number;

Defined in: packages/rxdb-adapter-http/src/http.interface.ts:457

条件请求响应缓存的条目上限。默认 256；仅在 conditionalRequests 为 true 时生效。

Remarks

一页 / 一块各占一个条目，所以上限要按并发活跃查询的总页数估，不是按实体数。 取太小会让翻页里最热的首页被反复挤出，退化成没有缓存（不产生错误结果）。

Inherited from

HttpNumericConfig.conditionalCacheSize

---

conditionalRequests?

optional conditionalRequests?: boolean;

Defined in: packages/rxdb-adapter-http/src/http.interface.ts:488

启用 ETag / If-None-Match 条件请求（US-212 AC#28）。默认 false。

Remarks

必须显式开启，因为它只在远端真的发 ETag 并认 If-None-Match 时才有收益， 而这一点适配器无从探测。关闭时 fetchMetadata / findByIds 的行为与阶段 A 逐字相同： 不带条件头、不去重并发、304 照旧当错误。

开启后缓存的是响应（上次 200 的 JSON body），不是行——行缓存归 core 经本地适配器 落盘，本包按 AC#19 不碰。缓存按适配器实例存活、有界（HttpNumericConfig.conditionalCacheSize）、 disconnect() 时清空。

三组 header 只有一组进请求指纹。HttpRequestSpec.headers（handler 逐请求给的） 进——它是唯一会在同一条 URL 上区分投影的一组，不进就是两个租户共用一个条目。 HttpAdapterOptions.headers（本实例恒定）与 auth hook 产出的不进： 前者进去只是给每条键加同一段前缀，后者进去会让每次 token 轮换都全量失效。

换用户必须走 disconnect() / connect()：这是 auth header 不进指纹的代价—— 同一实例上直接换 token 会读到上一个身份的响应。

---

handlers

handlers: HttpHandlers;

Defined in: packages/rxdb-adapter-http/src/http.interface.ts:464

---

headers?

optional headers?: Record<string, string>;

Defined in: packages/rxdb-adapter-http/src/http.interface.ts:467

附加到所有请求的 header；与 auth hook 冲突时 auth hook 优先

---

idChunkSize?

optional idChunkSize?: number;

Defined in: packages/rxdb-adapter-http/src/http.interface.ts:443

findByIds 单块 id 数。默认 100（对标 SUPABASE_IN_CHUNK_SIZE）

Inherited from

HttpNumericConfig.idChunkSize

---

maxEmptyPages?

optional maxEmptyPages?: number;

Defined in: packages/rxdb-adapter-http/src/http.interface.ts:445

token 形态下连续空页容忍上限。默认 3；0 = 不容忍空页

Inherited from

HttpNumericConfig.maxEmptyPages

---

maxPages?

optional maxPages?: number;

Defined in: packages/rxdb-adapter-http/src/http.interface.ts:447

单次 fetchMetadata 总页数上限。默认 1000；触顶是抛错不是截断

Inherited from

HttpNumericConfig.maxPages

---

onEtagUnreadable?

optional onEtagUnreadable?: HttpEtagUnreadableHook;

Defined in: packages/rxdb-adapter-http/src/http.interface.ts:522

条件请求开着、响应是 200、却读不到 ETag 时被调用（US-215）。

Remarks

存在的理由：conditionalRequests 开启前远端认不认 If-None-Match 确实无从探测， 但开启后「一次都没生效」是适配器手上就有的铁证——一个 200 响应，条件请求开着， 却读不到 ETag。没有这个回调时它知道，只是没有嘴：请求照发、账单照付、缓存零命中， 而客户端侧一行日志都没有。

三条边界，缺一条这个回调就会变成新的麻烦：

• 它不改数据路径。 不配它时的行为与 US-215 之前逐字相同（丢弃该条目、正常返回）； 配了它也一样，回调只是多一次调用。
• 它不臆断成因，只给事实（见 HttpEtagUnreadableReport）。
• 它按缓存 key 去重，一个 key 只报一次；disconnect() 清缓存时一并清掉记录， 所以换了后端配置重连后会重新报。

回调抛出的错误被丢弃——不是「有别的通道兜着」，是真的没地方去：此刻正在报告的 就是「本包没有输出通道」这件事本身。诊断通道不该成为新的故障源，所以宁可丢。 需要知道自己的上报失败了，请在回调内部自行处理。

conditionalRequests 关着时永不触发：关着的开关不该产生噪音。

Example

new RxDBAdapterHttp(rxdb, {
  baseUrl,
  handlers,
  conditionalRequests: true,
  onEtagUnreadable: report => myLogger.warn(report.message, report)
});

---

pageSize?

optional pageSize?: number;

Defined in: packages/rxdb-adapter-http/src/http.interface.ts:441

单页条数，透传为 handler 的 ctx.limit。默认 1000（对标 SUPABASE_PAGE_SIZE）

Inherited from

HttpNumericConfig.pageSize

---

requestTimeoutMs?

optional requestTimeoutMs?: number;

Defined in: packages/rxdb-adapter-http/src/http.interface.ts:449

单个 HTTP 请求的超时上限（毫秒）。默认 30000

Inherited from

HttpNumericConfig.requestTimeoutMs