# ts-interface-checker 中文文档

规范地址：https://npmcn.com/package/ts-interface-checker/

版本：1\.0\.2
npm 元数据更新时间：2023-07-22T22:36:13.865Z
中文译文更新时间：2026-11-05T16:37:40.037Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/ts-interface-checker
原文对照：https://npmcn.com/package/ts-interface-checker/?lang=original
项目主页：https://github.com/gristlabs/ts-interface-checker#readme
源码仓库：https://github.com/gristlabs/ts-interface-checker

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

- 包体积（解压后）：83.3 kB，12 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2018-01-11T20:23:46.109Z
- 最新版本发布：2021-10-11T22:57:41.129Z
- 近 30 天下载量：173973630（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 0 个）

## 中文简介

用 TypeScript 接口验证数据的运行时库

## 安装

```sh
npm install ts-interface-checker
```

也可以使用：`pnpm add ts-interface-checker`、`yarn add ts-interface-checker`、`bun add ts-interface-checker`

## README

# ts 界面检查器

[![Build Status](https://travis-ci.org/gristlabs/ts-interface-checker.svg?branch=master)](https://travis-ci.org/gristlabs/ts-interface-checker) [![npm version](https://badge.fury.io/js/ts-interface-checker.svg)](https://badge.fury.io/js/ts-interface-checker)

> 运行时库可以对照TypeScript接口验证数据.

此软件包是运行时对校验器的支持 [ts- 界面构建器](https://github.com/gristlabs/ts-interface-builder)。 。 。 . 它允许验证数据, 例如解析收到的 JSON 对象 覆盖网络,或解析 JSON 或 YAML 文件,以检查它们是否满足 TypeScript 接口, 并生成信息性错误消息 .

## 安装

```bash
npm install --save-dev ts-interface-builder
npm install --save ts-interface-checker
```

## 使用量

假设您有定义接口的 TypeScript 文件 :

```typescript
// foo.ts
interface Square {
  size: number;
  color?: string;
}
```

第一步是生成一些运行时间检查代码:

```bash
`npm bin`/ts-interface-builder foo.ts
```

它会产生这样的文件:

```typescript
// foo-ti.js
import * as t from "ts-interface-checker";

export const Square = t.iface([], {
  "size": "number",
  "color": t.opt("string"),
});
...
```

现在运行时, 检查一个值是否满足了 Square 界面 :

```typescript
import fooTI from "./foo-ti";
import {createCheckers} from "ts-interface-checker";

const {Square} = createCheckers(fooTI);

Square.check({size: 1});                  // OK
Square.check({size: 1, color: "green"});  // OK
Square.check({color: "green"});           // Fails with "value.size is missing"
Square.check({size: 4, color: 5});        // Fails with "value.color is not a string"
```

请注意: `ts-interface-builder` 仅是建时步骤需要 `ts-interface-checker` 运行时需要。 这就是为什么建议Npm -inll 前一个使用 `--save-dev` 旗并使用 `--save`。 。 。 .

## 检查方法调用

如果与方法有接口,可以验证方法调用参数并返回值:

```typescript
// greet.ts
interface Greeter {
  greet(name: string): string;
}
```

在生成运行时代码后,您现在可以检查诸如:

```typescript
import greetTI from "./greet-ti";
import {createCheckers} from "ts-interface-checker";

const {Greeter} = createCheckers(greetTI);

Greeter.methodArgs("greet").check(["Bob"]);     // OK
Greeter.methodArgs("greet").check([17]);        // Fails with "value.name is not a string"
Greeter.methodArgs("greet").check([]);          // Fails with "value.name is missing"

Greeter.methodResult("greet").check("hello");   // OK
Greeter.methodResult("greet").check(null);      // Fails with "value is not a string"
```

## 类型套房

如果一个类型指另一个文件中定义的类型,则需要告诉界面检查器有关 调用时所有类型名称 `createCheckers()`. 例如给定

```typescript
// color.ts
export type Color = RGB | string;
export type RGB = [number, number, number];
```

```typescript
// shape.ts
import {Color} from "./color";
export interface Square {
  size: number;
  color?: Color;
}
```

生成的文件 `color-ti.ts` 财务报告和审定财务报表 `shape-ti.ts` 不自动提及对方,但 期待你把他们联系起来 `createCheckers()` 电话 :

```typescript
import color from "./color-ti";
import shape from "./shape-ti";
import {createCheckers} from "ts-interface-checker";

const {Square} = createCheckers(shape, color);    // Pass in all required type suites.

Square.check({size: 1, color: [255,255,255]});
```

## 严格检查

您可以检查该数据中没有额外的属性 。 请注意,一般不建议 它防止了后向相容性:如果将新属性添加到接口中,那么会更旧 严格检查的代码不会接受.

以上述例子如下:

```typescript
Square.strictCheck({size: 1, color: [255,255,255], bg: "blue"});    // Fails with value.bg is extraneous
Square.strictCheck({size: 1, color: [255,255,255,0.5]});            // Fails with ...value.color[3] is extraneous
```

## 类型警卫

标准 `Checker` 对象进行类型检查逻辑,但无法制作类型脚本 编译器意识到对象 `unknown` 类型执行某个接口.

基本代码 :

```typescript
const unk: unknown = {size: 1, color: "green"};
// Type is unknown, so TypeScript will not let you access the members.
console.log(unk.size); // Error: "Object is of type 'unknown'"
```

与一个 `Checker` 备注:

```typescript
import fooTI from "./foo-ti";
import {createCheckers} from "ts-interface-checker";

const {Square} = createCheckers(fooTI);

const unk: unknown = {size: 1, color: "green"};

if (Square.test(unk)) {
  // unk does implement Square, but TypeScript is not aware of it.
  console.log(unk.size); // Error: "Object is of type 'unknown'"
}
```

启用现有类型守护功能 `test`,以及 `strictTest` 函数, `Checker` 对象应被投放到 `CheckerT<>` 使用合适的类型.

使用 `CheckerT<>`数字 :

```typescript
import {Square} from "./foo";
import fooTI from "./foo-ti";
import {createCheckers, CheckerT} from "ts-interface-checker";

const {Square} = createCheckers(fooTI) as {Square: CheckerT<Square>};

const unk: unknown = {size: 1, color: "green"};

if (Square.test(unk)) {
  // TypeScript is now aware that unk implements Square, and allows member access.
  console.log(unk.size);
}
```

## 类型断言

`CheckerT<>` 最终将使用 `check` 财务报告和审定财务报表 `strictCheck` 函数, 然而,这个功能还没有在TypeScript中完全工作.

## 常见问题

### ts-interface-checker 是什么？

用 TypeScript 接口验证数据的运行时库

### 如何安装 ts-interface-checker？

在项目目录运行 npm install ts-interface-checker，或使用 pnpm add / yarn add / bun add。

### ts-interface-checker 支持 TypeScript 吗？

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

### ts-interface-checker 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### ts-interface-checker 可以商用吗？

ts-interface-checker 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### ts-interface-checker 的下载量有多少？

根据 npm 官方下载统计，ts-interface-checker 在 2026/10/05 – 2026/11/03 这 30 天内被下载 173,973,630 次，日均约 5,799,121 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### ts-interface-checker 还在维护吗？

最新版本 1\.0\.2 发布于 2021/10/12（5 年前）；至今共发布 19 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/01/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。