Microsoft kiota 在 TypeScript/JavaScript 下的使用

2023年12月5日 1362点热度 0人点赞 0条评论
内容纲要

Kiota 是一个命令行工具,用于将 swagger、openapi 生成对应语言的的代码文件,目前支持:

  • .NET
  • CLI(C# 的 System.CommandLine)
  • Go
  • Java
  • PHP
  • Python
  • TypeScript/JavaScript

官方文档:
https://learn.microsoft.com/en-us/openapi/kiota/

官方仓库:
https://github.com/microsoft/kiota

据笔者使用,此工具目前尚未成熟,Bug 较多。此工具貌似是 Azure 内部开发使用的,用于快速生成对应语言的 SDK ,主要是 Microsoft Graph API,然后后面工具开源了。

这里就不多说了,下面来说一下这个工具如何生成 TypeScript 代码。

首先是安装 kiota ,它可以通过 .NET CLI 工具、VSCode 插件等形式安装,然后通过工具生成代码文件。但是,还有一点最重要的是,生成的代码文件是有依赖的,必须引入相关的 kiota 库!所以,这是有代价的!而且个人认为目前比较重!而且挺难用!

在 VSCode 中搜索 Microsoft Kiota 并安装:

file

然后点击打开 API 描述文档。
file

然后按照提示输出 swagger/openapi 文档地址即可,支持 json、yaml 等格式。

生成代码后,会有很多文件。

file

目录下会有个 xxxClient ,这个是入口文件,然后其它文件是模型类以及不同名称路由的 http 处理器。一般会使用控制器做路由,所以目录也会按照对应的 url 路由目录划分。

然后在项目中安装以下包:

npm install @microsoft/kiota-abstractions
npm install @microsoft/kiota-http-fetchlibrary
npm install @microsoft/kiota-serialization-form
npm install @microsoft/kiota-serialization-json
npm install @microsoft/kiota-serialization-text
npm install @microsoft/kiota-serialization-multipart

在代码中引入依赖:

import { AnonymousAuthenticationProvider } from '@microsoft/kiota-abstractions';
import { FetchRequestAdapter } from '@microsoft/kiota-http-fetchlibrary';

引入生成的代码文件:

import { ApiClient } from '../apiclient/apiClient'

实例化、初始化 http 请求基础配置:

const authProvider = new AnonymousAuthenticationProvider();
const adapter = new FetchRequestAdapter(authProvider);
adapter.baseUrl = "https://aaa.com";
const myClient = new ApiClient(adapter);

发出一个 http get 请求:

        var response = await myClient.控制器名称.方法名称.get();

上面的代码演示了调用路径。
具体的路径可以在代码目录中摸索,基本是按照目录分层的。
例如 /account/add ,调用代码:

 var response = await myClient.account.add.get();

但是,调用的时候很容易报错。

file

类型“Record<string, string[]> | undefined”的参数不能赋给类型“Headers | undefined”的参数。
  类型“Record<string, string[]>”缺少类型“Headers”的以下属性: headers, singleValueHeaders, set, get 及其他 16 项。ts(2345)
(parameter) requestConfiguration: Db_listRequestBuilderGetRequestConfiguration
Configuration for the request such as headers, query parameters, and middleware options.

@param requestConfiguration — Configuration for the request such as headers, query parameters, and middleware options.
属性“tryAddRequestHeaders”在类型“RequestInformation”上不存在。你是否指的是“addRequestHeaders”?ts(2551)
requestInformation.d.ts(39, 5): 在此处声明了 "addRequestHeaders"。

这是估计 kiota 代码生成工具跟 kiota 依赖库不兼容的 bug。所以这里需要自己手动修复。
将包含以下代码的行都注释掉:

requestInfo.addRequestHeaders(requestConfiguration.headers);
requestInfo.tryAddRequestHeaders

file

如果 get 中有参数,那就真的坑了。

这样请求是错的:

 var response = await myClient.account.add.get();

要这样使用:

 var response = await myClient.account.add.get({
            queryParameters: {
                name: datasource
            }
        });

因为生成的代码太黑暗了。

file
file
file

所以使用的时候,必须去代码文件好好看一下接口定义。。。

总的来说,能够识别多种类型的 API 接口生成代码。但是生成的代码有问题,需要注释掉,并且代码过于复杂和麻烦,没有类似其它工具生成的代码标准统一。生成的代码并不 “原生” ,还必须依赖 SDK 一起使用,所以比较重。再者,生成的 API 接口调用好麻烦和复杂!笔者也是搞了很久才通的!
微软的东西,一如既往的黑暗!

痴者工良

高级程序员劝退师

文章评论