# @carlos-tzin/tzin 中文文档

规范地址：https://npmcn.com/package/%40carlos-tzin/tzin/

版本：1\.0\.8
npm 元数据更新时间：2026-10-01T02:48:26.092Z
中文译文更新时间：2026-11-09T15:50:22.006Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40carlos-tzin/tzin
原文对照：https://npmcn.com/package/%40carlos-tzin/tzin/?lang=original
项目主页：https://github.com/Tzinny-dev/tzin#readme
源码仓库：https://github.com/Tzinny-dev/tzin

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

- 包体积（解压后）：205 kB，76 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-08-25T20:23:42.920Z
- 最新版本发布：2026-10-01T02:48:25.900Z
- 近 30 天下载量：2323（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

合同第一类型脚本框架. 类型大小,有存在的实时通道,以及每个API的MCP服务器.

## 安装

```sh
npm install @carlos-tzin/tzin
```

也可以使用：`pnpm add @carlos-tzin/tzin`、`yarn add @carlos-tzin/tzin`、`bun add @carlos-tzin/tzin`

## README

# 锡因

**合同第一类型脚本框架. 类型,比例。 实时建造. 从第一天开始的人工智能.**

> `tzin` - 来自纳瓦特尔 _\- t_一个值得珍视和爱戴的荣誉后缀. 客户端和服务器之间的契约,声明一次.

[![CI](https://github.com/Tzinny-dev/tzin/actions/workflows/ci.yml/badge.svg)](https://github.com/Tzinny-dev/tzin/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@carlos-tzin/tzin)](https://www.npmjs.com/package/@carlos-tzin/tzin) [![Donate](https://img.shields.io/badge/Donate-PayPal-00457C?logo=paypal&logoColor=white)](https://paypal.me/carlostzin) [![Buy Me A Coffee](https://img.shields.io/badge/Buy_Me_A_Coffee-FFDD00?logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/tzinny)

**状况:稳定(1.0.x).** 核心工程端到端(见 [基准](https://npmcn.com/package/%40carlos-tzin/tzin/#readme-benchmarks)(三); 1.0.0 运出稳定的API,1.0.2 增加测试覆盖门,一个更大的CI 矩阵和一个公共类型清洁的表面.

```sh
npm install @carlos-tzin/tzin
```

或者脚手架 一个新的项目:

```sh
npx create-tzin my-app
```

## 文档

托管网站 : **[tzin.tzinny.com (中文(简体) )](https://tzin.tzinny.com/)**

-   **[API 参考](https://npmcn.com/package/%40carlos-tzin/tzin/docs/api-reference.md)** - 所有出口、类型和选择
-   **[架构指南](https://npmcn.com/package/%40carlos-tzin/tzin/docs/architecture.md)** - 请求管道、设计决定、内部
-   **[部署指南](https://npmcn.com/package/%40carlos-tzin/tzin/docs/deployment.md)** ——多克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克
-   **[路线图](https://npmcn.com/package/%40carlos-tzin/tzin/docs/roadmap.md)** ——未来特色

## 为什么是另一个框架?

TypeScript后端的地平面很拥挤

| 差距 | 证据 |
| --- | --- |
| 规模的推论类型崩溃 | 霍诺问题 [#2399号](https://github.com/honojs/hono/issues/2399), (中文(简体) ), [3869号](https://github.com/honojs/hono/issues/3869); 链路构建者强制每个应用程序一个巨大的表达式 |
| 轻量级框架中没有结构 | 霍诺问题 [4121号](https://github.com/honojs/hono/issues/4121) |
| TS 中不存在提取器 | 只有Rust的 Axum 才对处理器输入 |
| OpenAPI 是一个螺栓 | 每个 TS 框架在运行时或通过代码源将自己的chema DSL 翻译为 JSON Schema |
| AI 本地工具链 | 一个框架运送一个MCP服务器;窗口正在关闭 |

tzin的回答是: **宣布合同一次**免费得到其他一切.

```ts
import { t } from '@carlos-tzin/tzin'
import { contract, impl, createApp, listen } from '@carlos-tzin/tzin'

const getUser = contract({
  method: 'GET',
  path: '/users/:id',
  params: t.Object({ id: t.String() }),
  responses: {
    200: t.Object({ id: t.String(), name: t.String(), tags: t.Array(t.String()) }),
    404: t.Object({ error: t.String() }),
  },
})

export const getUserRoute = impl(getUser, async ({ params }) => {
  const user = await findUser(params.id)
  if (!user) throw new HttpError(404, 'user not found')
  return { status: 200, body: user }
})

const app = createApp([getUserRoute])
listen(app, 3000)
```

从该单项宣言:

-   **处理器输入被取出, 未猜测**数字 : `{ params }` 存在是因为您声明 它; 添加 `query`, (中文(简体) ), `body`, (中文(简体) ), `headers` 或者说 `cookies` 对合同,他们似乎, 每个请求都打入并经过验证.
-   **编译器执行您的回复**:返回一个不匹配的形状 已声明 `200` 身体是一个类型错误。 丢弃 `HttpError`地图到他们的状态.
-   **OpenAPI 3.1 免费**合同是JSON Schema(TypeBox),所以 `generateOpenApi(routes)` 不需要翻译层.

## 特征

### 核心

| 特性 | 导入 | 说明 |
| --- | --- | --- |
| 合同 | `@carlos-tzin/tzin` | 安全型API合同 |
| 路线 | `@carlos-tzin/tzin` | 与管理人员订立合同 |
| 中间软件 | `@carlos-tzin/tzin` | 洋葱型中相软件 |
| 编 | `@carlos-tzin/tzin` | 类型依赖性注射 |

### 运行时间

| 特性 | 导入 | 说明 |
| --- | --- | --- |
| 节点服务器 | `@carlos-tzin/tzin` | `listen(app, port)` |
| Bun 服务器 | `@carlos-tzin/tzin` | `serveBun(app, port)` |
| 工人 | `@carlos-tzin/tzin` | `toWorker(app)` |
| Dev 服务器 | 国 际 | `tzin dev` 热重装 |

### 实时

| 特性 | 导入 | 说明 |
| --- | --- | --- |
| 频道 | `@carlos-tzin/tzin` | SSE + POST 频道 |
| 出席情况 | `@carlos-tzin/tzin` | 凤凰式存在 |
| 网络安全套 | `@carlos-tzin/tzin/ws` | 本地 WS 频道 |
| 浏览器客户端 | `@carlos-tzin/tzin/client-browser` | 0dep 浏览器客户端 |

### 大赦国际

| 特性 | 导入 | 说明 |
| --- | --- | --- |
| MCP 服务器 | `@carlos-tzin/tzin` | 可流性 HTTP + stdio |
| 打开API | `@carlos-tzin/tzin` | 合同自动生成 |
| 法学硕士.txt | `@carlos-tzin/tzin` | 可读 API 索引 |

### 数据库

| 特性 | 导入 | 说明 |
| --- | --- | --- |
| 模型 | `@carlos-tzin/tzin/db` | 类型安全ORM |
| 查询构建器 | `@carlos-tzin/tzin/db` | 可链条查询 |
| 存储适配器 | `@carlos-tzin/tzin/db` | 可移动后端 |

### 认证

| 特性 | 导入 | 说明 |
| --- | --- | --- |
| 持有者认证 | `@carlos-tzin/tzin/auth` | JWT 验证 |
| 可选认证 | `@carlos-tzin/tzin/auth` | 非限制性 JWT |
| API 密钥 | `@carlos-tzin/tzin/auth` | 基于信头的认证 |
| JWT 倾斜 | `@carlos-tzin/tzin/auth` | 签名/核查 |

### 工作

| 特性 | 导入 | 说明 |
| --- | --- | --- |
| 定义工作 | `@carlos-tzin/tzin/jobs` | 背景任务 |
| 队列 | `@carlos-tzin/tzin/jobs` | 任务队列 |
| 重试 | `@carlos-tzin/tzin/jobs` | 失败时自动重试 |

### 日志

| 特性 | 导入 | 说明 |
| --- | --- | --- |
| 锁定器 | `@carlos-tzin/tzin/log` | 结构化伐木 |
| 儿童伐木工 | `@carlos-tzin/tzin/log` | 范围上下文 |
| 美丽/JSON | `@carlos-tzin/tzin/log` | 可配置输出 |

### 测试

| 特性 | 导入 | 说明 |
| --- | --- | --- |
| 测试客户端 | `@carlos-tzin/tzin/test` | API 测试 |
| Schema 验证 | `@carlos-tzin/tzin/test` | 类型断言 |
| 模拟数据 | `@carlos-tzin/tzin/test` | 生成模拟 |

## 快速启动

### 1\. 脚手架

```bash
npx create-tzin my-api
cd my-api
```

### 2\. 合同的定义

```ts
// src/routes/users.ts
import { t, contract, impl } from '@carlos-tzin/tzin'

export const getUser = contract({
  method: 'GET',
  path: '/users/:id',
  params: t.Object({ id: t.String() }),
  responses: {
    200: t.Object({ id: t.String(), name: t.String() }),
    404: t.Object({ error: t.String() }),
  },
})

export const getUserRoute = impl(getUser, async ({ params }) => {
  return { status: 200, body: { id: params.id, name: 'Ada' } }
})
```

### 3\. 创建应用程序

```ts
// src/app.ts
import { createApp } from '@carlos-tzin/tzin'
import { getUserRoute } from './routes/users.js'

export const app = createApp([getUserRoute], {
  openapi: true,
  mcp: true,
  meta: { title: 'My API', version: '1.0.0' },
})
```

### 4\. 运行

```bash
npm run dev    # tzin dev  -> dev server at http://localhost:3000
npm run build  # tzin build -> production build
```

这个 `tzin` 带包裹的二进制飞船,所以这些脚本在之后工作 `npm install`没有 本地安装, 通过 npm exec 运行 :

```bash
npx --package @carlos-tzin/tzin tzin dev
```

## 国 际

```bash
tzin dev [--port N]                                # dev server with hot reload
tzin build                                         # build for production
tzin deploy --target node|workers [--pack] [--docker <tag> [--push]]  # deploy
tzin generate route <name>                         # scaffold a route
tzin generate middleware <name>                    # scaffold middleware
tzin generate test <name>                          # scaffold a test
```

## 基准

100个有不同计划的最终点,由 `tsc --extendedDiagnostics`数字 :

| N路线 | tzin:类型 | Hono: 类型 | tzin:即时处理 | 霍诺:即时报道 |
| --- | --- | --- | --- | --- |
| 20国 | 4 851个 | 72 368 (中文(简体) ) | 22 472个 | 156 054 (中文(简体) ) |
| 100个 | 15 779个 | 111,952 (中文(简体) ) | 93,128 (中文(简体) ) | 240k (韩语) |
| 三百块 | 43 099 (中文(简体) ) | 210 912 (中文(简体) ) | 270k (韩语) | 590k (中文(简体) ) |

天津生长 **严格线性** (~130个类型/端点.

### 运行时间吞吐量

| 框架 | 数 | 第99页 |
| --- | --- | --- |
| 原始节点:http(地板) | ~42k (韩语) | 2 -- 3ms (2 -- 3ms) |
| 哈诺 | ~34–36k (英语) | 3分钟 |
| 锡因 | ~30–31k (英语) | 6分钟 |
| 表达式 | ~ 15k 时 | 7分钟 |

## 实例

| 示例 | 运行时间 | 显示什么 |
| --- | --- | --- |
| `examples/node-demo.ts` | 节点 | 有合同的最小 HTTP 服务器 |
| `examples/bun-demo.ts` | 阿宝 | Bun.serve 有验证功能 |
| `examples/todo-api.ts` | 节点 | 完整 CRUD: 认证中间软件, DI, OpenAPI, MCP |
| `examples/mcp-demo.ts` | 节点 | 通过 stdio 的 MCP 服务器 |
| `examples/ws-demo.ts` | 阿宝 | 有存在的 WebSocket 频道 |
| `examples/workers-quickstart/` | 工人 | 复制- paste wrangler 项目: DO + 通道 + 存在 |
| `examples/workers-quickstart.md` | 工人 | 相同的项目, 按文件解释 |

## 设计原则

-   **合同第一,统一登记.** 一条路由是数据(`contract({...})`链接 在建造链。 推论成本保持每个终点的O(1).
-   **JSON斯克马本地人.** TypeBox schemas 二相为OpenAPI,零转换.
-   **网络标准运行时间.** `Request` 内, `Response` 退出;适配器保持瘦弱.
-   **解开者战胜魔法.** 交易员得到的正是合同申报的内容.
-   **错误是控制流 .** 丢入打出的错误; 响应联盟已经知道 .
-   **Light DI 不举行仪式.** `provide(key, value)` 在应用级种子类型中 每个请求的上下文中的单通数——处理者 `ctx.require(db)`。 。 。 .

## 发展

```sh
npm install
npm test          # vitest — runtime + end-to-end client + type assertions
npm run typecheck # strict tsc across src/test/bench fixtures
```

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40carlos-tzin/tzin/LICENSE)。 。 。 .

## 常见问题

### @carlos-tzin/tzin 是什么？

合同第一类型脚本框架\. 类型大小,有存在的实时通道,以及每个API的MCP服务器\.

### 如何安装 @carlos-tzin/tzin？

在项目目录运行 npm install @carlos-tzin/tzin，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 tzin，可以用 npx tzin 直接运行。

### @carlos-tzin/tzin 支持 TypeScript 吗？

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

### @carlos-tzin/tzin 支持 ESM 还是 CommonJS？

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

### @carlos-tzin/tzin 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @carlos-tzin/tzin 可以商用吗？

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

### @carlos-tzin/tzin 的下载量有多少？

根据 npm 官方下载统计，@carlos-tzin/tzin 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,323 次，日均约 77 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @carlos-tzin/tzin 还在维护吗？

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