tsp 客户端

tsp-client 是一个简单的命令行工具来方便从 TypeSpec 生成客户端库.

先决条件

• 节点js 18.19 LTS 或需要较晚时间

安装

npm install -g @azure-tools/typespec-client-generator-cli

注: " Repo " 所有人应当遵守《公约》的步骤 tsp - 客户端重传设置 医生.

使用量

tsp-client < command > [options]

图标

使用其中一个支持的命令从TypeSpec项目开始生成客户端.

此工具将默认使用您当前的工作目录生成客户端 用于查找相关的配置文件。 要指定不同的输出目录, 请使用 页:1 -o 或者说 --output-dir 选项.

要查看支持的命令, 请运行 :

tsp-client --help

要查看支持的特定命令的参数和选项, 运行:

tsp-client < command > --help

使用 init 命令 :

tsp-client init --help

输入

使用 tspconfig.yaml 初始化客户端库目录 。 当运行此命令时, 在本地路径或远程 tspconfig 的 URL 中通过 。 来啊 -c 或者说 --tsp-config 旗帜。 如果远程, tspconfig 。 Yaml必须包含路径中的具体承诺. (见下文实例)

这个 init 命令按照整个Azure SDK语言寄存器所用的标准模式生成目录结构,创建 tsp-location.yaml (中文(简体) ) 文件用于控制生成,并履行客户端库的初始生成。 如果您想要跳过客户端库生成, 请通过 --skip-sync-and-generate 旗帜.

重要: 此命令应从寄存器的根来运行 。 示例寄存器根 : azure-sdk-for-python/

示例

tsp-client init -c https://github.com/Azure/azure-rest-api-specs/blob/dee71463cbde1d416c47cf544e34f7966a94ddcb/specification/contosowidgetmanager/Contoso.WidgetManager/tspconfig.yaml

更新

这个 update 命令将查找一个 tsp-location.yaml (中文(简体) ) 当前目录中的文件可以同步 TypeSpec 项目并生成客户端库。 更新流称为 sync 财务报告和审定财务报表 generate 命令,所以如果需要将这些步骤分开,请使用 sync 财务报告和审定财务报表 generate 相反,命令是分开的.

示例

tsp-client update

批量图书馆的生成参见 批量库生成 说明.

同步

用 tsp-location.yaml 中指定的参数同步 TypeSpec 项目.

默认情况下 sync 命令将查找 tsp- 位置。 获取项目细节并同步到一个名为“ 临时目录” 的临时目录 TempTypeSpecFiles。作为替代,您可以在 --local-spec-repo 标记与您本地 TypeSpec 项目的路径, 将这些文件拖入您的临时目录 .

示例

tsp-client sync

生成

从 TypeSpec 项目创建客户端库. 这个 generate 命令应在 sync 命令. generate 取决于存在 TempTypeSpecFiles 创建目录 sync 命令和命令时 emitter-package.json 文件在以下路径中检查到您的仓库 : <repo root>/eng/emitter-package.json编辑 emitter-package.json 文件用于安装项目依赖性并获得适当的发射包.

示例

tsp-client generate

转换

将已有的 swagger 规格转换为 TypeSpec 项目 。 此命令只应运行一次才能开始在 TypeSpec 项目上工作. TypeSpec项目需要在转换后手动优化并进行全面审查. 当使用此命令时, 需要通过 : --swagger-readme 旗帜。 默认情况下,被转换的TypeSpec项目将用标准模式和模板来利用TypeSpec内置库(高推荐),这将造成生成的TypeSpec和原生的 swagger之间的差异. 如果你真的不想要这个 想要的差异,添加 --fully-compatible 旗来生成一个完全兼容 swagger 的 Typec 项目.

示例

tsp-client convert -o ./Contoso.WidgetManager --swagger-readme < path-to > /readme.md

排序拓扑器

用 TypeSpec 生成的 swagger 排序现有的 swagger 规格为相同的内容顺序 。 这将允许您比较并识别当前所生成的 swagger 和 TypeSpec 之间的区别 。 在创建已转换的 TypeSpec PR 之前, 您应该运行此命令 .

生成配置文件

此命令生成 tsp- 客户端使用的默认配置文件 。 运行此命令以生成 emitter-package.json 财务报告和审定财务报表 emitter-package-lock.json 下划线 纳克/ 您当前仓库的目录 .

要求: 使用 --package-json 标记以指定软件包的路径。json文件用于生成客户端库.

示例

tsp-client generate-config-files --package-json < path-to-emitter-repo-clone > /package.json

任何额外的 npm 旗可以使用 --npm-args 选项。 这允许您通过任何 npm 旗帜, 如 --registry, (中文(简体) ), --legacy-peer-deps, (中文(简体) ), --force空格分隔字符串中的等:

tsp-client generate-config-files --package-json < path-to-emitter-repo-clone > /package.json --npm-args="--registry=https://my-registry --legacy-peer-deps"

使用 azure-sdk-for-js 编辑 @azure-tools/typespec-ts 发射器 :

这个 --package-json 旗帜应该是重新复制@azure-tools/typespec-ts包的相对或绝对路径.

azure-sdk-for-js > tsp-client generate-config-files --package-json < path-to-emitter-repo-clone > /package.json

要明确指定您想要绑定的依赖性, 请在软件包中添加一个新字段。 json 文件名为 "azure-sdk/emitter-package-json-pinning" 带有您想要转发到排放包的依赖性列表 。 这些依赖关系必须在您的软件包中指定 。 json的devDependency,以便工具指定正确的版本.

注:如果 azure-sdk/emitter-package-json-pinning 字段从 package.json 文件中缺失。该工具将默认对下面列出的软件包进行针入 peerDependencies。 。 。 .

示例包.json 使用 "azure-sdk/emitter-package-json-pinning"数字 :

{
  "name": "@azure-tools/typespec-foo",
  "version": "0.4.0-alpha.20250110.1",
  ...
  "dependencies": {
    "@azure-tools/generator-foo": "0.3.0",
    "@typespec/http-client-foo": "1.2.0"
  },
  "devDependencies": {
    "@typespec/compiler": "0.64.0",
    "rimraf": "^6.0",
  },
  "azure-sdk/emitter-package-json-pinning": [
    "@typespec/compiler"
  ]
}

示例 emitter-package.json 由软件包生成. json 上所示:

{
  "main": "dist/src/index.js",
  "dependencies": {
    "@azure-tools/typespec-foo": "0.4.0-alpha.20250110.1"
  },
  "devDependencies": {
    "@typespec/compiler": "0.64.0"
  }
}

如果您需要覆盖您的 emiters- package.json 的依赖性, 您可以创建 json 文件, 以明确列出您想要覆盖的软件包和相应的版本 。 这将增加一个 overrides 在您发射包中的区域。 json 将用于 npm install 或者说 npm ci。 。 。 . 参见 npm 覆盖 doc .

有包覆盖的示例 json 文件 :

{
  "@azure-tools/typespec-foo": "https://<dev-feed-url>/typespec-foo-0.4.0-alpha.20250110.1.tgz",
  "@azure-tools/generator-foo": "https://<dev-feed-url>/generator-foo-1.3.0-alpha.20250110.1.tgz"
}

指定覆盖的示例命令 :

tsp-client generate-config-files --overrides my_overrides.json --package-json < path-to-emitter-repo-clone > /package.json

示例 emitter-package.json 使用覆盖生成 :

{
  "main": "dist/src/index.js",
  "dependencies": {
    "@azure-tools/typespec-foo": "https://<dev-feed-url>/typespec-foo-0.4.0-alpha.20250110.1.tgz"
  },
  "devDependencies": {
    "@typespec/compiler": "~0.64.0"
  },
  "overrides": {
    "@azure-tools/generator-foo": "https://<dev-feed-url>/generator-foo-1.3.0-alpha.20250110.1.tgz"
  }
}

生成锁定文件

根据已有的 eng/ 目录在 eng/ 目录下生成一个发报- package-lock.json <repo-root>/eng/emitter-package.json。 。 。 .

示例

tsp-client generate-lock-file

任何额外的 npm 旗帜都可以传送到下面 npm install 使用 --npm-args 选项。 这允许您通过任何 npm 旗帜, 如 --registry, (中文(简体) ), --legacy-peer-deps, (中文(简体) ), --force空格分隔字符串中的等:

tsp-client generate-lock-file --npm-args="--registry=https://my-registry --legacy-peer-deps"

安装依赖性

默认情况下在寄存器的根部安装嵌入于emitter-package.json和emitter-package-lock.json(如果存在的话)的依赖性. 该命令支持一个位置路径参数,如果需要将依赖性安装到另一个目录中.

IMPORANT:节点 模块/目录需要安装在一条路径上,基本npm命令可以使用. 通常与要编译的目标 Typec 项目在同一目录路径内.

tsp-client install-dependencies [optional install path]

重要概念

每个项目设置

每个工程都需要有一个名为tsp-location的配置文件. 将告诉工具在哪里找到 TypeSpec 项目 .

tsp-location.yaml (中文(简体) )

此文件通过 tsp-client init 命令或您可以在项目目录下手动创建它,以运行此工具所支持的其他命令.

注: 此文件应存在于每个服务的项目目录下.

文件有以下属性:

示例

directory: specification/contosowidgetmanager/Contoso.WidgetManager
commit: 431eb865a581da2cd7b9e953ae52cb146f31c2a6
repo: Azure/azure-rest-api-specs
additionalDirectories:
  - specification/contosowidgetmanager/Contoso.WidgetManager.Shared/

高级设想

批量库生成

批量客户端库生成仅支持 tsp-client update 命令。 为了使批量生成能够遵循这些步骤:

1. 增加tsp-位置. 将生成所有批次库的父目录中的 yaml 文件 。 示例

- sdk/
  - foo/
    - tsp-location.yaml
    - bar/
    - zas/

2. 顶级tsp-位置. 雅姆尔应该只有 batch 属性配置。 分批地产预计将是直接包含正则 tsp-位置的子目录. 为客户端库生成配备了适当配置的yaml文件. 其他 tsp- location.yaml 属性, 如 directory, (中文(简体) ), commit, (中文(简体) ), repo, (中文(简体) ), additionalDirectories 目前不支持 batch 配置 。 示例

batch:
  - ./bar
  - ./zas

3. 确保在 batch 列表有 tsp- 位置。 为它们配置了 yaml 文件 。 若分行所出无有取取取取取取取出. Tsp- 客户端将返回一个错误 。 以设tsp-地. 子目录中的 yaml 文件, 您可以创建 tsp- 位置 。 手动或使用 Yaml 文件 tsp-client init 附有适当 emitter-output-dir 配置来创建它 .

需要的文件结构示例 :

- sdk/
  - foo/
    - tsp-location.yaml
    - bar/
        - tsp-location.yaml
    - zas/
        - tsp-location.yaml

子目录中的正则 tsp-location.yaml 示例 :

directory: specification/contosowidgetmanager/Contoso.WidgetManager
commit: abc123
repo: Azure/azure-rest-api-specs
additionalDirectories:
  - specification/contosowidgetmanager/Contoso.WidgetManager.Shared/

4. 运行 tsp-client update 从父目录。 上面的例子就是 foo/ 目录.

注:如果 update 调用子目录失败 .

5. 都结束了! tsp-客户端会调用每个子目录上的更新命令,向命令转发命令行参数.

注: local-spec-repo 旗在批量库生成时会有特殊的行为. tsp客户端将获得传递到旗帜的本地光谱回波路径的回波根路径,然后从 tsp 位置附加目录值. 相应的子目录中的 yaml 文件 .