TypeSpec 1.5.0 版本深度解析OpenAPI operationId 生成策略、时长编码增强与 LSP/API 能力升级【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespecTypeSpec 1.5.0发布于 2025-10-08是一次以「发射器灵活性与开发者工具链」为核心的版本升级。本指南以官方发布说明为骨架结合当前仓库源码与测试用例系统拆解本次更新中typespec/compiler、typespec/openapi3、typespec-vscode三大模块的新特性与问题修复重点讲解 OpenAPI operationId 的三种生成策略、DurationKnownEncoding新增毫秒编码、secret装饰器目标类型的扩展以及编译器公共 API 与 LSP 入口点配置的增强。读完本文你将掌握这些新能力的确切用法、配置项取值范围与底层实现原理可直接应用于实际 TypeSpec 项目中。版本概览本次发布共涉及三大包包类型亮点typespec/compilerFeatures / Bug Fixes测试 API、时长编码、LSP 入口点、公共 API 暴露、secret扩展、codefix 增强typespec/openapi3Features / Bug Fixes新增operation-id-strategy选项、importer 一系列导入修复typespec-vscodeFeaturesLSP 入口点配置、编译任务与 emitter 加载行为调整此外typespec/json-schema与typespec/rest各修复了一个崩溃问题。一、typespec/openapi3全新的operation-id-strategy选项这是 1.5.0 中面向 OpenAPI 文档使用者最直接的可见变更。在未显式使用operationId时OpenAPI 发射器如何为操作生成operationId此前是固定行为现在你可以通过tspconfig.yaml中的options[typespec/openapi3]显式控制。三种策略的定义在 packages/openapi3/src/lib.ts 中策略类型被定义为export type OperationIdStrategy parent-container | fqn | explicit-only;对应的行为如下策略说明默认分隔符示例namespace Baz { namespace Bar { op foo(): string } }位于service命名空间下parent-container取操作最近的父容器interface 或 namespace名称与操作名拼接。这是默认行为也是 1.5.0 之前的历史行为_Bar_foofqn从 service 根到操作的完整限定名逐级拼接.Baz.Bar.fooexplicit-only完全不自动生成只输出显式通过operationId指定的 ID—未设置operationId时该操作为undefined三种策略的默认分隔符实现在 packages/openapi3/src/openapi.ts 中通过resolveOperationIdDefaultStrategySeparator按策略返回_、.或空字符串。在 tspconfig.yaml 中使用operation-id-strategy既可接受简单字符串也可接受带自定义separator的对象形式完整 JSON Schema 校验见 packages/openapi3/src/lib.tsemit: - typespec/openapi3 options: typespec/openapi3: operation-id-strategy: fqn # 字符串形式Baz.Bar.foo或自定义分隔符options: typespec/openapi3: operation-id-strategy: kind: fqn # parent-container | fqn | explicit-only separator: / # 自定义拼接分隔符如 Baz/Bar/foo对象形式各字段说明字段类型默认值说明kindparent-container \| fqn \| explicit-onlyparent-container决定operationId缺失时的生成方式separatorstring随kind变化_/./用于拼接操作名各段的字符在 packages/openapi3/src/openapi.ts 中resolveOperationIdStrategy负责归一化未配置时返回默认的{ kind: parent-container, separator: _ }传入字符串时自动补全对应默认分隔符传入对象时若省略separator同样按kind取默认值。类型定义同时支持字符串与对象两种写法见 lib.ts。底层实现OperationIdResolver生成逻辑收敛在独立的OperationIdResolver类中packages/openapi3/src/operation-id-resolver/operation-id-resolver.ts其解析流程为若操作上显式存在operationId通过getOperationId读取直接返回该值策略不生效否则按策略执行#resolveInternalparent-container取路径最后两段拼接operationPath.slice(-2).join(separator)fqn取完整路径拼接operationPath.join(separator)explicit-only返回undefined路径由#getOperationPath构造从操作名出发沿interface/namespace逐级向上直到遇到全局命名空间或service标记的命名空间为止这部分决定了为什么直接定义在 service 命名空间下的操作不会带上命名空间前缀。去重机制不同 namespace 下可能出现同名操作导致生成的 operationId 冲突。1.5.0 同步修复了这一问题原文档 Bug Fixes 中 Deduplicate operation ids that would resolve to the same one。OperationIdResolver内部维护#used集合一旦发现已使用过的名称通过#findNextAvailableName追加_2、_3后缀见 operation-id-resolver.ts。测试用例验证operation-id-resolver.test.tspackages/openapi3/src/operation-id-resolver/operation-id-resolver.test.ts为三种策略各编写了完整用例可直接作为行为规格参考parent-container根级操作生成fooservice 命名空间下直接定义的操作仍是foo不拼接 service 名interface 内为Bar_foo嵌套 namespaceBaz Bar中只取最近一层Bar_foo去重用例中Onenamespace 的test与Twointerface 下的test分别解析为One_test与One_test_2fqn嵌套 namespace 会得到完整路径Baz.Bar.fooexplicit-only显式OpenAPI.operationId(explicit_foo)时返回explicit_foo未设置时返回undefined。二、typespec/compiler新特性详解2.1 DurationKnownEncoding 新增 millisecondsDurationKnownEncoding枚举packages/compiler/lib/std/decorators.tsp原本只支持ISO8601与seconds两种编码。1.5.0 新增milliseconds成员定义在 TypeSpec 语言标准库层面enum DurationKnownEncoding { ISO8601: ISO8601, // ISO8601 时长字符串 seconds: seconds, // 以秒为单位的整数或浮点数 milliseconds: milliseconds, // 以毫秒为单位的整数或浮点数1.5.0 新增 }对应的 TS 类型别名位于 packages/compiler/src/lib/decorators.ts并在 packages/compiler/src/index.ts 中作为公共导出。它的典型用途是与encode装饰器配合例如将duration编码为毫秒数值encode(DurationKnownEncoding.milliseconds) duration elapsed: duration;。新增毫秒编码后时长类型在 JSON 序列化场景下可以更精确地表达亚秒级数据无需再手动换算为秒。2.2secret装饰器目标类型扩展此前secret只允许作用于Scalar与ModelProperty。1.5.0 将目标扩展为Model、Union、Enum即任何数据类型都可以被标记为 secret用于整体性的数据敏感性标记。该变更的意义在于此前若要标记一个由多个字段组成的模型为敏感数据只能逐字段添加装饰器现在可以直接在模型级别声明例如secret model Credentials { username: string; password: string; }发射器如各类客户端代码生成器可以据此识别并整体规避对这些类型的日志输出或文档暴露。2.3 Testing API 增强本次为测试基础设施带来三处改进Tester 暴露 marker 位置Expose marker position in Tester在使用t.code\...模板测试时/marker/ 标记的位置现在可以被测试代码读取便于精确断言诊断信息在源码中的位置Linter 规则测试器传递parseDocsBug Fixes 中 Linter rule tester not passing parseDocs option to new tester instance修复了 linter 规则测试时文档解析选项未被传递给新 tester 实例的问题Tester 支持子导出Support sub exports without having them being defined as separate libraries测试框架允许直接使用库的子路径导出如typespec/openapi/xxx无需将其注册为独立库同时修复了一个可能导致测试超时的问题。2.4 编译器公共 API 扩展1.5.0 集中暴露了一批此前为内部实现的 API方便库作者与工具链开发者使用API位置说明applyCodeFix/applyCodeFixes/resolveCodeFix/applyCodeFixEditspackages/compiler/src/index.ts编程式地应用 codefix。applyCodeFixEdits负责按编辑片段重写文件内容applyCodeFixes批量处理多个 codefixcreateSuppressCodeFixpackages/compiler/src/core/compiler-code-fixes/suppress.codefix.ts生成「添加 suppression 注释」的 codefix程序内部在生成诊断 codefix 时即调用它见 program.tsgetNodeForTargetpackages/compiler/src/ast/index.ts从诊断 target 定位对应的 AST 节点从typespec/compiler/ast导出其中「codefix 跨文件支持」也是一项重要增强codefix 可以作用于与诊断不同的文件并在需要时自动创建新文件suppression codefix 在查找可用父节点时会向上寻找第一个有效父节点Bug Fixes 中 Add suppression codefix looks up for the first valid parent。此外secret等 API 现在支持传入 suppression 消息允许在抑制诊断时附加说明文字。2.5 测试框架与发射器 Schema 支持 UnionEmitter 配置 Schema 支持 Union发射器在声明配置项类型时可以使用 union 类型使得 JSON Schema 校验可以表达更丰富的取值组合Hover 显示模板参数默认值LSP hover 签名中会展示模板参数的默认值提升语言服务体验。2.6 LSP 入口点配置[LSP] Allow configuring which file names to use as entrypointsPR 编号 7929让语言服务器不再硬编码入口点文件名。底层配置项entrypoint定义于编译器的配置 Schema 中packages/compiler/src/config/config-schema.ts并在 config-loader.ts 中被加载校验对应 Bug Fix 是「entrypoint 配置默认值为 null 时不再出错」。这意味着你可以自定义项目入口.tsp文件名默认是main.tspLSP 会按配置识别入口点这在大型 monorepo 或非标准目录结构中尤为实用。2.7 其他编译器修复修正 TypeSpec「unused-using」警告文案中的语法错误删除多余的 be 一词修复 LSP 在动态加载包内某个库后出现的连接失败问题支持导入自身模块如位于typespec/openapi包内时以typespec/openapi/some/path导入自身遵循 ESM 规范。三、typespec-vscode 扩展更新1.5.0 同步将 LSP 入口点配置带入了 VS Code 扩展并调整了两项启动行为PR 8346限制启动时创建的 vscode 任务扩展启动时不再大量预创建编译任务降低启动开销默认不在 LSP 编译中包含 emitters此前 LSP 编译会默认带上tspconfig.yaml中声明的全部 emitters现在默认不包含任何 emitter。如需恢复显式控制可在 VS Code 设置中配置{ typespec.lsp.emit: [typespec/openapi3] }将typespec.lsp.emit设置为[config:defaults]可以恢复为「使用 tspconfig.yaml 中定义的全部 emitters」的旧行为。这一调整让编辑器内的实时类型检查更轻量把 emitter 的执行留给显式的编译命令。四、typespec/openapi3的导入器importer修复本次修复集中在「从已有 OpenAPI 描述导入回 TypeSpec」的路径上这些修复直接关系到 OpenAPI → TypeSpec 的逆向转换质量修复点说明additionalProperties: true {}导入现在正确转换为Recordunknown而不是生成不完整的模型单一any/oneOf解包当anyOf/oneOf只有一个成员时解包该成员得到语义更有意义的类型枚举默认值加前缀导入时为枚举的默认值加上enum前缀避免与普通字面量混淆不再为每个成员类型重复输出默认值避免在导入的描述中为每个成员类型重复发射默认值anyOf/oneOftype: null正确导入并保留装饰器、文档注释multipart 请求体仅在实际存在 multipart 请求体时才导入避免生成多余结构null 默认值崩溃修复「null 值默认值导致导入崩溃」的回归问题属性名为set的崩溃修复在属性名为set时的崩溃typespec/json-schema同步修复五、typespec/rest修复parentResource递归引用typespec/rest修复了一个崩溃场景当资源通过parentResource递归地引用自身时不再崩溃。例如资源层级中 parent 与 child 类型互相循环引用如model A { parentResource parent?: A; }此前会导致发射器栈溢出1.5.0 已处理。总结与升级建议TypeSpec 1.5.0 的关键升级路径建议OpenAPI 使用者升级后注意operation-id-strategy默认值仍为parent-container即历史行为不变、不会破坏现有文档如需更稳定的跨语言 SDK 命名可切换为fqn并在文档生成后对比前后差异库 / 工具链作者applyCodeFix、createSuppressCodeFix、getNodeForTarget等 API 已公开可以围绕编译器诊断构建自定义修复工具编辑器体验VS Code 用户可通过typespec.lsp.emit精细控制 LSP 编译范围获得更快的编辑反馈时长数据建模新milliseconds编码让亚秒级 duration 的 JSON 表达更直接配合encode即可落地。相关源码与测试均可在仓库内查阅openapi3 发射器选项定义、OperationIdResolver 实现与其测试、DurationKnownEncoding 标准库声明、codefix 公共 API。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TypeSpec 1.5.0 版本深度解析：OpenAPI operationId 生成策略、时长编码增强与 LSP/API 能力升级
TypeSpec 1.5.0 版本深度解析OpenAPI operationId 生成策略、时长编码增强与 LSP/API 能力升级【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespecTypeSpec 1.5.0发布于 2025-10-08是一次以「发射器灵活性与开发者工具链」为核心的版本升级。本指南以官方发布说明为骨架结合当前仓库源码与测试用例系统拆解本次更新中typespec/compiler、typespec/openapi3、typespec-vscode三大模块的新特性与问题修复重点讲解 OpenAPI operationId 的三种生成策略、DurationKnownEncoding新增毫秒编码、secret装饰器目标类型的扩展以及编译器公共 API 与 LSP 入口点配置的增强。读完本文你将掌握这些新能力的确切用法、配置项取值范围与底层实现原理可直接应用于实际 TypeSpec 项目中。版本概览本次发布共涉及三大包包类型亮点typespec/compilerFeatures / Bug Fixes测试 API、时长编码、LSP 入口点、公共 API 暴露、secret扩展、codefix 增强typespec/openapi3Features / Bug Fixes新增operation-id-strategy选项、importer 一系列导入修复typespec-vscodeFeaturesLSP 入口点配置、编译任务与 emitter 加载行为调整此外typespec/json-schema与typespec/rest各修复了一个崩溃问题。一、typespec/openapi3全新的operation-id-strategy选项这是 1.5.0 中面向 OpenAPI 文档使用者最直接的可见变更。在未显式使用operationId时OpenAPI 发射器如何为操作生成operationId此前是固定行为现在你可以通过tspconfig.yaml中的options[typespec/openapi3]显式控制。三种策略的定义在 packages/openapi3/src/lib.ts 中策略类型被定义为export type OperationIdStrategy parent-container | fqn | explicit-only;对应的行为如下策略说明默认分隔符示例namespace Baz { namespace Bar { op foo(): string } }位于service命名空间下parent-container取操作最近的父容器interface 或 namespace名称与操作名拼接。这是默认行为也是 1.5.0 之前的历史行为_Bar_foofqn从 service 根到操作的完整限定名逐级拼接.Baz.Bar.fooexplicit-only完全不自动生成只输出显式通过operationId指定的 ID—未设置operationId时该操作为undefined三种策略的默认分隔符实现在 packages/openapi3/src/openapi.ts 中通过resolveOperationIdDefaultStrategySeparator按策略返回_、.或空字符串。在 tspconfig.yaml 中使用operation-id-strategy既可接受简单字符串也可接受带自定义separator的对象形式完整 JSON Schema 校验见 packages/openapi3/src/lib.tsemit: - typespec/openapi3 options: typespec/openapi3: operation-id-strategy: fqn # 字符串形式Baz.Bar.foo或自定义分隔符options: typespec/openapi3: operation-id-strategy: kind: fqn # parent-container | fqn | explicit-only separator: / # 自定义拼接分隔符如 Baz/Bar/foo对象形式各字段说明字段类型默认值说明kindparent-container \| fqn \| explicit-onlyparent-container决定operationId缺失时的生成方式separatorstring随kind变化_/./用于拼接操作名各段的字符在 packages/openapi3/src/openapi.ts 中resolveOperationIdStrategy负责归一化未配置时返回默认的{ kind: parent-container, separator: _ }传入字符串时自动补全对应默认分隔符传入对象时若省略separator同样按kind取默认值。类型定义同时支持字符串与对象两种写法见 lib.ts。底层实现OperationIdResolver生成逻辑收敛在独立的OperationIdResolver类中packages/openapi3/src/operation-id-resolver/operation-id-resolver.ts其解析流程为若操作上显式存在operationId通过getOperationId读取直接返回该值策略不生效否则按策略执行#resolveInternalparent-container取路径最后两段拼接operationPath.slice(-2).join(separator)fqn取完整路径拼接operationPath.join(separator)explicit-only返回undefined路径由#getOperationPath构造从操作名出发沿interface/namespace逐级向上直到遇到全局命名空间或service标记的命名空间为止这部分决定了为什么直接定义在 service 命名空间下的操作不会带上命名空间前缀。去重机制不同 namespace 下可能出现同名操作导致生成的 operationId 冲突。1.5.0 同步修复了这一问题原文档 Bug Fixes 中 Deduplicate operation ids that would resolve to the same one。OperationIdResolver内部维护#used集合一旦发现已使用过的名称通过#findNextAvailableName追加_2、_3后缀见 operation-id-resolver.ts。测试用例验证operation-id-resolver.test.tspackages/openapi3/src/operation-id-resolver/operation-id-resolver.test.ts为三种策略各编写了完整用例可直接作为行为规格参考parent-container根级操作生成fooservice 命名空间下直接定义的操作仍是foo不拼接 service 名interface 内为Bar_foo嵌套 namespaceBaz Bar中只取最近一层Bar_foo去重用例中Onenamespace 的test与Twointerface 下的test分别解析为One_test与One_test_2fqn嵌套 namespace 会得到完整路径Baz.Bar.fooexplicit-only显式OpenAPI.operationId(explicit_foo)时返回explicit_foo未设置时返回undefined。二、typespec/compiler新特性详解2.1 DurationKnownEncoding 新增 millisecondsDurationKnownEncoding枚举packages/compiler/lib/std/decorators.tsp原本只支持ISO8601与seconds两种编码。1.5.0 新增milliseconds成员定义在 TypeSpec 语言标准库层面enum DurationKnownEncoding { ISO8601: ISO8601, // ISO8601 时长字符串 seconds: seconds, // 以秒为单位的整数或浮点数 milliseconds: milliseconds, // 以毫秒为单位的整数或浮点数1.5.0 新增 }对应的 TS 类型别名位于 packages/compiler/src/lib/decorators.ts并在 packages/compiler/src/index.ts 中作为公共导出。它的典型用途是与encode装饰器配合例如将duration编码为毫秒数值encode(DurationKnownEncoding.milliseconds) duration elapsed: duration;。新增毫秒编码后时长类型在 JSON 序列化场景下可以更精确地表达亚秒级数据无需再手动换算为秒。2.2secret装饰器目标类型扩展此前secret只允许作用于Scalar与ModelProperty。1.5.0 将目标扩展为Model、Union、Enum即任何数据类型都可以被标记为 secret用于整体性的数据敏感性标记。该变更的意义在于此前若要标记一个由多个字段组成的模型为敏感数据只能逐字段添加装饰器现在可以直接在模型级别声明例如secret model Credentials { username: string; password: string; }发射器如各类客户端代码生成器可以据此识别并整体规避对这些类型的日志输出或文档暴露。2.3 Testing API 增强本次为测试基础设施带来三处改进Tester 暴露 marker 位置Expose marker position in Tester在使用t.code\...模板测试时/marker/ 标记的位置现在可以被测试代码读取便于精确断言诊断信息在源码中的位置Linter 规则测试器传递parseDocsBug Fixes 中 Linter rule tester not passing parseDocs option to new tester instance修复了 linter 规则测试时文档解析选项未被传递给新 tester 实例的问题Tester 支持子导出Support sub exports without having them being defined as separate libraries测试框架允许直接使用库的子路径导出如typespec/openapi/xxx无需将其注册为独立库同时修复了一个可能导致测试超时的问题。2.4 编译器公共 API 扩展1.5.0 集中暴露了一批此前为内部实现的 API方便库作者与工具链开发者使用API位置说明applyCodeFix/applyCodeFixes/resolveCodeFix/applyCodeFixEditspackages/compiler/src/index.ts编程式地应用 codefix。applyCodeFixEdits负责按编辑片段重写文件内容applyCodeFixes批量处理多个 codefixcreateSuppressCodeFixpackages/compiler/src/core/compiler-code-fixes/suppress.codefix.ts生成「添加 suppression 注释」的 codefix程序内部在生成诊断 codefix 时即调用它见 program.tsgetNodeForTargetpackages/compiler/src/ast/index.ts从诊断 target 定位对应的 AST 节点从typespec/compiler/ast导出其中「codefix 跨文件支持」也是一项重要增强codefix 可以作用于与诊断不同的文件并在需要时自动创建新文件suppression codefix 在查找可用父节点时会向上寻找第一个有效父节点Bug Fixes 中 Add suppression codefix looks up for the first valid parent。此外secret等 API 现在支持传入 suppression 消息允许在抑制诊断时附加说明文字。2.5 测试框架与发射器 Schema 支持 UnionEmitter 配置 Schema 支持 Union发射器在声明配置项类型时可以使用 union 类型使得 JSON Schema 校验可以表达更丰富的取值组合Hover 显示模板参数默认值LSP hover 签名中会展示模板参数的默认值提升语言服务体验。2.6 LSP 入口点配置[LSP] Allow configuring which file names to use as entrypointsPR 编号 7929让语言服务器不再硬编码入口点文件名。底层配置项entrypoint定义于编译器的配置 Schema 中packages/compiler/src/config/config-schema.ts并在 config-loader.ts 中被加载校验对应 Bug Fix 是「entrypoint 配置默认值为 null 时不再出错」。这意味着你可以自定义项目入口.tsp文件名默认是main.tspLSP 会按配置识别入口点这在大型 monorepo 或非标准目录结构中尤为实用。2.7 其他编译器修复修正 TypeSpec「unused-using」警告文案中的语法错误删除多余的 be 一词修复 LSP 在动态加载包内某个库后出现的连接失败问题支持导入自身模块如位于typespec/openapi包内时以typespec/openapi/some/path导入自身遵循 ESM 规范。三、typespec-vscode 扩展更新1.5.0 同步将 LSP 入口点配置带入了 VS Code 扩展并调整了两项启动行为PR 8346限制启动时创建的 vscode 任务扩展启动时不再大量预创建编译任务降低启动开销默认不在 LSP 编译中包含 emitters此前 LSP 编译会默认带上tspconfig.yaml中声明的全部 emitters现在默认不包含任何 emitter。如需恢复显式控制可在 VS Code 设置中配置{ typespec.lsp.emit: [typespec/openapi3] }将typespec.lsp.emit设置为[config:defaults]可以恢复为「使用 tspconfig.yaml 中定义的全部 emitters」的旧行为。这一调整让编辑器内的实时类型检查更轻量把 emitter 的执行留给显式的编译命令。四、typespec/openapi3的导入器importer修复本次修复集中在「从已有 OpenAPI 描述导入回 TypeSpec」的路径上这些修复直接关系到 OpenAPI → TypeSpec 的逆向转换质量修复点说明additionalProperties: true {}导入现在正确转换为Recordunknown而不是生成不完整的模型单一any/oneOf解包当anyOf/oneOf只有一个成员时解包该成员得到语义更有意义的类型枚举默认值加前缀导入时为枚举的默认值加上enum前缀避免与普通字面量混淆不再为每个成员类型重复输出默认值避免在导入的描述中为每个成员类型重复发射默认值anyOf/oneOftype: null正确导入并保留装饰器、文档注释multipart 请求体仅在实际存在 multipart 请求体时才导入避免生成多余结构null 默认值崩溃修复「null 值默认值导致导入崩溃」的回归问题属性名为set的崩溃修复在属性名为set时的崩溃typespec/json-schema同步修复五、typespec/rest修复parentResource递归引用typespec/rest修复了一个崩溃场景当资源通过parentResource递归地引用自身时不再崩溃。例如资源层级中 parent 与 child 类型互相循环引用如model A { parentResource parent?: A; }此前会导致发射器栈溢出1.5.0 已处理。总结与升级建议TypeSpec 1.5.0 的关键升级路径建议OpenAPI 使用者升级后注意operation-id-strategy默认值仍为parent-container即历史行为不变、不会破坏现有文档如需更稳定的跨语言 SDK 命名可切换为fqn并在文档生成后对比前后差异库 / 工具链作者applyCodeFix、createSuppressCodeFix、getNodeForTarget等 API 已公开可以围绕编译器诊断构建自定义修复工具编辑器体验VS Code 用户可通过typespec.lsp.emit精细控制 LSP 编译范围获得更快的编辑反馈时长数据建模新milliseconds编码让亚秒级 duration 的 JSON 表达更直接配合encode即可落地。相关源码与测试均可在仓库内查阅openapi3 发射器选项定义、OperationIdResolver 实现与其测试、DurationKnownEncoding 标准库声明、codefix 公共 API。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考