Medusa TSDoc 写作规范全解writing-tsdocs 技能与 Medusa 自定义标签体系实践【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa本文基于 Medusa 仓库内置的writing-tsdocs技能文档SKILL.md系统讲解如何为 Medusa 的 TypeScript 源码补充 TypeDocTSDoc注释覆盖 HTTP 类型、API 路由、UI 组件、数据模型、服务接口、JS SDK、抽象 Provider、Workflow SDK、core-flows 工作流/步骤与事件常量等十类文件并结合 tsdoc.json 中定义的 Medusa 自定义标签expandable、featureFlag、eventPayload等与仓库中的真实使用证据给出一套可直接落地的 TSDoc 写作方法论。一、技能定位writing-tsdocs 是什么writing-tsdocs是 Medusa 仓库.claude/skills/目录下定义的一个 AI 技能Skill其职责是为 Medusa 代码库中的 TypeScript 源文件添加和更新 TypeDoc 注释。技能描述明确列出了它适用的文件范围HTTP 类型packages/core/types/src/httpAPI 路由packages/medusa/src/apiUI 组件packages/design-system/ui/src/components数据模型packages/modules 下各模块的src/models/服务接口与类型packages/core/types/srcJS SDKpackages/core/js-sdk/src抽象 Provider 与工作流工具packages/core/utils/srcWorkflow SDK 组合函数packages/core/workflows-sdk/srccore-flows 工作流与步骤packages/core/core-flows/src事件常量packages/core/utils/src/core-flows/events.ts技能的工作方式是主文档 参考文件SKILL.md 规定总约束与快速参考针对每一种文件类型再加载reference/目录下对应的 7 份参考文档。二、硬性约束写错就是事故技能文档用CRITICAL标注了六条不可违反的约束违反任何一条都会产生不正确或损坏的文档永远不要为未导出的项写文档—— 只处理export的 interface、type、function、class永远不要给测试文件加 TSDoc—— 跳过*.spec.ts、*.test.ts和__tests__/目录永远不要编造since版本号—— 只能使用提示词prompt中明确给出的版本永远不要删除或修改已有 TSDoc—— 只在缺失处补充永远不要修改逻辑—— 只增改注释块Medusa 自定义标签只能用 tsdoc.json 中定义的那些expandable、featureFlag、since、apiIgnore、schema、tags、version、keep、customNamespace、namespaceMember。这些约束背后的工程考量TSDoc 是 API 文档的源头数据文档生成工具会把它直接编译进对外发布的 API Reference。版本号错误、标签未注册、文档了内部实现都会直接污染生成产物。三、文件类型与参考文档的映射关系技能规定在写任何 TSDoc 之前先加载该文件类型对应的参考文档。映射表如下路径模式加载的参考文档packages/core/types/src/http/reference/http-types.mdpackages/medusa/src/api/admin/或/store/reference/api-routes.mdpackages/design-system/ui/src/components/reference/ui-components.mdpackages/modules/*/src/models/reference/data-models.mdpackages/core/types/src/非 http、packages/core/js-sdk/src/、packages/core/utils/src/abstract provider、packages/core/workflows-sdk/src/utils/composer/reference/service-interfaces.mdpackages/core/core-flows/src/workflows / stepsreference/workflows-steps.mdpackages/core/utils/src/core-flows/events.tsreference/events.md四、基础格式与各类型文档深度矩阵4.1 TSDoc 块的基础格式最基本的格式就是标准 JSDoc 块注释——先一句简要描述再为每个属性单独写注释/** * Brief description. */ export interface Foo { /** * The foos ID. */ id: string }4.2 按文件类型决定写到多深技能用一张矩阵规定了十种文件类型各自的文档范围与关键标签。这是全文档体系中最核心的深度控制原则并非所有文件都值得也需要完整 JSDoc文件类型文档范围Medusa 关键标签HTTP 类型每个导出的 interface/type 全部属性嵌套对象加expandableAPI 路由仅导出的 handler极简featureFlag、sinceUI 组件组件 全部 props纯描述数据模型模型 每个属性新增项加since服务接口每个方法完整文档param、returns、exampleJS SDK每个公共方法param、returns、example、tagsProvider类 每个抽象方法param、returns、exampleWorkflow SDK每个导出函数param、returns、examplecore-flows 工作流工作流导出 hookssummary、featureFlag、sincecore-flows 步骤步骤导出 输入类型featureFlag、since、example事件每个事件常量eventPayload、featureFlag、since标准 TSDoc/JSDoc 标签param、returns、example、deprecated、remarks等始终允许使用。五、Medusa 自定义标签体系以 tsdoc.json 为准技能文档中提到的自定义标签其权威定义位于 www/utils/packages/typedoc-config/tsdoc.json。该文件通过extends: [typedoc/tsdoc.json]继承标准 TSDoc 标签集再用tagDefinitions扩展 Medusa 专属标签。技能速查表中列出的十个标签及用途标签语法种类使用场景featureFlag nameblock该导出需要开启某个 feature flag 才可用expandablemodifier该属性是可通过 API 查询展开的嵌套对象since versionblock该导出在此版本新增仅使用提示词给定的版本apiIgnoremodifier从 API 文档输出中排除tags nameblockSDK 方法分类schemablock自定义 schema 文档keepmodifier文档生成时保留该属性customNamespaceblock分配到自定义文档命名空间此外从 tsdoc.json 的完整定义看仓库中还注册了更多标签供特定文档场景使用eventPayloadblock——事件常量专用描述事件负载结构eventName、workflows、workflowEvent、workflowLockblock——工作流/事件关联文档versionblock、namespaceMembermodifier、parentIgnoreblock、typeParamDefinitionblockexcludeExternal、mainSignature、docHideSignaturemodifier——控制继承属性与签名在生成文档中的呈现前两者在 UI 组件文档中实际使用见下文。这一点值得注意技能文档的速查表是写作白名单tsdoc.json 才是注册全集。写作者应遵循更严格的那份清单而读者可以依据 tsdoc.json 理解生成文档中出现的其它标签。六、十类文件的写作细则6.1 HTTP 类型expandable 与可展开实体的判断HTTP 类型文件位于packages/core/types/src/http/定义 Medusa REST API 的请求/响应形状。规则要点详见 reference/http-types.md每个导出的interface/type用一句描述每个属性用对 API 消费者有意义的简短描述对另一个可通过fields查询参数展开获取的 interface类型的属性使用expandable联合/枚举语义字段用项目符号逐一解释取值不得对 HTTP 类型使用param、returns、since——它们是数据形状不是方法。expandable的判断标准是这个标签的核心被引用类型必须是完整实体可通过?fieldsxxx展开获取标量与内嵌值对象embedded value object不加。参考文档给出的经典对比export interface AdminOrder { /** * The associated shipping methods. * expandable */ shipping_methods?: AdminOrderShippingMethod[] /** * The associated customer. * expandable */ customer?: AdminCustomer | null /** * The orders total amounts. */ summary: BaseOrderSummary // 内嵌值对象——不可独立获取不加 expandable }仓库中的实际使用情况印证了这一规范在packages/core/types/src/http/下expandable已大量出现在 order/common.ts、cart/common.ts、payment/common.ts、collection/common.ts 等核心类型文件中仅 order 一个文件就有多处使用。对于语义明确的字符串状态字段规范给出统一写法/** * The orders status: * - pending — the order is awaiting payment * - completed — the order has been fulfilled and paid * - cancelled — the order has been cancelled * - archived — the order has been archived */ status: OrderStatus而继承BaseFilterable的过滤器接口则按Filter by xxx.句式逐个说明过滤属性/** * The filters to apply when listing orders. */ export interface AdminOrderFilters extends BaseFilterableAdminOrderFilters { /** * Filter by order IDs. */ id?: string | string[] /** * Filter by order status. */ status?: OrderStatus | OrderStatus[] }参考文档还附了一个完整的 Before/After 示例BaseOrderAdjustmentLine接口从裸字段到逐属性注释可作为 HTTP 类型文档的样板接口级一句 The order adjustment lines details.属性级明确id归属The ID of the order this adjustment belongs to.、created_at/updated_at用 The date the adjustment was created/last updated. 的固定句式。6.2 API 路由极简主义与 Feature Flag 探测API 路由文件位于packages/medusa/src/api/admin/与packages/medusa/src/api/store/导出GET、POST、DELETE、PATCH等命名 handler。规则是反直觉但明确的越少越好详见 reference/api-routes.md只给导出的 handler 函数加 TSDoc只允许featureFlag和/或since不写完整方法文档若 handler 既无 feature flag 又不是新增的则不加任何 TSDoc不加param、returns、example和描述。Feature flag 的探测方法查看 handler 函数体内是否调用FeatureFlag.isFeatureEnabled(...)featureFlag的值取 flag 的 key 字符串如IndexEngineFeatureFlag.key对应index_engine同时检查路由是否基于 flag 在路由注册配置或中间件中条件注册。条件添加内容handler 使用FeatureFlag.isFeatureEnabled(XFlag.key)featureFlag flag_keyhandler 是本次 diff 中的新增since versionhandler 是既有的且无 feature flag什么都不加典型输出/** * since 2.14.0 * featureFlag view_configurations */ export const GET async ( req: AuthenticatedMedusaRequest, res: MedusaResponseHttpTypes.AdminViewConfigurationListResponse ) { /* ... */ }路由文件中偶尔导出的 validator 或 helper 不属于模块公共面无需 TSDoc。6.3 UI 组件内联 prop 注释、Radix 与 excludeExternal/keepUI 组件位于packages/design-system/ui/src/components/。规则详见 reference/ui-components.md组件用一句描述props 以内联注释写在解构参数列表中而不是给Propsinterface 单独写注释除非该 interface 本身被导出基于 Radix UI 的组件在组件文档中指明所基于的 Radix 原语纯透传 Radix props、无自定义属性的薄封装组件只写组件级描述即可不给组件加param/returns/since除非组件是新增且版本已给定。内联 prop 文档的正确/错误对照// 正确——内联 prop 文档 const Button React.forwardRefHTMLButtonElement, ButtonProps( ( { /** * The buttons visual style. */ variant primary, /** * The buttons size. */ size base, /** * Whether to render as the child element instead of a button. */ asChild false, /** * Whether to show a loading spinner. */ isLoading false, disabled, className, children, ...props }, ref ) { /* ... */ } )对于Props继承自原生 HTML 元素类型如React.ComponentPropsWithoutRefdiv的组件继承来的className、children、style、id等大量属性不该出现在生成文档中。规范给出两级控制excludeExternal加在组件 TSDoc 块上抑制所有继承的外部属性keep若某个被继承的属性在本组件中有非平凡行为如disabled触发自定义视觉状态、onInvalid接入了内部校验在该 prop 的内联注释中加keep可附defaultValue使其保留而className、style、id这类通用透传属性绝不keep。若Props只含自定义属性没有 extends 外部类型则可省略excludeExternal。6.4 数据模型DML 实体与 since 的diff 纪律数据模型位于packages/modules/*/src/models/使用 DMLData Model Language的model.define(...)定义实体。规则详见 reference/data-models.md模型级const用一句实体描述完整句或简短名词短语均可每个属性一句简短描述since version只加在本次 diff 中新增仅出现在新增行的属性或模型上字符串格式不直观的属性locale 码、货币码、时区用example说明主键id不写文档约定俗成关系属性统一句式The associated [related model]./** * A locale supported by a store. * since 2.14.0 */ const StoreLocale model.define(StoreLocale, { /** * The BCP 47 language tag code of the locale. * example en-US */ locale_code: model.text().searchable(), /** * The associated store. */ store: model.belongsTo(() Store, { mappedBy: supported_locales }).nullable(), })关系属性的三种标准句式/** The associated store. */ store: model.belongsTo(() Store, { mappedBy: supported_locales }), /** The products variants. */ variants: model.hasMany(() ProductVariant, { mappedBy: product }), /** The variants images. */ images: model.manyToMany(() ProductImage, { mappedBy: variants }),反例清单同样明确不要给主键id: model.id({ prefix: pv }).primaryKey()写文档不要给本次提交之前就存在的属性补since。6.5 服务接口、JS SDK、Provider、Workflow SDK同一套完整 JSDoc模式这四类文件共用同一参考文档reference/service-interfaces.md都采用完整 JSDoc模式接口/类本身一句描述每个公共方法写描述 paramreturnsexampleJS SDK 方法额外加tags category与 SDK 模块分类对应如tags products方法描述以 This method [verb phrase]. 开头固定格式param {Type} name - Description.、returns {PromiseType} Description of resolved value.。完整的 retrieve 方法样板/** * This method retrieves a product by its ID. * * param {string} productId - The ID of the product to retrieve. * param {FindConfigProductDTO} config - The configurations determining how the product is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a product. * param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * returns {PromiseProductDTO} The retrieved product. * * example * const product await productModuleService.retrieveProduct(prod_123) */ retrieveProduct( productId: string, config?: FindConfigProductDTO, sharedContext?: Context ): PromiseProductDTO几个值得注意的细节sharedContext参数有固定标准描述A context used to share resources, such as transaction manager, between the application and the module.——它几乎出现在所有模块服务方法上统一措辞可避免文档漂移列表方法的example应展示多个真实场景按 ID 列表、带relations查询多个场景用标签分段抽象 Provider 方法的example以继承该抽象类的实现类形式给出如class MyPaymentProvider extends AbstractPaymentProvider { async initiatePayment(input) { ... } }Workflow SDK 组合函数如createStep也要为compensateFn这类可选参数用[compensateFn]方括号标注。6.6 core-flows 工作流与步骤summary、hooks 与 step 输入类型工作流与步骤文件位于packages/core/core-flows/src/分别用createWorkflow(...)与createStep(...)创建详见 reference/workflows-steps.md。工作流文档要求一段描述说明工作流做什么、何时被使用并链接到执行它的 API 路由如适用example展示如何调用.run()summary一行摘要每个hooks.*钩子一条property hooks.xxx条目新增时加since受 flag 控制时加featureFlag。export const myWorkflowId my-workflow /** * This workflow [does X]. Its executed by the [Some API Route]. * * You can use this workflow within your own customizations or custom workflows, * allowing you to wrap custom logic around [the operation]. * * example * const { result } await myWorkflow(container) * .run({ input: { id: foo_123 } }) * * summary * * [One-line summary of what the workflow does.] * * property hooks.myHook - This hook is called [when/before/after X]. You can * use it to [describe what customization is possible]. */ export const myWorkflow createWorkflow(myWorkflowId, (input) { /* ... */ })钩子文档的标准句式This hook is called before/after X. You can use it to ....逐钩子一条* property hooks.validate - This hook is called before all operations. You can * use it to validate the input or perform any custom validation logic. * * property hooks.setPricingContext - This hook is called after the cart is * retrieved. You can use it to pass custom pricing context to the workflow.步骤文档要求描述步骤做什么含抛错/返回条件、example展示调用方式、since/featureFlag如适用并为步骤的输入类型 interface 逐属性写描述且用{link stepName}交叉引用关联步骤/** * The input for the {link validateCartStep}. */ export interface ValidateCartStepInput { /** * The cart to validate. */ cart: CartWorkflowDTO | CartDTO }对仅受 flag/版本控制的简单步骤允许只写标签型文档/** * since 2.10.3 * featureFlag view_configurations */ export const createViewConfigurationStep createStep(/* ... */)明确不写文档的对象*Id字符串常量如export const addToCartWorkflowId add-to-cart、模块内部未导出的 helper、以及createStep第三个参数补偿函数——属于内部实现细节。6.7 事件常量eventPayload 负载结构规范事件常量位于 packages/core/utils/src/core-flows/events.ts按命名空间对象分组导出如CartWorkflowEvents、OrderWorkflowEvents。规则详见 reference/events.md每个事件常量写何时被发出的描述Emitted when [resource] is [action].必须包含eventPayload展示负载结构TypeScript 代码块每个属性带内联注释事件在本次 diff 中新增时加since且since置于eventPayload之前使版本信息先出现受 flag 控制时加featureFlag命名空间对象本身一般不写文档除非它确实缺描述且同文件其它命名空间已统一使用categorycustomNamespace模式。eventPayload的一个精细规则字符串 ID 不标注类型非字符串值必须用(type)标注/** * Emitted when an orders fulfillment is created. * * eventPayload * ts * { * order_id, // The ID of the order * fulfillment_id, // The ID of the fulfillment * no_notification, // (boolean) Whether to notify the customer * } * */ FULFILLMENT_CREATED: order.fulfillment_created,完整的 Before/After 示例OrderWorkflowEvents三个事件从裸常量到带eventPayload的注释是事件文档的基准样板。仓库实证当前 events.ts 中已存在 83 处eventPayload注释说明该规范已在事件常量文档化中被系统性执行而featureFlag也已在packages/medusa/src/api/admin/下多条路由如admin/index/details/route.ts、admin/locales/route.ts等中落地。七、常见错误清单Common Mistakes技能文档最后给出了一份自查清单覆盖五类高频错误为未导出或private项写了文档提示词未提供版本号时使用了since属性描述超过 2 句话给非方法导出interface、type加了param/returns文档化了id字段却没有指明它属于哪个资源。这份清单与前述各参考文档的What NOT to Document章节互为呼应可作为提交前的最后一道检查。八、体系总结一套按类型分级的文档工程方法把 SKILL.md 与 7 份参考文档合起来看Medusa 的 TSDoc 体系有三个可迁移到其它大型 TypeScript 项目的设计思想文档深度与公共面成正比API 路由 handler 只标 flag/版本HTTP 类型逐属性注释服务接口才需要完整 JSDoc example。文档预算跟着消费者是谁走而不是对所有代码一刀切自定义标签 文档生成器的可编程开关expandable驱动前端字段展开、featureFlag驱动文档按 flag 分组、apiIgnore/excludeExternal/keep控制呈现粒度、eventPayload把事件负载结构嵌入文档——标签不是装饰而是文档构建流水线的一等输入其注册必须集中在 tsdoc.json 单点管理事实纪律since只认提示词给定的版本、只给 diff 新增项打标签、不碰测试文件、不改逻辑——保证文档注释永远可以追溯到一个真实的变更来源。对维护者而言这套规范的最佳使用路径是确认目标文件落在第三节的映射表中哪一行加载对应参考文档按第四节的深度矩阵确定文档范围用第五节的标签表约束自定义标签最后过一遍第七节的常见错误清单——即可获得与仓库现有 83 处eventPayload、遍布 http 类型的expandable同一水准的 TSDoc 输出。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考