Rocket.Chat 实验性 REST API 端点（/api/experimental）机制深度解析

Rocket.Chat 实验性 REST API 端点（/api/experimental）机制深度解析

【免费下载链接】Rocket.ChatThe Secure CommsOS™ for mission-critical operations项目地址: https://gitcode.com/GitHub_Trending/ro/Rocket.Chat

实验性端点（Experimental Endpoints）是 Rocket.Chat REST API 中与稳定版/api/v1/...并行的一套独立命名空间：它允许功能在接口形态尚未定型时先上线生产环境，随时演进、随时下线，却不破坏/v1的 semver（语义化版本）承诺。本文以 docs/experimental-api-endpoints.md 为主线，结合其设计文档 docs/experimental-api-endpoints-plan.md 与apps/meteor/server/api下的真实源码，系统讲解该机制的定义、适用场景、生命周期、护栏工具以及如何新增一个实验性端点。

什么是实验性端点：命名空间即契约

Rocket.Chat 在常规 REST API 之外划出了一条独立的"不稳定通道"。所有端点位于/api/experimental/...前缀之下，并携带一份显式的稳定性契约：

/api/experimental/...下的端点是不稳定的。它们可能在任意版本中改变形态或被移除——无需通知，也没有弃用周期。该命名空间不附加任何 semver 承诺。

与之对照的是/api/v1/...：这是官方、稳定的 API 面。其端点遵循 semver，破坏性变更必须伴随主版本号升级，移除必须走完整的弃用（deprecation）周期。

这套设计的核心思想在 docs/experimental-api-endpoints-plan.md 中被概括为一句话——命名空间本身就是契约：调用者仅凭 URL 命中/api/experimental/*，就已经"主动选择了不稳定"。而/v1隐含的 semver 稳定承诺保持不变，两者互不干扰。

为什么需要这条通道

团队偶尔需要在 API 形态尚未定型之前把功能送到生产环境，常见的场景包括：

• 某个新功能的请求/响应契约仍需要通过真实流量来验证、演进；
• 端点为特定客户端（例如官方 UI 自身）而构建，尚未准备好将其承诺为公开、受支持的接口；
• 希望给功能挂上一块醒目的"使用风险自负"标牌，同时让它在真实环境中持续成熟。

如果没有实验通道，团队往往只剩两个坏选择：要么把一个还没把握的设计直接冻结到/v1（之后要么永远背着它、要么靠大版本升级来打破它），要么等到 API 设计"完美"才允许功能进入生产。实验性端点提供了第三条路径——先上线，自由迭代，成熟后再正式承诺。

该不该用实验端点：决策指南

原文档给出了清晰的判断标准，整理如下。

应该使用实验性端点，当：

• 请求/响应形态很可能随功能成熟而改变；
• 希望在正式承诺契约之前获得生产流量和真实反馈；
• 消费方是内部或已明确"选择加入"的客户端，可以容忍发布间（release-to-release）的破坏性变更；
• 否则你会忍不住"先随便挂到/v1上，以后再修"。

不应当使用实验性端点，当：

• 端点面向期望稳定性的第三方集成方——他们不应该在每次发布间追踪破坏；
• 契约已经充分理解、不太可能变化——直接放/v1；
• 你只是想把experimental当作永久居所，借此回避稳定 API 应有的纪律。它是暂存区（staging area），不是垃圾场。

发布实验端点的约定与期望

一旦在实验命名空间下发布端点，需要遵守以下几点期望：

• 它不是永久的。每个实验端点最终只有两个归宿：契约稳定后升级到/v1，或验证失败后被移除。一个无限期停留在experimental下的端点本身就是一个"异味"（smell）——意味着某个决策已经逾期未决。
• 调用方会在运行时收到警告。每个实验端点的响应都会携带x-experimental: true——这是官方支持的、用于在客户端代码中探测并呈现"实验状态"的信号。响应同时携带Warning: 299 ...头，仅为兼容仍在读取它的旧工具链而保留：RFC 9111 已经废弃了Warning头及其警告码，因此不要在新客户端逻辑上依赖它。
• 类型化客户端必须显式选择加入。实验端点被声明在独立的ExperimentalEndpoints类型中，而不是主Endpoints联合类型里，从而保证稳定版 SDK 的对外类型面保持诚实。使用者需要显式 import 它们。
• 只使用类型化 API。注册端点必须使用.get()/.post()/.put()/.delete()加 AJV 校验器。不要使用.addRoute()：它在整个 API 中已被标记@deprecated，而一个专门用于迭代新契约的命名空间，是最后应该给遗留注册路径添砖加瓦的地方。

运行时信号：两个响应头的真实形态

从源码 apps/meteor/server/api/v1/middlewares/experimental.ts 可以看到这两个头的实际实现：

const WARNING_HEADER = '299 - "experimental: endpoint is unstable and may change without notice"'; export const experimentalWarningMiddleware = ({ basePathRegex }: { basePathRegex: RegExp }): MiddlewareHandler => async (c, next) => { if (!basePathRegex.test(c.req.path)) { return next(); } c.res.headers.set('x-experimental', 'true'); c.res.headers.set('Warning', WARNING_HEADER); await next(); };

因此一次实验端点调用的真实响应头形如：

HTTP/1.1 200 OK x-experimental: true Warning: 299 - "experimental: endpoint is unstable and may change without notice"

中间件注释清晰说明了设计取舍：x-experimental: true是受支持的程序化信号；Warning: 299的警告码 299 源自已被 RFC 9111 取代的 RFC 7234，仅面向仍在展示该头的旧工具链输出，随时可以移除而不构成破坏性变更。header 写入方式模仿了弃用机制中 apps/meteor/server/lib/deprecationWarningLogger.ts 的writeDeprecationHeader。

中间件为何挂在共享挂载点而非路由器上

值得注意的工程细节：该中间件不注册在API.experimental.router上，而是在 api.ts 的startRestAPI中注册到共享的/api挂载点、且位于cors之前。原因是cors中间件对拒绝的预检（preflight）请求直接返回 403/405 而不会调用next()——如果中间件只挂在路由器上，这些响应将永远无法被打上实验标记。而将 header 设置在c.res.headers上、在后续处理器运行之前完成，Hono 会将其合并进任何后续产生的响应，因此404 与 CORS 拒绝响应也会被覆盖。

这一点被单测 experimental.spec.ts 严格验证：

• /api/experimental/test的 200 响应带两个头；
• /api/v1/test的响应不带任何实验头；
• 未匹配的/api/experimental/nope返回 404 但依然带两个头；
• CORS 关闭时的预检拒绝（405）、来源不被允许时的预检拒绝（403）都带两个头；
• /api/v1的预检拒绝则不带。

生命周期：从 experimental 走向 official

原文档给出了清晰的生命周期图：

stabilizes experimental ───────────────▶ v1 (official, semver-stable) (/api/experimental/x) (/api/v1/x) │ │ does not pan out ▼ removed (no deprecation cycle needed)

升级（Elevating）到/v1

1. 确认契约已经稳定，并准备好按 semver 长期支持它。
2. 在/v1下新增端点：在API.v1上注册，并把其类型声明到属于Endpoints联合体的对应*Endpoints类型中。
3. 可选：在过渡期内让实验路径继续转发到新的/v1路径，以免升级当天就打断现有调用方。
4. 过渡窗口关闭后，删除实验声明。

移除（Removing）实验端点

移除一个实验端点不需要弃用周期——这份自由正是该命名空间存在的全部意义。不过作为一种礼貌，仍应记录移除动作，并向已知消费方提前打个招呼。

护栏与工具

• 同一条路径绝不同时存在于两个联合体中。重复的 key 会在暗中给一个被宣传为不稳定的路径挂上 semver 义务，因此"升级"意味着把声明移动到稳定的*Endpoints类型，而不是在实验侧留下一份拷贝。这一点并没有编译期强制——靠/experimental/路径前缀保证两个联合体在实践中不会重叠。
• 生成的 API 文档刻意跳过实验端点。OpenAPI / 文档生成扫描的是Endpoints联合体，而实验路径被有意排除在外，因此不会出现在公开 API 文档中。这是有意设计：一个不稳定的接口面不应被宣传为已文档化契约的一部分。运行时x-experimental/Warning头以及本文档才是该命名空间的对外呈现方式。
• 指标是升级信号。实验流量会被记录进 REST API 的 Prometheus 指标，标签为version=experimental，因此真实使用量可以作为端点是否该毕业到/v1、还是该被移除的决策依据。

源码纵深：实验实例是如何被搭建起来的

理解这套机制的最快方式，是沿着 apps/meteor/server/api/api.ts 追踪API.experimental从定义到挂载的全过程。

1)version字符串直接决定 URL 路径段

API对象通过工厂函数createApi构造了三个版本化实例：

export const API: { api: Router<'/api', any, APIActionHandler>; v1: APIClass<'/v1'>; experimental: APIClass<'/experimental'>; default: APIClass; // ... } = { ApiClass: APIClass, api: new RocketChatAPIRouter('/api'), v1: createApi({ version: 'v1', useDefaultAuth: true }), experimental: createApi({ version: 'experimental', useDefaultAuth: true }), default: createApi({}), };

在 ApiClass.ts 的构造函数里，version被拼进apiPath，进而决定路由挂载前缀：

this.version = properties.version; this.apiPath = [properties.apiPath, properties.version].filter(Boolean).join('/').replaceAll('//', '/'); // ... this.router = new RocketChatAPIRouter(`/${this.apiPath}`.replace(/\/$/, '').replaceAll('//', '/'));

所以version: 'experimental'会自动把该实例挂到/api/experimental/<name>，路由内部无需任何改动——这正是createApi({ version })把版本字符串映射为 URL 路径段的直接结果。

2) 挂载顺序与指标采样护栏

在startRestAPI（同一文件）中，实验路由器被插入到请求管线，位置在API.v1.router之后、作为兜底的API.default.router之前：

.use(API.v1.router) .use(API.experimental.router) .use(API.default.router).router

由于所有版本共享同一个/api挂载点，metrics.ts 中的每个指标中间件块都通过basePathRegex/excludePathRegex守卫来避免同一次请求被多次采样：

• 版本化块通过basePathRegex选择进入，例如/^\/api\/v1\//、/^\/api\/experimental\//；
• 覆盖默认路由（/api/info、/api/docs/json）及未匹配/api/*的兜底块，通过excludePathRegex: /^\/api\/(v1|experimental|apps)\//退出不属于自己的前缀。

实验流量因此被记录为指标标签version=experimental，可作为后续"是否毕业到/v1"的指标信号（见 api.ts 的第二个 metrics 块）。如果新增版本化命名空间，必须同步把它加入兜底块的excludePathRegex，否则会被重复计数。

3) 认证、限流等能力"免费"获得

实验端点之所以能自动获得认证（auth）、权限（permissions）、限流（rate limiting）、CORS、AJV 校验与指标能力，是因为它们全部来自createApi+startRestAPI的中间件链。设计文档特别强调了"实验端点免费获得限流"这一等价性承诺是有条件的：设置变更时需要触发刷新。在 api.ts 中可以确认，限流相关的设置监听回调同时刷新了API.v1与API.experimental：

const reloadRoutesToRefreshRateLimiter = () => { API.v1.reloadRoutesToRefreshRateLimiter(); API.experimental.reloadRoutesToRefreshRateLimiter(); }; settings.watch<number>('API_Enable_Rate_Limiter_Limit_Time_Default', (value) => { defaultRateLimiterOptions.intervalTimeInMS = value; reloadRoutesToRefreshRateLimiter(); });

计划文档同时披露了一个已知缺口：Accounts_CustomFields的 watcher 目前仍只更新API.v1。这在当前是无害的（尚无任何实验端点返回用户对象），但在出现此类端点前必须先补上。

类型层面的"显式选择加入"：ExperimentalEndpoints

实验端点之所以不会污染稳定客户端类型面，关键在于packages/rest-typings的导出设计。在 packages/rest-typings/src/index.ts 中：

// Opt-in experimental endpoint typings. Deliberately NOT part of the `Endpoints` // union above — see ./experimental for the rationale. export type * from './experimental';

即：ExperimentalEndpoints被从包根导出，但不并入interface Endpoints。于是PathPattern、Method、Path以及稳定类型化客户端都不会包含实验路径——需要类型化实验调用的消费方必须显式引入ExperimentalEndpoints。

新增实验端点的类型声明方式见 packages/rest-typings/src/experimental/index.ts，遵循/v1端点的分资源声明风格，且路径 key 必须以/experimental/开头：

export type ExperimentalEndpoints = { '/experimental/rooms.setCategory': { POST: (params: { roomIds: string[]; category: string | null }) => { success: true }; }; };

从源码结构看，主类型联合体与实验类型的分离正是"稳定 SDK 面保持诚实、实验接口强制显式选择加入"这一规则在类型系统层面的落地。

真实示例：rooms.setCategory

仓库中现存的一个实验端点实例是 apps/meteor/server/api/experimental/rooms.setCategory.ts。它完整展示了"只用类型化 API"的全部要素：API.experimental.post(...)注册、AJV 编译的body与分状态码response校验、authRequired与许可证（license）约束：

const isRoomsSetCategoryParamsPOST = ajv.compile<{ roomIds: string[]; category: string | null }>({ type: 'object', properties: { roomIds: { type: 'array', items: { type: 'string', minLength: 1 }, minItems: 1, uniqueItems: true, }, category: { type: 'string', nullable: true, not: { enum: [...SIDEBAR_SYSTEM_GROUP_KEYS] }, }, }, required: ['roomIds', 'category'], additionalProperties: false, }); API.experimental.post( 'rooms.setCategory', { authRequired: true, license: ['experimental-enterprise-features'], body: isRoomsSetCategoryParamsPOST, response: { 200: ajv.compile<void>({ /* success: true */ }), 400: validateBadRequestErrorResponse, 401: validateUnauthorizedErrorResponse, 403: validateForbiddenErrorResponse, }, }, async function action() { const { roomIds, category } = this.bodyParams; // 业务逻辑：校验用户偏好分类 → 批量更新订阅 → 通知变更 return API.experimental.success(); }, );

这个文件同时印证了计划文档中的一条规则：.get()/.post()/.put()/.delete()对路径泛型TSubPathPattern是开放的，不受限于keyof Endpoints，因此一个独立的实验实例天然能与类型系统协同工作，而无需任何路由内部的特殊分支。

TL;DR 总结

• 实验端点让你在 API 形态仍在剧烈变动时就能把它送上生产环境，却不必把自己锁死在 semver 里；
• 它们是暂存区，不是永久居所：每个端点要么毕业到/v1，要么被移除；
• 运行时通过x-experimental: true（受支持信号）与Warning: 299（仅为遗留工具链保留）两个响应头对外宣告不稳定状态；
• 需要稳定性保证时用/v1；会有第三方依赖它时也用/v1。

延伸阅读

• 机制设计文档：docs/experimental-api-endpoints-plan.md（含 5 步落地实施与测试清单）
• API 实例与挂载实现：apps/meteor/server/api/api.ts
• 版本路径拼装：apps/meteor/server/api/ApiClass.ts
• 实验响应头中间件及单测：apps/meteor/server/api/v1/middlewares/experimental.ts、experimental.spec.ts
• 指标采样守卫：apps/meteor/server/api/v1/middlewares/metrics.ts
• 类型化选择加入：packages/rest-typings/src/experimental/index.ts
• 现有实验端点实例：apps/meteor/server/api/experimental/rooms.setCategory.ts
• 被模拟的弃用响应头实现：apps/meteor/server/lib/deprecationWarningLogger.ts

【免费下载链接】Rocket.ChatThe Secure CommsOS™ for mission-critical operations项目地址: https://gitcode.com/GitHub_Trending/ro/Rocket.Chat