# @mittwald/api-client 中文文档

规范地址：https://npmcn.com/package/%40mittwald/api-client/

版本：4\.509\.0
npm 元数据更新时间：2026-11-01T19:08:30.728Z
中文译文更新时间：2026-11-01T22:21:16.324Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40mittwald/api-client
原文对照：https://npmcn.com/package/%40mittwald/api-client/?lang=original
项目主页：https://developer.mittwald.de/
源码仓库：https://github.com/mittwald/api-client-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：8.5 MB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：@mittwald/react-use-promise ^2\.6\.0 \|\| ^3\.0\.0 \|\| ^4\.0\.0
- 首次发布：2023-06-07T11:50:30.696Z
- 最新版本发布：2026-11-01T19:08:30.391Z
- 已发布版本数：803（近 12 个月 375 个）

## 中文简介

为mittwald API自动生成客户端

## 安装

```sh
npm install @mittwald/api-client
```

也可以使用：`pnpm add @mittwald/api-client`、`yarn add @mittwald/api-client`、`bun add @mittwald/api-client`

## README

# mitwald API JavaScript客户端

这个包包含一个JavaScript客户端（大部分是自动生成的） mittwald API。

## 许可证

版权所有：Mittwald CM Service GmbH & Co. KG

本项目（以及其中的所有NPM软件包）在MIT许可下获得许可； 看到 [许可证](https://npmcn.com/package/LICENSE) 文件查看详细信息。

## 目录表

-   [安装](https://npmcn.com/package/%40mittwald/api-client/#readme-installing)
-   [使用](https://npmcn.com/package/%40mittwald/api-client/#readme-usage)
    -   [使用v3-next客户机](https://npmcn.com/package/%40mittwald/api-client/#readme-using-the-v3-next-client)
    -   [设置请求参数](https://npmcn.com/package/%40mittwald/api-client/#readme-setting-request-parameters)
        -   [路径参数](https://npmcn.com/package/%40mittwald/api-client/#readme-path-parameters)
        -   [报头、查询参数和请求正文](https://npmcn.com/package/%40mittwald/api-client/#readme-headers-query-parameters-and-request-body)
        -   [日期和时间值](https://npmcn.com/package/%40mittwald/api-client/#readme-date-and-time-values)
-   [例子](https://npmcn.com/package/%40mittwald/api-client/#readme-example)
-   [React中的用法](https://npmcn.com/package/%40mittwald/api-client/#readme-usage-in-react)
    -   [安装](https://npmcn.com/package/%40mittwald/api-client/#readme-installation)
    -   [设置](https://npmcn.com/package/%40mittwald/api-client/#readme-setup)
    -   [使用](https://npmcn.com/package/%40mittwald/api-client/#readme-usage-1)
    -   [例子](https://npmcn.com/package/%40mittwald/api-client/#readme-example-1)
-   [API文档](https://npmcn.com/package/%40mittwald/api-client/#readme-api-documentation)
-   [访问底层Axios实例](https://npmcn.com/package/%40mittwald/api-client/#readme-accessing-the-underlying-axios-instance)
    -   [添加自定义HTTP标头](https://npmcn.com/package/%40mittwald/api-client/#readme-adding-custom-http-headers)
    -   [拦截请求或响应](https://npmcn.com/package/%40mittwald/api-client/#readme-intercepting-requests-or-responses)
-   [TypeScript的用法](https://npmcn.com/package/%40mittwald/api-client/#readme-usage-with-typescript)
    -   [导入类型](https://npmcn.com/package/%40mittwald/api-client/#readme-importing-types)
-   [从包版本V2迁移到V3](https://npmcn.com/package/%40mittwald/api-client/#readme-migrating-from-package-version-v2-to-v3)

## 安装

你可以从普通的NPM注册表中安装这个包：

```shell
yarn add @mittwald/api-client
```

## 使用

导入客户端：

```typescript
import { MittwaldAPIV2Client } from "@mittwald/api-client";
```

要创建客户端实例，可以使用以下工厂方法之一 不同类型的认证：

1.  `MittwaldAPIClient.newUnauthenticated()`
2.  `MittwaldAPIClient.newWithToken(apiToken: string)` (推荐)
3.  `MittwaldAPIClient.newWithCredentials(email: string, password: string)` ( 实际上在后台执行登录，从而返回一个promise)

看看我们的 [API的介绍](https://developer.mittwald.de/docs/v2/api/intro) 了解更多信息 如何获取API令牌以及如何开始使用API。

### 使用v3-next客户机

默认的导入路径公开了v2客户机。使用生产 `v3-next` 客户端，从 `@mittwald/api-client/v3-next` 子路径:

```typescript
import { MittwaldAPIClient } from "@mittwald/api-client/v3-next";

const mittwaldApi = MittwaldAPIClient.newWithToken("your-access-token");
```

React客户端可以从对应的React子路径中获得：

```typescript
import { MittwaldAPIClientReact } from "@mittwald/api-client/v3-next/react";
```

TypeScript的请求和响应类型通过 `MittwaldAPIV3Next` 名称空间:

```typescript
import { MittwaldAPIV3Next } from "@mittwald/api-client/v3-next";
```

这使用了已发布的、非开发的 `v3-next` 客户端。这个包裹没有 公开 `@mittwald/api-client/v3-next-dev` 进口路径;这个 `v3-next-dev` OpenAPI规范仅用于生成开发构建。

### 设置请求参数

API请求可能需要这些类型的参数：

-   路径参数
-   头
-   查询参数
-   请求体

#### 路径参数

路径参数是URL路径的可变部分。他们通常习惯于 指向集合中的特定资源，例如已标识的项目 通过ID。一个URL可以有几个路径参数，每个参数用花括号表示 `{ }`.

```
/v2/projects/{projectId}
```

路径参数 **是必需的** 并且必须在请求中直接定义 对象。

```javascript
// Setting the projectId path parameters
const project = await mittwaldApi.project.getProject({
  projectId: "p-xxxxx",
});
```

#### 报头、查询参数和请求正文

根据不同的操作，还需要配置额外的参数，例如 `queryParameters` （URL查询参数）， `headers` （HTTP报头），以及 `data` (请求主体)。

操作及其参数记录在 [API文档](https://developer.mittwald.de/reference/v2/).

当使用TypeScript时，所有的参数模式都由请求类型反映， 因此，当请求与模式不匹配时，您将获得编译错误。

```javascript
const response = await mittwaldApi.category.operation({
  // path parameters
  pathParameter1: "param1",
  pathParameter2: "param2",
  // parameters in header
  headers: {
    "x-header": "header",
  },
  // query parameters
  queryParameters: {
    queryParameter1: "queryParam1",
    queryParameter2: "queryParam2",
  },
  // JSON object in request body
  data: {
    data1: "data1",
    data2: "data2",
  },
});
```

#### 日期和时间值

只要API需要日期和时间（API中的ISO 8601字符串） 文档)，您可以自己传递该字符串，也可以简单地传递 JavaScript `Date`. `Date` 值被转换成ISO 8601格式 发送-在请求体（在任何嵌套深度），在查询参数，路径 参数和头文件。

```typescript
await mittwaldApi.contract.terminateContractItem({
  contractId: "contract-id",
  contractItemId: "contract-item-id",
  data: {
    terminationTargetDate: new Date("2024-12-10"),
  },
});
```

注意，这适用于 `date-time` 只值。只值 （`YYYY-MM-DD`)仍然需要作为字符串传递，并且响应总是包含 字符串,从来没有 `Date` 对象。

## 例子

```typescript
import { MittwaldAPIV2Client } from "@mittwald/api-client";

const mittwaldApi = MittwaldAPIClient.newWithToken("your-access-token");

const projects = await mittwaldApi.project.listProjects();
```

## React中的用法

这个包还提供了一个在React组件中使用的客户端。它 使用 [`@mittwald/react-use-promise`](https://www.npmjs.com/package/@mittwald/react-use-promise) 将异步API函数封装到AsyncResources中。更多的细节 关于如何使用AsyncResources，请参阅 [包的文档](https://www.npmjs.com/package/@mittwald/react-use-promise#terminology).

### 安装

要使用React客户端，您必须安装附加的 `@mittwald/react-use-promise` 包:

```shell
yarn add @mittwald/react-use-promise
```

### 设置

要创建一个React客户端实例，首先需要一个regular的实例 (当)客户机。然后你可以使用 `.fromBaseClient(api)` 方法 构建React客户端。

```javascript
const api = MittwaldAPIV2Client.newUnauthenticated();
const apiReact = MittwaldAPIV2ClientReact.fromBaseClient(api);
```

### 使用

React客户端对常规客户端的每个GET方法都有一个等价的GET方法。 返回可用于获取API的AsyncResource的方法 响应。

如果响应不是OK（状态200），则 `ApiClientError` 会被扔。 错误可以通过使用错误边界来处理。看到 [错误处理部分](https://www.npmjs.com/package/@mittwald/react-use-promise#error-handling) 了解更多详情。

### 例子

```javascript
import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { MittwaldAPIV2ClientReact } from "@mittwald/api-client/react";

const api = MittwaldAPIV2Client.newUnauthenticated();
const apiReact = MittwaldAPIV2ClientReact.fromBaseClient(api);

const ProjectsList = () => {
  // apiReact.project.listProjects() returns an AsyncResource that can be "used"
  const projects = apiReact.project.listProjects().use({
    autoRefresh: {
      seconds: 30,
    },
  });

  return (
    <ul>
      {projects.map((p) => (
        <li key={p.id}>{p.description}</li>
      ))}
    </ul>
  );
};
```

## API文档

API文档可以在 [https://api.mittwald.de/v2/docs/](https://api.mittwald.de/v2/docs/)． 你可以 在每个操作的右侧找到操作ID。

## 访问底层Axios实例

客户端使用流行的 [Axios HTTP客户端](https://axios-http.com/) 下 罩。您可以使用客户机访问Axios实例 `axios` 财产。

### 添加自定义HTTP标头

要向所有请求添加自定义HTTP头，您可以使用Axios的 `defaults.headers` 属性:

```typescript
client.axios.defaults.headers["User-Agent"] = `your-tool/v1.2.3`;
```

### 拦截请求或响应

来拦截请求或响应，您可以使用 [Axios的拦截器](https://axios-http.com/docs/interceptors).

## TypeScript的用法

中导入所有响应和请求类型 `MittwaldAPIV2` 名称空间。

### 引用请求/响应类型

```typescript
import { MittwaldAPIV2 } from "@mittwald/api-client";

type ProjectData = MittwaldAPIV2.Operations.ProjectGetProject.ResponseData;

// Reference "non-200" response type
type ProjectNotFoundData =
  MittwaldAPIV2.Operations.ProjectGetProject.ResponseData<404>;

type CreateProjectData =
  MittwaldAPIV2.Operations.ProjectCreateProject.RequestData;
```

## 从包版本V2迁移到V3

**此指令考虑从 _包_ version V2到V3 在请求调用的呼叫签名中有重大更改。API本身有 没有改变，仍然是版本2。**

路径参数是请求的主要组成部分，因此不应该是 “隐藏”在请求配置对象中。在V3中，请求的API 配置对象发生变化，需要重新设置路径参数 直接在请求对象的根级别。

```javascript
// V2
mittwaldApi.project.getProject({
  pathParameters: {
    projectId: "p-xxxxx",
  },
});

// V3
mittwaldApi.project.getProject({
  projectId: "p-xxxxx",
});
```

## 常见问题

### @mittwald/api-client 是什么？

为mittwald API自动生成客户端

### 如何安装 @mittwald/api-client？

在项目目录运行 npm install @mittwald/api-client，或使用 pnpm add / yarn add / bun add。

### @mittwald/api-client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @mittwald/api-client 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @mittwald/api-client 可以商用吗？

@mittwald/api-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @mittwald/api-client 还在维护吗？

最新版本 4\.509\.0 发布于 2026/11/02（1 天前）；至今共发布 803 个版本，其中过去 12 个月发布了 375 个；首次发布于 2023/06/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。