前置知识
在开始使用 @apihawk/gear-sdk，你需要了解以下前置知识：
- 基础的 JavaScript 知识
- Node.js 环境和 npm（Node.js 包管理器）
- RESTful API 开发和接口文档的编写
若您对这些知识还不是很熟悉，建议先学习这些知识再继续阅读本文。
什么是 @apihawk/gear-sdk
@apihawk/gear-sdk 是一个针对接口文档生成的 SDK，它可以通过解析 OpenAPI 3.0 规范的 API 接口文档，自动生成前端所需的 TypeScript 类型定义和 API 请求方法等。
使用 @apihawk/gear-sdk 可以自动实现 API 调用所需的参数校验、请求数据格式化、错误消息类型化等功能，减少了前端手写接口请求的工作量。
安装
在 npm 中安装 @apihawk/gear-sdk：
npm install @apihawk/gear-sdk
安装成功后，在代码中引入 SDK：
import { Gear } from '@apihawk/gear-sdk';使用步骤
编写接口文档
@apihawk/gear-sdk 可以自动生成请求方法和类型定义，所以我们需要编写对应规范的接口文档。现假设有以下用户相关的接口：
-- -------------------- ---- -------
-------- -----
-----
------ ---- ---
-------- -----
------
-------
----
-------- ------
------------ ---------
-----------
- ----- ---
--- -----
------------ --
--------- ----
-------
----- ------
----- ------ -------
----------
------
------------ --
--------
-----------------
-------
----- -----
------
----- ------
-----------
---
----- ------
------------ -- --
-----
----- ------
------------ ---
----
----- ------
------------ --
-----
-------- ----
------------ ----------
------------
--------
-----------------
-------
----- ------
-----------
-----
----- ------
------------ ---
----
----- ------
------------ --
----- ------ -------
----------
------
------------ --
--------
-----------------
-------
----- ------
-----------
---
----- ------
------------ -- --
-----
----- ------
------------ ---
----
----- ------
------------ --上述 YAML 格式的文档中，定义了两个用户接口：
GET /users：获取用户列表，须传入sex参数。POST /users：创建用户，须传入name和sex参数。
生成请求方法和类型定义
安装成功并编写接口文档后，可以使用 @apihawk/gear-sdk 自动生成请求方法和类型定义。
例如，我们将接口文档保存在 docs/user.yaml 中，运行以下命令：
npx apihawk ./docs/user.yaml -o ./src/apis/user.ts
此命令将解析 docs/user.yaml 并在 src/apis/user.ts 中自动生成对应的请求方法和类型定义：
-- -------------------- ---- ------- ------ --------- ----- - --- ------- ----- ------- ---- ------ - --------- - ------ -------- -------------- ------ - --------- --------- ------------------------- ----------- ----------------- ------ -------- ---------------- - ----- ------- ---- ------ - -------- -- --------- ------------------------- ------- - ---------------------------------- ---------------
请求方法的名称和方法参数类型不是固定的，它们与接口文档中 operationId、schema 等属性相关，可以通过修改接口文档中的这些属性影响生成的请求方法和类型定义。
调用请求方法
生成了请求方法后，就可以在代码中调用接口了。
以下示例代码中，我们调用了 findUsers 接口，并输出返回的用户列表：
-- -------------------- ---- -------
------ - ---- - ---- --------------------
------ - --------- - ---- --------------
----- ---- - --- ------------------------------------
--------------------- - --------- ---
----- -------- ----------- ------------- -
--- -
----- ------ - ----- -------------------------- - ---- ------ ---
--------------------
- ----- --- -
-----------------
-
-
-----------Gear 类的构造函数需要传入接口的基础 URL，然后可以通过 register 方法将接口请求方法注册到 SDK 中。接口的调用通过 gear.run 方法实现。
小结
@apihawk/gear-sdk 可以帮助前端开发者自动生成前端所需的 TypeScript 类型定义和 API 请求方法，并自动实现参数校验、请求数据格式化、错误消息类型化等功能，减少了前端手写接口请求的工作量。
使用 @apihawk/gear-sdk 的步骤如下：
- 编写符合 OpenAPI 3.0 规范的接口文档。
- 在 Node.js 环境中通过 npm 安装 @apihawk/gear-sdk。
- 运行 Gear 命令并指定接口文档 yaml 文件路径和自动生成的 TypeScript 文件输出路径。
- 在代码中引入 SDK，并调用生成的 API 请求方法。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/112920