TypeSpec 声明表达式在表达式位置使用 model、enum、union 与 scalar 的完整指南【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespecTypeSpec 编译器typespec/compiler在近期版本中引入了实验性的“声明表达式”declaration expressions功能它允许把model、enum、union、scalar四类声明直接写在表达式位置如属性类型、别名、装饰器参数而不必先声明成顶层或成员级符号。本文基于仓库中的变更日志条目 decl-expr-declaration-expressions-2026-4-18-0-0-0.md 展开并结合 checker 源码、特性开关实现 与 测试用例完整讲解该功能的启用方式、语法规则、使用位置边界以及底层实现机制帮助你在项目中正确启用并驾驭这一实验特性。声明表达式是什么传统的 TypeSpec 声明必须占据“语句位置”——即 namespace、接口或 model 的成员槽位拥有独立的符号并被注册到所在命名空间中。声明表达式则打破了这一限制它把声明语法本身当作一个“值”类型构造器来使用出现在任何期望表达式的上下文里。官方变更条目给出的完整示例如下涵盖别名、属性类型、装饰器参数与带extends的 scalar 表达式alias Foo enum { a, b, }; model Bar { status: enum { active, inactive }; unit: scalar extends string; inner: model Inner { x: string }; } Versioning.versioned(enum Versions { v1, v2 }) namespace MyService;其中涉及三个关键行为约定均来自变更日志原文标记expression: true凡是在表达式位置使用的声明其对应类型都会被标记expression: true供上层如 typekit、emitter区分它和语句级声明不注册到外围命名空间声明表达式不会在外围 namespace 中注册符号即enum { a, b }不会在命名空间里产生一个可查找的类型名可命名也可匿名它既可以带名字如model Inner { x: string }也可以匿名此时类型没有名字。命名表达式会保留名字用于类型显示但不能通过名字再次引用它——这一点由测试用例 “cannot be referenced by its name” 明确验证见 declaration-expressions.test.ts。语句级声明与表达式级的标记差异expression标记是双向的不仅表达式位置的声明为expression: true语句位置的model/enum/union/scalar声明也会被显式标记expression: false测试组 “statement declarations are not expressions”。可以推断这一对称标记是为了让依赖类型元数据的下游工具emitter、类型图可视化等无需再做“是否语句级声明”的猜测直接读取布尔字段即可。如何启用tspconfig.yaml 的 features 开关这是一个实验性特性必须显式开启。变更日志明确要求在tspconfig.yaml的features列表中加入declaration-expressions若未开启而在代码中使用了声明表达式编译器会报告declaration-expression-disabled错误注意是 error 级别不是警告。启用配置示例# tspconfig.yaml features: - declaration-expressions特性开关的源码实现特性定义位于 features.tsdeclaration-expressions: { description: Allows use of declaration expressions (named or anonymous model, scalar, enum and union declarations in expression position) in project code., },同文件中的isCompilerFeatureEnabled函数features.ts揭示了开关的解析规则值得注意项目代码读取根项目tspconfig.yaml的features列表库代码按源文件所属包解析——库可以通过自己的tspconfig.yaml为自身代码独立启用特性与消费方项目的配置相互独立编译器标准库与合成代码从不被特性门控never gated。这意味着特性检查是“按代码归属地”解析的而不是全局一刀切。诊断错误的触发路径错误消息定义在 messages.tsdeclaration-expression-disabled: { severity: error, messages: { default: Declaration expressions require the declaration-expressions feature to be enabled. Add declaration-expressions to the features list in your tspconfig.yaml., }, },触发逻辑在 checker 的 reportDeclarationExpressionFeature 中它先判断节点是否属于四种“表达式形态”之一ModelDeclarationExpression、ScalarDeclarationExpression、EnumDeclarationExpression、UnionDeclarationExpression再调用isCompilerFeatureEnabled(program, declaration-expressions, node)按上文规则解析特性集合未启用即上报诊断。这也说明扫描器/解析器层面已为声明表达式定义了独立的 AST 节点类型SyntaxKind.*DeclarationExpression与语句位置的*Statement节点分开建模。可用的位置与语法能力变更日志说明声明表达式“可以在任何期望表达式的地方使用”并列举了具体场景别名alias、model 属性、装饰器参数、模板参数位置作为模板实参、函数/调用参数、元组tuple。仓库测试 declaration-expressions.test.ts 对这些位置做了系统性验证从测试用例标题可以确认以下已覆盖的用法使用位置对应测试组/用例作为属性类型enum/union/scalar/model 的关键词与花括号形态enum、union、scalar、model各 describe 组通过 alias 解析并保持expression: true“resolves through an alias and keeps expression: true”作为 operation 的返回类型与参数类型“can be used as an operation return type / parameter type”作为 union 的变体、嵌套在其他声明表达式内“can be used as a union variant”、“can be nested inside another declaration expression”作为装饰器参数传递匿名与命名两种as a decorator argument组元组等表达式上下文别名解析用例extends子句支持model、scalar、union的声明表达式支持与语句形态相同的extends子句。一个关键细节union 表达式使用extends时额外还需要union-extends特性否则会报告union-extends-disabled错误消息见 messages.ts测试见 “reports an error when the union-extends feature is not enabled”。即同时需要features: - declaration-expressions - union-extends # 仅当 union 表达式使用 extends 时此外测试组还验证了unionextends能约束匿名/命名 union 表达式的变体不可赋值到基类型的变体会报错model 表达式支持is遗产子句可无 bodyscalar 表达式支持构造器。边界与限制不允许模板参数测试组 “template parameters are not allowed in expression position” 明确验证在表达式位置写带模板参数的声明如modelT { ... }作为表达式会报告诊断语句位置则仍然允许模板参数。可 augmentchecker 中的 isDeclarationExpressionSym 表明命名声明表达式是“真实可引用类型”可以作为 augment decorator 的目标通过::type成员访问测试组 “augment decorators” 验证了对命名 model、匿名 enum、union、scalar 表达式的 augment 能力。装饰器与文档注释声明表达式上可应用装饰器表达式成员上也可以内联文档注释doc comment会像doc一样作用于声明表达式显式doc可以覆盖测试组doc comments。这些能力来自同批次的姊妹变更见下文。类型命名与显示测试组 “type name” 验证了类型名渲染规则匿名表达式类型名会以内联形式渲染如enum { a, b }直接展开且不带命名空间限定命名表达式按名字渲染如Inner同样不带 namespace 前缀。这符合其“不注册进外围命名空间”的设计——既然不是命名空间成员类型名自然不需要命名空间限定。相关姊妹变更.chronus/changes/目录下存在一组同一批次2026-4-18的前缀为decl-expr-的变更条目构成声明表达式特性的完整能力面可在仓库中查阅decl-expr-decorators-2026-4-18-0-0-2.md声明表达式上的装饰器支持decl-expr-doc-comments-2026-4-18-0-0-3.md文档注释支持decl-expr-formatting-2026-4-18-0-0-4.md格式化器支持decl-expr-json-schema-inline-2026-4-18-0-0-1.md 与 decl-expr-openapi-inline-2026-4-18-0-0-1.mdJSON Schema / OpenAPI 输出内联声明表达式decl-expr-typekit-enum-2026-4-18-0-0-1.mdtypekit 对枚举表达式的适配decl-expr-versioning-validation-2026-4-18-0-0-1.md版本化验证对声明表达式的处理。从源码结构看html-program-viewer也有一项 expression 支持变更说明类型图可视化侧同步适配了表达式类型。小结与实践建议声明表达式是实验性功能API 未来可能变化在正式项目中启用前应在tspconfig.yaml中明确加入declaration-expressions并知悉其语义可能随版本演进启用后model/enum/union/scalar可匿名或命名地用于别名、属性、装饰器参数、模板实参、调用参数、元组等表达式位置且model/scalar/union保留extends能力union 需叠加union-extends未启用特性时会得到明确的declaration-expression-disabled错误提示错误信息直接指明了修复方式表达式位置的声明不支持模板参数且命名表达式不能按名字二次引用——这两点是与语句级声明最显著的行为差异深入验证可参考 declaration-expressions.test.ts 中的用例矩阵它几乎逐条覆盖了上文所述的行为约定是理解该特性边界的最可靠依据。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
TypeSpec 声明表达式：在表达式位置使用 model、enum、union 与 scalar 的完整指南
TypeSpec 声明表达式在表达式位置使用 model、enum、union 与 scalar 的完整指南【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespecTypeSpec 编译器typespec/compiler在近期版本中引入了实验性的“声明表达式”declaration expressions功能它允许把model、enum、union、scalar四类声明直接写在表达式位置如属性类型、别名、装饰器参数而不必先声明成顶层或成员级符号。本文基于仓库中的变更日志条目 decl-expr-declaration-expressions-2026-4-18-0-0-0.md 展开并结合 checker 源码、特性开关实现 与 测试用例完整讲解该功能的启用方式、语法规则、使用位置边界以及底层实现机制帮助你在项目中正确启用并驾驭这一实验特性。声明表达式是什么传统的 TypeSpec 声明必须占据“语句位置”——即 namespace、接口或 model 的成员槽位拥有独立的符号并被注册到所在命名空间中。声明表达式则打破了这一限制它把声明语法本身当作一个“值”类型构造器来使用出现在任何期望表达式的上下文里。官方变更条目给出的完整示例如下涵盖别名、属性类型、装饰器参数与带extends的 scalar 表达式alias Foo enum { a, b, }; model Bar { status: enum { active, inactive }; unit: scalar extends string; inner: model Inner { x: string }; } Versioning.versioned(enum Versions { v1, v2 }) namespace MyService;其中涉及三个关键行为约定均来自变更日志原文标记expression: true凡是在表达式位置使用的声明其对应类型都会被标记expression: true供上层如 typekit、emitter区分它和语句级声明不注册到外围命名空间声明表达式不会在外围 namespace 中注册符号即enum { a, b }不会在命名空间里产生一个可查找的类型名可命名也可匿名它既可以带名字如model Inner { x: string }也可以匿名此时类型没有名字。命名表达式会保留名字用于类型显示但不能通过名字再次引用它——这一点由测试用例 “cannot be referenced by its name” 明确验证见 declaration-expressions.test.ts。语句级声明与表达式级的标记差异expression标记是双向的不仅表达式位置的声明为expression: true语句位置的model/enum/union/scalar声明也会被显式标记expression: false测试组 “statement declarations are not expressions”。可以推断这一对称标记是为了让依赖类型元数据的下游工具emitter、类型图可视化等无需再做“是否语句级声明”的猜测直接读取布尔字段即可。如何启用tspconfig.yaml 的 features 开关这是一个实验性特性必须显式开启。变更日志明确要求在tspconfig.yaml的features列表中加入declaration-expressions若未开启而在代码中使用了声明表达式编译器会报告declaration-expression-disabled错误注意是 error 级别不是警告。启用配置示例# tspconfig.yaml features: - declaration-expressions特性开关的源码实现特性定义位于 features.tsdeclaration-expressions: { description: Allows use of declaration expressions (named or anonymous model, scalar, enum and union declarations in expression position) in project code., },同文件中的isCompilerFeatureEnabled函数features.ts揭示了开关的解析规则值得注意项目代码读取根项目tspconfig.yaml的features列表库代码按源文件所属包解析——库可以通过自己的tspconfig.yaml为自身代码独立启用特性与消费方项目的配置相互独立编译器标准库与合成代码从不被特性门控never gated。这意味着特性检查是“按代码归属地”解析的而不是全局一刀切。诊断错误的触发路径错误消息定义在 messages.tsdeclaration-expression-disabled: { severity: error, messages: { default: Declaration expressions require the declaration-expressions feature to be enabled. Add declaration-expressions to the features list in your tspconfig.yaml., }, },触发逻辑在 checker 的 reportDeclarationExpressionFeature 中它先判断节点是否属于四种“表达式形态”之一ModelDeclarationExpression、ScalarDeclarationExpression、EnumDeclarationExpression、UnionDeclarationExpression再调用isCompilerFeatureEnabled(program, declaration-expressions, node)按上文规则解析特性集合未启用即上报诊断。这也说明扫描器/解析器层面已为声明表达式定义了独立的 AST 节点类型SyntaxKind.*DeclarationExpression与语句位置的*Statement节点分开建模。可用的位置与语法能力变更日志说明声明表达式“可以在任何期望表达式的地方使用”并列举了具体场景别名alias、model 属性、装饰器参数、模板参数位置作为模板实参、函数/调用参数、元组tuple。仓库测试 declaration-expressions.test.ts 对这些位置做了系统性验证从测试用例标题可以确认以下已覆盖的用法使用位置对应测试组/用例作为属性类型enum/union/scalar/model 的关键词与花括号形态enum、union、scalar、model各 describe 组通过 alias 解析并保持expression: true“resolves through an alias and keeps expression: true”作为 operation 的返回类型与参数类型“can be used as an operation return type / parameter type”作为 union 的变体、嵌套在其他声明表达式内“can be used as a union variant”、“can be nested inside another declaration expression”作为装饰器参数传递匿名与命名两种as a decorator argument组元组等表达式上下文别名解析用例extends子句支持model、scalar、union的声明表达式支持与语句形态相同的extends子句。一个关键细节union 表达式使用extends时额外还需要union-extends特性否则会报告union-extends-disabled错误消息见 messages.ts测试见 “reports an error when the union-extends feature is not enabled”。即同时需要features: - declaration-expressions - union-extends # 仅当 union 表达式使用 extends 时此外测试组还验证了unionextends能约束匿名/命名 union 表达式的变体不可赋值到基类型的变体会报错model 表达式支持is遗产子句可无 bodyscalar 表达式支持构造器。边界与限制不允许模板参数测试组 “template parameters are not allowed in expression position” 明确验证在表达式位置写带模板参数的声明如modelT { ... }作为表达式会报告诊断语句位置则仍然允许模板参数。可 augmentchecker 中的 isDeclarationExpressionSym 表明命名声明表达式是“真实可引用类型”可以作为 augment decorator 的目标通过::type成员访问测试组 “augment decorators” 验证了对命名 model、匿名 enum、union、scalar 表达式的 augment 能力。装饰器与文档注释声明表达式上可应用装饰器表达式成员上也可以内联文档注释doc comment会像doc一样作用于声明表达式显式doc可以覆盖测试组doc comments。这些能力来自同批次的姊妹变更见下文。类型命名与显示测试组 “type name” 验证了类型名渲染规则匿名表达式类型名会以内联形式渲染如enum { a, b }直接展开且不带命名空间限定命名表达式按名字渲染如Inner同样不带 namespace 前缀。这符合其“不注册进外围命名空间”的设计——既然不是命名空间成员类型名自然不需要命名空间限定。相关姊妹变更.chronus/changes/目录下存在一组同一批次2026-4-18的前缀为decl-expr-的变更条目构成声明表达式特性的完整能力面可在仓库中查阅decl-expr-decorators-2026-4-18-0-0-2.md声明表达式上的装饰器支持decl-expr-doc-comments-2026-4-18-0-0-3.md文档注释支持decl-expr-formatting-2026-4-18-0-0-4.md格式化器支持decl-expr-json-schema-inline-2026-4-18-0-0-1.md 与 decl-expr-openapi-inline-2026-4-18-0-0-1.mdJSON Schema / OpenAPI 输出内联声明表达式decl-expr-typekit-enum-2026-4-18-0-0-1.mdtypekit 对枚举表达式的适配decl-expr-versioning-validation-2026-4-18-0-0-1.md版本化验证对声明表达式的处理。从源码结构看html-program-viewer也有一项 expression 支持变更说明类型图可视化侧同步适配了表达式类型。小结与实践建议声明表达式是实验性功能API 未来可能变化在正式项目中启用前应在tspconfig.yaml中明确加入declaration-expressions并知悉其语义可能随版本演进启用后model/enum/union/scalar可匿名或命名地用于别名、属性、装饰器参数、模板实参、调用参数、元组等表达式位置且model/scalar/union保留extends能力union 需叠加union-extends未启用特性时会得到明确的declaration-expression-disabled错误提示错误信息直接指明了修复方式表达式位置的声明不支持模板参数且命名表达式不能按名字二次引用——这两点是与语句级声明最显著的行为差异深入验证可参考 declaration-expressions.test.ts 中的用例矩阵它几乎逐条覆盖了上文所述的行为约定是理解该特性边界的最可靠依据。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
