TypeSpec 标准库指南：使用 @encodedName 与 resolveEncodedName 控制不同 MIME 类型的序列化字段名

TypeSpec 标准库指南使用 encodedName 与 resolveEncodedName 控制不同 MIME 类型的序列化字段名【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec在 TypeSpec 中定义一个模型时属性名通常即代表线上传输时的名字但在真实项目中JSON、XML、YAML 等不同序列化格式、或不同编程语言生态往往需要不同的字段名。TypeSpec 标准库为此提供了encodedName装饰器与配套的resolveEncodedNameAPI让你无需复制模型即可为同一实体声明多套传输名。读完本文你将掌握encodedName的完整用法、其底层实现与编译期校验规则并能直接在自定义 emitter 或库中通过resolveEncodedName精确消费这些别名。适用场景为什么需要编码名TypeSpec 语言中的属性名与线上传输的名字并不总是相同。典型场景包括某个属性在 TypeSpec 中命名为expireAt但序列化为 JSON 时希望是exp同一模型同时暴露 JSON 与 XML 两种格式JSON 用exp、XML 用ExpireAt对接既有 API 协议时必须沿用对方已固定的字段名而 TypeSpec 内部希望保留更清晰的可读命名。encodedName就是为这类按 MIME 类型媒体类型重命名的需求而生的标准库装饰器。它与clientName面向具体编程语言客户端命名的装饰器职责不同专注解决按序列化格式wire format命名的问题。装饰器签名与参数说明encodedName的声明位于 packages/compiler/lib/std/decorators.tsp签名如下extern dec encodedName(target: unknown, mimeType: valueof string, name: valueof string);它接收两个必填参数参数类型说明mimeTypevalueof string该别名生效的 MIME 类型。应为常见 MIME 类型如application/json、application/xml且不能携带任何后缀suffix例如json这种带后缀的写法是不允许的见下文编译期校验encodedNamevalueof string序列化到指定 MIME 类型时使用的名字。同样注意此参数类型为valueof string意味着传入的是字符串字面量值而非类型引用target类型为unknown表示它可应用于多种实体。从实现来看见下文getScope逻辑目前主要支持三类成员模型属性ModelProperty、枚举成员EnumMember、联合变体UnionVariant。也就是说除了给属性改名你同样可以为枚举成员和联合变体声明按 MIME 类型区分的编码名。基础用法为一个属性声明 JSON 编码名最简单的场景仅针对一种 MIME 类型声明别名model Foo { // 序列化为 JSON 时expireAt 属性将被命名为 exp encodedName(json, exp) expireAt: string; }注意这里的json是application/json的简写形式TypeSpec 会将其解析为标准的type/subtype结构后匹配。官方标准库文档与源码中更多使用完整形式application/json。完整示例同一模型的多格式编码名以下示例来自标准库文档展示了如何为同一属性在不同 MIME 类型下声明不同的名字model CertificateAttributes { encodedName(application/json, nbf) notBefore: int32; encodedName(application/json, exp) encodedName(application/xml, ExpireAt) expires: int32; created: int32; updated: int32; }其序列化结果对比格式行为输出JSON序列化为application/json时优先使用该 MIME 类型下的encodedName否则回退到属性名{nbf: 1430344421, exp: 2208988799, created: 1493938289, updated: 1493938291}XML序列化为application/xml时优先使用该 MIME 类型下的encodedName否则回退到属性名CertificateAttributesnotBefore1430344421/notBeforeExpireAt2208988799/ExpireAtcreated1493938289/createdupdated1493938291/updated/CertificateAttributesYAML未声明任何 YAML 相关编码名直接使用 TypeSpec 属性名notBefore: 1430344421、expires: 2208988799、created: 1493938289、updated: 1493938291这个例子清晰地体现了三层设计意图notBefore只为 JSON 声明了nbf所以 JSON 输出nbfXML/YAML 保持原名expires为 JSON 与 XML 各声明了不同的名字exp与ExpireAt两种格式各自独立created、updated未声明任何编码名所有格式都使用属性名。编译期校验非法 MIME 类型、后缀与命名冲突encodedName不是声明即生效的弱类型装饰器编译器会在编译期对声明做严格校验。核心实现位于 packages/compiler/src/lib/encoded-names.tsexport function $encodedName( context: DecoratorContext, target: Type, mimeType: string, name: string, ) { // 为 target 维护一个 MapmimeType, name 的状态 const mimeTypeObj parseMimeType(mimeType); if (mimeTypeObj undefined) { reportDiagnostic(context.program, { code: invalid-mime-type, ... }); } else if (mimeTypeObj.suffix) { reportDiagnostic(context.program, { code: no-mime-type-suffix, ... }); } existing.set(mimeType, name); }对应的三条校验规则均有测试覆盖见 packages/compiler/test/decorators/decorators.test.ts诊断码触发条件示例invalid-mime-typeMIME 类型格式非法无法解析为type/subtypeencodedName(foo/bar/baz, exp)no-mime-type-suffixMIME 类型携带xxx后缀encodedName(application/merge-patchjson, exp)encoded-name-conflict编码名与既有成员名冲突或同一 MIME 类型下两个成员声明了相同的编码名见下方示例命名冲突检测由validateEncodedNamesConflicts完成packages/compiler/src/lib/encoded-names.ts其规则为若某成员的编码名与同作用域内已有的成员名相同例如属性exp已存在又为expireAt声明encodedName(application/json, exp)报冲突若两个成员在同一 MIME 类型下声明了相同的编码名两个属性都声明encodedName(application/json, exp)报冲突若不同 MIME 类型下使用相同的编码名一个用application/json的exp另一个用application/xml的exp不构成冲突允许通过。model Cert { encodedName(application/json, exp) expireAt: utcDateTime; exp: string; // 错误encoded-name-conflict编码名 exp 与已有成员名冲突 }这套校验机制保证了编码后的序列化结果不会出现歧义字段从源头规避了 JSON/XML 反序列化时的命名碰撞。在库与 emitter 中消费编码名resolveEncodedName对于编写自定义 emitter 或库的开发者编译器导出了resolveEncodedName函数来读取编码名。其函数签名与完整 JSDoc 示例见 packages/compiler/src/lib/encoded-names.tsexport function resolveEncodedName( program: Program, target: Type { name: string }, mimeType: string, ): string { return getEncodedName(program, target, mimeType) ?? target.name; }用法import { resolveEncodedName } from typespec/compiler; // 解析给定属性在 application/json 下的编码名。 // 若该属性没有为此 MIME 类型声明编码名则返回属性名本身。 const encodedName resolveEncodedName(property, application/json); // 也可以传入完整的 HTTP MIME 类型 // resolveEncodedName 会自动解析为不带后缀的基础 MIME 类型。 const encodedName resolveEncodedName(property, application/merge-patchjson);后缀自动回退的底层逻辑第二个用法背后有一个关键设计带后缀的 MIME 类型会自动回退到基础 MIME 类型。其内部实现位于getEncodedNamepackages/compiler/src/lib/encoded-names.tsfunction getEncodedName(program: Program, target: Type, mimeType: string): string | undefined { const mimeTypeObj parseMimeType(mimeType); if (mimeTypeObj undefined) return undefined; const resolvedMimeType mimeTypeObj?.suffix ? ${mimeTypeObj.type}/${mimeTypeObj.suffix} : mimeType; return getEncodedNamesMap(program, target)?.get(resolvedMimeType); }也就是说查询application/merge-patchjson时会自动落到application/json的编码名上与文档中resolveEncodedName(property, application/merge-patchjson)返回exp的示例完全一致。注意这与装饰器声明侧的校验形成互补声明时禁止带后缀查询时却允许带后缀并自动回退从而让application/merge-patchjson、application/problemjson等派生媒体类型都能复用 JSON 的编码名。测试用例 packages/compiler/test/decorators/decorators.test.ts 对此行为有明确验证strictEqual(resolveEncodedName(program, expireAt, application/json), exp); strictEqual(resolveEncodedName(program, expireAt, application/merge-patchjson), exp); // 未为 application/xml 声明编码名时返回原始属性名 strictEqual(resolveEncodedName(program, expireAt, application/xml), expireAt);状态存储与按成员类型的作用域从源码结构看encodedName的状态通过useStateMapType, Mapstring, string按目标类型存储packages/compiler/src/lib/encoded-names.ts每个 target 维护一张基础 MIME 类型 → 编码名的映射表。validateEncodedNamesConflicts中的getScope同文件 L154-L165按成员种类解析其所属作用域模型属性归属其model的属性集合枚举成员归属其enum的成员集合联合变体归属其union的变体集合冲突检测正是在这些作用域内展开的。在真实 emitter 中的应用resolveEncodedName并非孤立 API从源码结构看它已被多个官方 emitter 与库实际消费可作为你编写 emitter 时的参考范例packages/openapi3/src/schema-emitter.ts 与 packages/openapi3/src/xml-module.tsOpenAPI3 emitter 在生成 schema 时解析 JSON/XML 编码名packages/http-server-js/src/common/serialization/json.tsHTTP Server JS 在 JSON 序列化路径中消费编码名packages/http-server-csharp/src/utils/attributes.tsx 与 packages/emitter-framework/src/csharp/components/property/property.tsxC# 相关 emitter 在生成属性代码时使用packages/xml/test/decorators.test.tsXML 库的测试中验证了编码名行为。最佳实践小结声明用基础 MIME 类型查询可带后缀声明encodedName时使用application/json这类不带suffix的形式在 emitter 中查询时则可以放心传入完整的application/merge-patchjson编译器会自动回退。为不同格式分别声明需要多格式输出的 API优先为每种格式显式声明编码名避免依赖回退到属性名的隐式行为导致格式间命名不一致。善用编译期冲突检测encoded-name-conflict诊断会在编译阶段暴露编码名冲突编写模型时应保持同一 MIME 类型内编码名唯一、且不与既有成员名重复。在 emitter 中始终使用resolveEncodedName而非自行解析该 API 统一处理了 MIME 解析、后缀回退与默认名回退是官方推荐的唯一消费入口避免在多个 emitter 中重复实现不一致的解析逻辑。从模型定义到 emitter 消费encodedName与resolveEncodedName构成了 TypeSpec 中按序列化格式命名的完整闭环前者负责声明后者负责查询而编译器在校验、存储与后缀解析三个层面为这一闭环提供保障。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考