TypeSpec Rest 资源操作模板接口全解typespec/rest 中 22 个 Resource Interface 的完整参考指南【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespectypespec/rest的TypeSpec.Rest.Resource命名空间提供了一组资源操作模板接口Resource Operation Template Interfaces把 REST 资源最常见的 CRUD 生命周期操作抽象为可复用的泛型接口。本指南以官方参考文档 interfaces.md 为骨架逐一拆解全部 22 个接口的模板参数、操作签名与适用场景并结合 resource.tsp 的源码实现与 resource.test.ts 的测试用例说明这些模板如何被解析为真实的 HTTP 路由。读完本文你将能熟练选用合适的模板接口标准资源、单例资源、扩展资源理解其背后的键参数复制与路由生成机制并直接在自己的 TypeSpec 规范中落地使用。一、资源操作模板解决了什么问题在 REST API 设计中资源的读写删建等操作高度模式化几乎每个资源都需要get读取单个实例、update更新、delete删除、create创建、list分页列出这五个标准操作。如果每个资源都手工书写这些op规范会迅速变得冗长且难以保持一致。typespec/rest通过接口模板interface 配合模板参数解决这一问题你只需要定义一个资源模型如Thing再写一句interface Things extends ResourceOperationsThing, Error {}编译器就会自动生成完整的标准操作集合包括正确的路由、HTTP 动词、路径参数与响应类型。这些模板接口定义在TypeSpec.Rest.Resource命名空间中按适用对象可分为三类类别接口标准资源模板ResourceRead、ResourceUpdate、ResourceDelete、ResourceCreate、ResourceList、ResourceCreateOrReplace、ResourceCreateOrUpdate、ResourceInstanceOperations、ResourceCollectionOperations、ResourceOperations单例资源模板SingletonResourceRead、SingletonResourceUpdate、SingletonResourceOperations扩展资源模板ExtensionResourceRead、ExtensionResourceUpdate、ExtensionResourceDelete、ExtensionResourceCreate、ExtensionResourceList、ExtensionResourceCreateOrUpdate、ExtensionResourceInstanceOperations、ExtensionResourceCollectionOperations、ExtensionResourceOperations接口的权威定义位于 packages/rest/lib/resource.tspTypeSpec 编译器会在编译时对模板进行实例化并生成路由。二、理解模板之前必须掌握的基础构件所有资源操作模板都建立在一组底层模型与装饰器之上理解它们才能真正读懂接口签名。2.1 装饰器key、segment、resource、parentResource资源模板要求资源模型上至少有一个键属性key property即用key标记的属性它会被复制为操作中的路径参数。resource(collectionName)将模型标记为资源类型并自动在其key属性上应用segmentsegment则为该路径参数定义前置路径段。parentResource(parent)用于声明父子资源关系使子资源的操作自动带上父资源的键参数。关于这些装饰器的完整签名与参数说明可参考 README.md 或 decorators.md。2.2 键参数收集模型KeysOf与ParentKeysOf模板签名中大量出现的...ResourceParametersResource与...ResourceCollectionParametersResource是路由参数展开的入口它们最终依赖两个动态收集模型// packages/rest/lib/resource.tsp 中的定义 copyResourceKeyParameters friendlyName({name}Key, Resource) model KeysOfResource {} copyResourceKeyParameters(parent) friendlyName({name}ParentKey, Resource) model ParentKeysOfResource {}KeysOfResource动态收集Resource模型含其父链上的全部key属性ParentKeysOfResource只收集父资源的键属性当copyResourceKeyParameters的过滤参数为parent时用于集合级操作定位父级作用域。在此基础上model ResourceParametersResource extends {} { ...KeysOfResource; } model ResourceCollectionParametersResource extends {} { ...ParentKeysOfResource; }ResourceParameters用于实例级操作如get、update、delete展开后包含资源自身及其所有父级的键ResourceCollectionParameters用于集合级操作如create、list只包含父级键。这一机制的底层实现在 src/resource.ts 的cloneKeyProperties与$copyResourceKeyParameters函数中——源码会递归遍历父资源链将每个键属性克隆到目标模型强制optional: false防止可选的键属性变成可选路径参数并自动附加path装饰器。2.3 请求与响应模型模板签名中还引用了若干辅助模型它们同样定义在TypeSpec.Rest.Resource命名空间ResourceCreateModelResource创建操作请求体等价于DefaultKeyVisibilityResource, Lifecycle.Read并施加Lifecycle.Create可见性即创建时通常不可提供服务端生成的键ResourceCreateOrUpdateModelResource创建/更新操作请求体是Resource的可更新属性集合OptionalPropertiesUpdateableProperties...属性均可选以支持部分更新ResourceCreatedResponseResource创建成功响应HTTP 状态码固定为201bodyRoot body承载被创建的资源ResourceDeletedResponse删除成功响应HTTP 状态码固定为200CollectionWithNextLinkResource分页响应结构包含value: Resource[]当前页数据pageItems与可选的nextLink?: ResourceLocationResource下一页链接nextLinkResourceError默认错误响应模型含code: int32与message: string。上述模型的属性明细可在>interface TypeSpec.Rest.Resource.ResourceReadResource, Error op get(...ResourceParametersResource): Resource | Error;签名中的...ResourceParametersResource展开后即为path segment(things) thingId: string之类的参数。在 resource.test.ts 中interface Things extends ResourceReadThing, Error {}被解析为GET /things/{thingId}。ResourceUpdateResource, Error—— 更新单个资源op update(...ResourceParametersResource, properties: ResourceCreateOrUpdateModelResource): Resource | Error;更新操作使用patch并开启implicitOptionality为兼容旧行为因此生成的路由动词为patch。源码在 resource.tsp 中还标注了updatesResource(Resource)装饰器。ResourceDeleteResource, Error—— 删除单个资源op delete(...ResourceParametersResource): ResourceDeletedResponse | Error;删除成功后返回ResourceDeletedResponse200 状态码源码实现见 resource.tsp。ResourceInstanceOperationsResource, Error—— 实例级三件套的聚合模板interface ResourceInstanceOperationsResource extends {}, Error extends ResourceReadResource, Error, ResourceUpdateResource, Error, ResourceDeleteResource, Error {}它通过 interface 继承组合了get、update、delete三个操作定义见 resource.tsp。3.2 集合级操作模板集合级操作作用于资源集合路由中只包含父级键参数通常没有键参数。ResourceCreateResource, Error—— 创建资源op create(...ResourceCollectionParametersResource, resource: ResourceCreateModelResource): Resource | ResourceCreatedResponseResource | Error;创建操作使用...ResourceCollectionParameters只带父键请求体为ResourceCreateModel成功时返回Resource或ResourceCreatedResponse201 创建后的资源体。测试验证其路由为POST /things。ResourceListResource, Error—— 列出资源集合op list(...ResourceCollectionParametersResource): CollectionWithNextLinkResource | Error;返回分页结构CollectionWithNextLinkResource路由为GET /things。ResourceCollectionOperationsResource, Error—— 集合级两件套的聚合模板interface ResourceCollectionOperationsResource extends {}, Error extends ResourceCreateResource, Error, ResourceListResource, Error {}组合了create与list见 resource.tsp。3.3 完整生命周期模板ResourceOperationsinterface ResourceOperationsResource extends {}, Error extends ResourceInstanceOperationsResource, Error, ResourceCollectionOperationsResource, Error {}ResourceOperations聚合了全部五个标准操作get、update、delete、create、list。这是日常使用频率最高的模板——一行interface Things extends ResourceOperationsThing, Error {}即可获得完整的 REST 资源端点。测试 resource.test.ts 验证其生成的路由为GET /things/{thingId} PATCH /things/{thingId} DELETE /things/{thingId} POST /things GET /things3.4 两种特殊写操作模板ResourceCreateOrReplaceResource, Error—— 全量创建或替换op createOrReplace(...ResourceParametersResource, resource: ResourceCreateModelResource): Resource | ResourceCreatedResponseResource | Error;与create不同createOrReplace使用ResourceParameters包含资源自身的键并生成PUT动词语义为按指定键全量替换路由为PUT /things/{thingId}见测试 resource.test.ts。ResourceCreateOrUpdateResource, Error—— 创建或部分更新upsert 语义op createOrUpdate(...ResourceParametersResource, resource: ResourceCreateOrUpdateModelResource): Resource | ResourceCreatedResponseResource | Error;同样携带资源自身键参数请求体为ResourceCreateOrUpdateModel属性可选使用patch生成PATCH动词。源码见 resource.tsp。四、单例资源模板SingletonResource*单例资源singleton resource表示在父资源作用域下唯一存在的一个实例例如GET /things/{thingId}/settings中的settings。它的特殊之处在于路径中只有父资源的键而没有单例自身的键。单例模板使用三个类型参数Singleton单例资源模型、Resource父资源模型、Error。SingletonResourceReadSingleton, Resource, Errorop get(...ResourceParametersResource): Singleton | Error;操作只展开父资源的键参数并通过segmentOf(Singleton)使用单例模型上的segment生成其 URL 段。测试 resource.test.ts 中segment(singleton) model Singleton与SingletonResourceOperationsSingleton, Thing, Error配合生成了GET /things/{thingId}/singleton。SingletonResourceUpdateSingleton, Resource, Errorop update(...ResourceParametersResource, properties: ResourceCreateOrUpdateModelSingleton): Singleton | Error;请求体为基于Singleton模型的可选属性集合生成PATCH /things/{thingId}/singleton。SingletonResourceOperationsSingleton, Resource, Error—— 聚合以上两者interface SingletonResourceOperationsSingleton extends {}, Resource extends {}, Error extends SingletonResourceReadSingleton, Resource, Error, SingletonResourceUpdateSingleton, Resource, Error {}单例资源只有读取与更新两个标准操作因为创建/删除/列表在语义上对单例不适用。五、扩展资源模板ExtensionResource*扩展资源extension resource是一种附着在其他资源父资源或子资源之上的资源类型用于在不修改原资源模型的前提下为它扩展额外数据与操作。扩展资源模板同样使用三个类型参数Extension扩展资源模型、Resource被扩展的资源模型、Error。关键差异在于签名中同时展开两组键参数例如ExtensionResourceReadop get(...ResourceParametersResource, ...ResourceParametersExtension): Extension | Error;这表示路由同时包含被扩展资源的键与扩展资源自身的键。以测试 resource.test.ts 中的ExtensionResourceOperationsExthing, Thing, Error为例生成的路由为GET /things/{thingId}/extension/{exthingId} PATCH /things/{thingId}/extension/{exthingId} DELETE /things/{thingId}/extension/{exthingId} POST /things/{thingId}/extension GET /things/{thingId}/extension而当扩展挂在子资源Subthing上时路由变为/things/{thingId}/subthings/{subthingId}/extension/{exthingId}可见父键会被完整继承。全部 9 个扩展资源模板及其操作如下均定义于 resource.tsp接口操作签名要点ExtensionResourceReadget...ResourceParametersResource, ...ResourceParametersExtensionExtensionResourceUpdateupdate两组键参数 properties: ResourceCreateOrUpdateModelExtensionExtensionResourceDeletedelete两组键参数返回ResourceDeletedResponseExtensionResourceCreatecreate...ResourceParametersResourceresource: ResourceCreateModelExtensionExtensionResourceListlist...ResourceParametersResource...ResourceCollectionParametersExtension返回CollectionWithNextLinkExtensionExtensionResourceCreateOrUpdatecreateOrUpdate两组键参数 ResourceCreateOrUpdateModelExtensionExtensionResourceInstanceOperationsget/update/delete聚合 Read、Update、DeleteExtensionResourceCollectionOperationscreate/list聚合 Create、ListExtensionResourceOperationsget/update/delete/create/list聚合以上两个六、模板参数的约定与编译期校验所有模板的类型参数遵循统一约定参数含义要求Resource标准资源模型必须含key属性否则诊断resource-missing-keyExtension扩展资源模型必须含key属性Singleton单例资源模型无需键但需segment定位Error错误响应模型必须用error装饰否则诊断resource-missing-error在 resource.tsp 源码中多数模板接口上都标注了Private.validateHasKey(Resource)与Private.validateIsError(Error)对应 resource.test.ts 中验证的两条诊断typespec/rest/resource-missing-keyType Dog is used as a resource and therefore must have a key. Use key to designate a property as the key.typespec/rest/resource-missing-errorType Error is used as an error and therefore must have the error decorator applied.此外还有针对资源建模本身的校验资源模型上存在多个key时报告duplicate-key子资源键名与父资源键名冲突时报告duplicate-parent-keyparentResource形成循环时报告circular-parent-resource源码实现见 src/resource.ts 中的checkCircularParentResource测试见 resource.test.ts。七、实战如何选用并组合这些模板7.1 标准资源一行接口获得完整 CRUDimport typespec/rest; import typespec/http; using TypeSpec.Rest; using TypeSpec.Rest.Resource; resource(things) model Thing { key segment(things) thingId: string; name: string; description?: string; } error model Error { code: int32; message: string; } interface Things extends ResourceOperationsThing, Error {}编译后即得到GET/PATCH/DELETE /things/{thingId}与POST/GET /things五个端点。7.2 分层资源借助parentResource组合嵌套路由parentResource(Thing) resource(subthings) model Subthing { key segment(subthings) subthingId: string; data: string; } interface Subthings extends ResourceOperationsSubthing, Error {}依据 resource.test.ts这会生成/things/{thingId}/subthings/{subthingId}get/patch/delete与/things/{thingId}/subthingspost/get父级键thingId自动出现在所有子操作的路由中。7.3 单例资源segment(settings) model ThingSettings { theme: string; } interface ThingSettingsSingleton extends SingletonResourceOperationsThingSettings, Thing, Error {}生成GET /things/{thingId}/settings与PATCH /things/{thingId}/settings。7.4 扩展资源resource(tags) model Tag { key segment(tags) tagId: string; label: string; } interface ThingTags extends ExtensionResourceOperationsTag, Thing, Error {}生成GET/PATCH/DELETE /things/{thingId}/tags/{tagId}与POST/GET /things/{thingId}/tags为Thing资源附加标签扩展能力。7.5 组合使用接口模板可以同时继承多个模板例如测试中的interface Things extends ResourceOperationsThing, Error, ResourceCreateOrReplaceThing, Error {}它会在五个标准操作之外再增加一个PUT /things/{thingId}的替换操作见 resource.test.ts。八、进一步阅读接口参考原文本文档数据模型参考装饰器参考typespec/rest 总览资源路由与自动路由生成源码实现 与 装饰器运行时实现路由生成与诊断的测试用例包级 README 与装饰器清单【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考