Medusa API 路由 TSDoc 规范:为 packages/medusa/src/api 路由处理器编写 @featureFlag 与 @since 注释

原创2026-09-09 12:25:001,868 阅读
文章标签:电商后端企业应用前端流程编排认证鉴权插件系统

Medusa API 路由 TSDoc 规范:为 packages/medusa/src/api 路由处理器编写 @featureFlag 与 @since 注释

导读

本文聚焦 Medusa 开源仓库中 API 路由文件的 TSDoc(TypeDoc)注释规范:路由处理器文件位于 packages/medusa/src/api/admin/ 与 packages/medusa/src/api/store/,其导出的 GET、POST、DELETE、PATCH 等命名 HTTP 处理器需要遵循一套极简注释策略——只允许 @featureFlag 与 @since 两个自定义标签,拒绝完整方法文档。读完本文,你将掌握如何精确判定一个路由是否处于特性开关(feature flag)之后、如何判断路由是否为新增、何时应当(以及何时绝不应当)添加 TSDoc,并能结合 FeatureFlag.isFeatureEnabled()、defineFileConfig() 与特性开关定义文件在源码层面的真实行为来写出可被文档生成器正确消费的注释。

1. 路由文件在哪里:目录结构与导出约定

根据 api-routes.md 与仓库实际布局,Medusa 的 API 路由文件集中在两个目录:

  • packages/medusa/src/api/admin/——管理端 API(后台操作,通常需要认证与权限)
  • packages/medusa/src/api/store/——商店前台 API(面向消费者)

例如当前仓库中 packages/medusa/src/api/admin/index/sync/route.ts、packages/medusa/src/api/admin/locales/route.ts、packages/medusa/src/api/admin/rbac/me/permissions/route.ts 都属于此类文件。此外 packages/medusa/src/api/ 下还有 auth/、cloud/、hooks/ 等目录以及公共的 middlewares.ts,但 TSDoc 规范只覆盖 admin/ 与 store/ 中的路由处理器。

这些文件的一个核心约定是:导出命名 HTTP 方法处理器函数,函数名就是 HTTP 动词本身:

export const GET = async (
  req: AuthenticatedMedusaRequest<HttpTypes.AdminProductListParams>,
  res: MedusaResponse<HttpTypes.AdminProductListResponse>
) => {
  // ...
}

export const POST = async (req, res) => {
  // ...
}

从框架侧看,这种命名约定与 packages/core/framework/src/http/router.ts 中的路由装配逻辑对应——框架会读取每个 route.ts 文件并查找导出的 HTTP 动词函数来注册路由。

2. 路由处理器 TSDoc 的三条铁律

规范对路由处理器注释的约束非常明确,任何违背都会导致生成的文档不正确:

  1. 只给导出的处理器函数(GET、POST 等)添加 TSDoc,不要给文件内其它符号添加。
  2. 保持极简:只允许 @featureFlag 和/或 @since,不要写完整的方法文档。
  3. 严禁添加 @param、@returns、@example 或任何描述性文字到路由处理器上。

第三条很容易被习惯性违反——因为同仓库中其它文件类型(服务接口、JS SDK 方法、workflow SDK 函数)都要求完整 JSDoc,唯独路由处理器是例外。理由是路由处理器的签名与行为已经由 HTTP 类型系统(HttpTypes.*)与 OpenAPI 规范描述,重复描述会产生维护负担与文档漂移。

决策表:何时加哪个标签

条件 添加
处理器体内调用了 FeatureFlag.isFeatureEnabled(XFlag.key) @featureFlag <flag_key>
处理器是本轮 commit diff 中新增的 @since <version>
处理器已存在 且 无特性开关 什么都不加

注意第三行:“已存在且无特性开关”的路由不加任何 TSDoc。也就是说,空白注释块甚至比“错误的注释”更符合规范——如果没有任何可声明的事实,就不要写。

3. 如何检测特性开关

3.1 方法一:处理器体内的 FeatureFlag.isFeatureEnabled(...)

在处理器函数体内搜索 FeatureFlag.isFeatureEnabled(...) 调用。例如参考文档给出的模式:

// This route is behind the "index_engine" feature flag
export const GET = async (req, res) => {
  if (FeatureFlag.isFeatureEnabled(IndexEngineFeatureFlag.key)) {
    // ...
  }
}

@featureFlag 的值是开关的 key 字符串。例如 IndexEngineFeatureFlag.key 展开后就是 "index_engine",因此注释写作 @featureFlag index_engine。

当前仓库中,packages/medusa/src/api/admin/index/details/route.ts 与 packages/medusa/src/api/admin/index/sync/route.ts 都通过 Modules.INDEX 与索引模块交互,并标注 @featureFlag index;packages/medusa/src/api/admin/locales/route.ts 标注 @featureFlag translation;packages/medusa/src/api/admin/rbac/me/permissions/route.ts 标注 @featureFlag rbac。

3.2 方法二:条件注册与 defineFileConfig

规范还要求检查路由文件是否基于特性开关被条件注册。这是第二条重要证据链,仓库中有真实的工程实践:packages/core/utils/src/common/define-file-config.ts 提供了 defineFileConfig(config) 辅助函数,用于声明“任何被 Medusa 自动加载的文件”的配置,其源码注释明确写道:

It is used to avoid loading files that are not required. Like a feature flag that is disabled.

该模块维护了一个 FILE_CONFIGS Map,通过 getCallerFilePath() 记录调用者文件路径,并提供 isFileDisabled(path) 检查 isDisabled 回调的结果。典型用法如 packages/medusa/src/api/admin/locales/route.ts 末尾:

defineFileConfig({
  isDisabled: () => !FeatureFlag.isFeatureEnabled(TranslationFeatureFlag.key),
})

以及 packages/medusa/src/api/admin/rbac/me/permissions/route.ts:

defineFileConfig({
  isDisabled: () => !FeatureFlag.isFeatureEnabled(RbacFeatureFlag.key),
})

这类文件虽然处理器体内未必直接调用 isFeatureEnabled,但整个文件在开关关闭时都不会被加载,因此同样需要 @featureFlag。

3.3 特性开关 key 从哪来:FlagSettings 定义文件

@featureFlag 使用的 key 字符串并非凭空捏造,而是来自 packages/medusa/src/feature-flags/ 下的 FlagSettings 定义。以 packages/medusa/src/feature-flags/view-configurations.ts 为例:

import { FlagSettings } from "@medusajs/framework/feature-flags"

const ViewConfigurationsFeatureFlag: FlagSettings = {
  key: "view_configurations",
  default_val: false,
  env_key: "MEDUSA_FF_VIEW_CONFIGURATIONS",
  description: "[WIP] Enable view configurations for data tables",
}

export default ViewConfigurationsFeatureFlag

FlagSettings 的 key 字段就是 TSDoc 中 @featureFlag 应写的字符串;env_key(如 MEDUSA_FF_VIEW_CONFIGURATIONS)则是运行时通过环境变量启用该开关的方式。当前仓库的 packages/medusa/src/feature-flags/ 下还包含 index-engine.ts、rbac.ts、translation.ts、caching.ts、backend-hmr.ts、rbac-filter-fields.ts 等定义文件,它们分别对应文档示例中的 index_engine、view_configurations 等 key。

框架侧的行为可由 feature-flags.spec.ts 与 flag-router.ts 印证:FeatureFlag.isFeatureEnabled(...) 支持字符串与嵌套对象两种参数形式,packages/core/framework/src/http/router.ts 中也存在 FeatureFlag.isFeatureEnabled("rbac")、FeatureFlag.isFeatureEnabled("backend_hmr") 这类基于开关动态装配路由的真实调用。

4. 四种完整示例

参考文档给出了四类场景的完整示例,全部可以在当前仓库中找到同构实现。

4.1 仅有特性开关

/**
 * @featureFlag index_engine
 */
export const GET = async (
  req: AuthenticatedMedusaRequest<HttpTypes.AdminProductListParams>,
  res: MedusaResponse<HttpTypes.AdminProductListResponse>
) => {
  // ...
}

仓库对应实现如 packages/medusa/src/api/admin/index/details/route.ts:

/**
 * Get the index information for all entities that are indexed and their sync state
 *
 * @since 2.11.2
 * @featureFlag index
 */
export const GET = async (
  req: AuthenticatedMedusaRequest<void>,
  res: MedusaResponse<HttpTypes.AdminIndexDetailsResponse>
) => {
  const indexModuleService = req.scope.resolve(Modules.INDEX)
  const indexInfo = await indexModuleService.getInfo()
  res.json({ metadata: indexInfo })
}

4.2 新增路由 + 特性开关

/**
 * @since 2.14.0
 * @featureFlag view_configurations
 */
export const GET = async (
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse<HttpTypes.AdminViewConfigurationListResponse>
) => {
  // ...
}

@since 与 @featureFlag 的顺序通常为 @since 在上、@featureFlag 在下(参考 SKILL.md 中自定义标签表格的排列顺序)。

4.3 新增路由、无特性开关

/**
 * @since 2.14.0
 */
export const POST = async (
  req: AuthenticatedMedusaRequest<AdminCreateRegionType>,
  res: MedusaResponse<HttpTypes.AdminRegionResponse>
) => {
  // ...
}

仓库同构示例:packages/medusa/src/api/admin/index/sync/route.ts 使用 @since 2.11.2 + @featureFlag index,packages/medusa/src/api/admin/locales/route.ts 使用 @since 2.12.3 + @featureFlag translation——即“新增”与“开关”两个维度相互独立,可自由组合。

4.4 已存在路由、无特性开关——不加 TSDoc

// No TSDoc added — route is existing and has no feature flag
export const GET = async (
  req: AuthenticatedMedusaRequest<HttpTypes.AdminOrderListParams>,
  res: MedusaResponse<HttpTypes.AdminOrderListResponse>
) => {
  // ...
}

这是最容易犯错的场景:经验不足的贡献者倾向于给所有路由补注释,但规范明确要求这里什么都不写。

5. 非处理器导出如何处理

路由文件有时会导出校验器(validator)或辅助函数(helper)。例如大量路由使用 validateAndTransformBody、validateAndTransformQuery 等中间件或独立的 schema 校验器。规范对此的处理原则是:

These are typically not exported from the module's public surface and do not need TSDocs.

即:这类符号通常不属于模块的公开 API 面,不需要 TSDoc。只有处理器函数才是文档生成器消费的对象。

6. 标签来源与约束(与整体 TSDoc 体系的关系)

@featureFlag 与 @since 并非 JSDoc/TypeDoc 标准标签,而是 Medusa 在 www/utils/packages/typedoc-config/tsdoc.json 中注册的自定义标签。根据 SKILL.md:

  • @featureFlag <name>(block):导出项需要启用某个特性开关
  • @since <version>(block):导出项在该版本新增(只能使用任务中提供的版本号,严禁臆造)

两条硬性约束对所有文件类型生效、对路由尤其关键:

  1. 严禁捏造 @since 版本号——只使用 prompt 中传入的版本。路由示例中的 2.14.0、仓库中的 2.11.2、2.12.3 都是实际版本号,编写时必须以给定版本为准。
  2. 只允许使用 tsdoc.json 中登记的自定义标签,标准 TypeDoc/JSDoc 标签(@param、@returns、@example、@deprecated、@remarks 等)虽然普遍可用,但路由处理器是例外场景,不得混用。

7. 实操检查清单

给某个路由文件写 TSDoc 前,按顺序自查:

  1. [ ] 该文件是否位于 packages/medusa/src/api/admin/ 或 packages/medusa/src/api/store/?
  2. [ ] 只给导出的处理器(GET/POST/DELETE/PATCH)加注释了吗?
  3. [ ] 处理器体内是否调用了 FeatureFlag.isFeatureEnabled(XFlag.key)?
  4. [ ] 文件末尾或配置处是否使用了 defineFileConfig({ isDisabled: ... }) 做条件注册?
  5. [ ] 开关的 key 是否与 packages/medusa/src/feature-flags/*.ts 中 FlagSettings.key 一致?
  6. [ ] 处理器是否为新增?@since 版本号是否来自任务给定版本、而非臆造?
  7. [ ] 是否不小心添加了 @param、@returns、@example 或描述段落?
  8. [ ] 如果处理器已存在且无开关,是否保持了“不加任何 TSDoc”?

遵循这套规范产出的注释,会被 Medusa 的文档生成管线正确转换为 API 参考文档中“受特性开关保护”与“版本引入”标注,而不会产生虚假的版本信息或噪音描述。

参考文件

登录后查看全文
medusa