# @brickkit/core 中文文档

规范地址：https://npmcn.com/package/%40brickkit/core/

版本：0\.13\.1
npm 元数据更新时间：2026-11-07T11:49:09.517Z
中文译文更新时间：2026-11-08T15:03:43.384Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40brickkit/core
原文对照：https://npmcn.com/package/%40brickkit/core/?lang=original
项目主页：https://brickkit.dev/
源码仓库：https://github.com/get-brickkit/brick

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

- 包体积（解压后）：1.1 MB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：drizzle-kit ^0\.31\.0，drizzle-orm ^0\.45\.2，@tanstack/query-core ^5\.0\.0
- 首次发布：2026-10-07T17:38:13.978Z
- 最新版本发布：2026-11-07T11:49:09.189Z
- 近 30 天下载量：4845（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

Brick-TS 框架的核心引擎原始

## 安装

```sh
npm install @brickkit/core
```

也可以使用：`pnpm add @brickkit/core`、`yarn add @brickkit/core`、`bun add @brickkit/core`

## README

# @ brickkit/ 核心

Brick-TS框架的服务、行动、资源和数据库。 您用 TypeBox 计划定义打字服务, 用挂载 `brick()`,并获得一个带有 OpenAPI 输出和输入客户端的 Elysia HTTP 服务器.

晚点要买一分钱 仅装箱的API是懒惰的,因此套件在严格的节点无害环境管理下也干净地进口.

```sh
bun add @brickkit/core
```

## 定义服务

创建一个服务,注册一个行动,并服务它。 每个动作都暴露出一条路线: `POST /api/{service}/{action}` 默认.

```ts
import { brick, defineAction, defineService } from "@brickkit/core";

const healthService = defineService("system");
const ping = defineAction({
  name: "ping",
  execute: async () => ({ status: "ok" }),
});
healthService.action(ping);

const app = brick({ services: [healthService] });
app.listen(4000);
```

设定 `method: "GET"` 用于完成阅读的动作配置 `path` 以替换默认路径。 添加 `input` 财务报告和审定财务报表 `output` TypeBox 策略在边界验证. 添加 `authorize` 要求用户;没有它,动作是公开的。 要求用同样的管道采取行动 `action.run(input, ctx)` 或者说 `service.getAction("ping")`。 。 。 .

`brick()` 还接受 `prefix`, (中文(简体) ), `title`,以及 `version`。 。 。 . `generateOpenApiSpec({ services, prefix })` 返回不启动服务器的 OpenAPI 3.1 文档.

## 出口

| 路径 | 它所持有的 |
| --- | --- |
| `@brickkit/core` | `brick`, (中文(简体) ), `defineService`, (中文(简体) ), `defineAction`, (中文(简体) ), `defineDatabase`, MCP 软件 |
| `@brickkit/core/client` | `createBrickClient`, Eden 风格的浏览器客户端 |
| `@brickkit/core/pg` | Postgres Drizzle 桌帮手, 例如 : `pgTable` |

数据库使用 Drizzle 表格通过 `defineDatabase({ engine, tables, url })` 与 `"sqlite"` 或者说 `"postgres"` 发动机。 数据库设置在 `DATABASES.md`。 。 。 .

```sh
bun add @brickkit/core drizzle-orm postgres
```

```ts
import { defineDatabase } from "@brickkit/core";
import { pgTable, text } from "@brickkit/core/pg";

const pages = pgTable("pages", {
  id: text("id").primaryKey(),
  title: text("title").notNull(),
});

export const db = defineDatabase({
  engine: "postgres",
  tables: { pages },
  url: process.env.DATABASE_URL!,
});
```

## 已打入客户端

`@brickkit/core/client` (亦从包根再出)提供从您合同类型推断出的一个Eden-style HTTP客户端——没有OpenAPI代码:

为您的默认导出应用程序配置了 Brick Vite 插件, Vite 创建 `_brick/contract.ts` 自动 :

```ts
import { createBrickClient } from "@brickkit/core/client";
import { contract } from "../_brick/contract";

const api = createBrickClient({ baseUrl: "http://localhost:4000", contract });
const pages = await api.page.list({ limit: 10 });
```

生成的合同包含浏览器安全路由元数据并推断出输入/输出/错误类型. 它尊重自定义的动作路径和方法,编码路径参数,并从剩余的有效载荷中去除. 没有后端处理器被捆绑. 见CLI读取和 [已键入客户端指南](https://brickkit.dev/docs/typed-client) 用于 Vite 设置和错误处理.

## MCP工具

定义诸如动作等工具,包括输入/输出计划和内置元数据:

```ts
import {
  defineService,
  createMcpRegistry,
  createMcpHandler,
  t,
} from "@brickkit/core";

const crm = defineService("crm");
const whoami = crm.tool({
  name: "crm_whoami",
  title: "View Connected CRM Account",
  annotations: { readOnlyHint: true },
  input: t.Object({}),
  output: t.String(),
  authorize: ({ user }) => !!user?.id,
  execute: ({ ctx }) => ctx.user.id,
});

const registry = createMcpRegistry({ services: [crm] });
registry.listTools();
await registry.callTool("crm_whoami", {}, { user: { id: "user_1" } });

const handleMcp = createMcpHandler({
  registry,
  serverInfo: { name: "crm", version: "1.0.0" },
});
// After your app authenticates a request:
// return handleMcp(request, { user: { id: verifiedSubject } });
```

工具使用动作验证,授权,和服务上下文. 它们与 HTTP 动作分开存储, 默认时远离路由和 OpenAPI, 包括其服务传递给 `brick()`添加 `http: true` 用于工具定义,或以 `crm.action(whoami)`也通过HTTP曝光.

登记处接受 `services` 和/或明示 `tools` 数组,拒绝重复名称,直接从定义中读取注释。 处理者是无国籍的POST JSON-RPC帮助者,负责初始化、打平、工具/清单和工具/呼叫;通知收到空的202答复。 您的应用程序中仍然保留着认证和安装。 它的默认协议版本是 `2025-06-18`,然后 [MCP 工具规格](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)。 。 。 .

资料来源: [https://github.com/get-brickkit/brick 页面存档备份,存于互联网档案馆](https://github.com/get-brickkit/brick)。 。 。 .

## 追踪

Brick 记录 HTTP, 动作, 和 RPC 跨度 `@opentelemetry/api`. 追查 默认关闭。 每个应用打开 `telemetry` 选项和注册 一个OpenTeleometry追踪器提供商,所以时间跨度有去处:

```ts
import { brick } from "@brickkit/core";

const app = brick({ services: [pagesService], telemetry: true });
```

每个请求都成为服务器跨度. 每个动作、远程呼叫和 SQL 语句 期间制造的 成为了儿童期。 SQLite 语句在 `bun:sqlite` 驱动程序,以及 postgres.js 查询本身的语句。 失败 记录在产生它们的间距: 服务器断层( 5xx) 标记间距 被错误的例外事件,而客户端错误( 4xx) 只添加 `brick.error.code`。没有注册的供应商,则无期限.

登记了W3C跟踪上下文的传播器后,请求继续发出 从它的追踪 `traceparent` 标题, 反应包含 `traceparent` 回来 没有 `x-trace-id` 标题, Brick 返回请求的微量标识为 `x-trace-id`。声明案文记录为 `db.statement`; 绑定参数 数值不是.

直接在应用程序上注册的路由,例如安装在 `app.all()`,坐在外部动作和终点。 包装他们的处理器 `traceRoute(route, handler)` 给他们一个服务器跨度。 处理者收到 `request`, (中文(简体) ), `headers`, (中文(简体) ), `set`, (中文(简体) ), `params`,以及 `query`; 从 `request`。 。 。 . `traceRoute` \* 每当追踪提供者注册时,记录.

```ts
import { traceRoute } from "@brickkit/core";

app.all(
  "/api/auth/*",
  traceRoute("/api/auth/*", ({ request }) => auth.handler(request)),
);
```

`brick dev` 注册一个提供者,并将跨度发送到它的仪表板,所以应用程序 有必要 `telemetry: true` 我也一样.

## 活动

生成 CRUD 写入可以记录与行相同的交易中的事件,并且 Brick在犯罪后把它交给听众 重试失败者. 添加 `outboxTable()` 到数据库,定义一个听众,然后传递给 `brick()`。 。 。 .

```ts
import { brick, defineListener, outboxTable } from "@brickkit/core";

export const outbox = outboxTable("postgres");

const welcome = defineListener({
  name: "welcome-email",
  on: "user.create",
  run: async ({ payload, deliveryId }) => {
    await mailer.sendWelcome(payload.row.email, { idempotencyKey: deliveryId });
  },
});

export default brick({ services, events: { listeners: [welcome] } });
```

交付至少一次,所以使用 `deliveryId` 作为一等钥匙。 应用程序 无 `events` 表现得跟以前一样 见 [活动指南](https://brickkit.dev/docs/events)。 。 。 .

## TanStack 查询选项

安装 `@tanstack/query-core` v5 与您框架的 TanStack 查询软件包并列 . 导入浏览器条目和生成的合同 :

```tsx
import { createBrickQueryClient } from "@brickkit/core/tanstack-query";
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { contract } from "./_brick/contract";

const api = createBrickQueryClient({
  baseUrl: "https://api.example.com",
  contract,
});

function Pages() {
  const queryClient = useQueryClient();
  const pages = useQuery({
    ...api.page.list.queryOptions({ input: { limit: 20 } }),
    staleTime: 30_000,
    select: (result) => result.items,
  });
  const create = useMutation({
    ...api.page.create.mutationOptions(),
    onSuccess: () =>
      queryClient.invalidateQueries({ queryKey: api.page.list.queryKey() }),
  });
  // Render pages.data and call create.mutate with the action's input.
}
```

直接电话,例如 `api.page.list(input)` 还在工作。 两位助手都在场 每一个行动。 选择它们由您如何使用动作, 独立于它的 HTTP 方法。 POST 查询仍然发送 POST; 自定义路由、插件动作和编码 路径参数使用生成的元数据.

`queryOptions({ input, request })` 返回键入 `queryKey` 财务报告和审定财务报表 `queryFn`。 。 。 . 传播本地选项, 如 `placeholderData`, (中文(简体) ), `select`,以及 `staleTime` 旁边 那些财产. `request` 接受普通客户头,信号,以及 暂停 。 查询取消到达取回, 请求取消也保留 活动. `mutationOptions({ request })` 返回时 `mutationKey` 财务报告和审定财务报表 `mutationFn`· ; 变异变量是动作输入.

`queryKey({ input })` 处理一项投入; `queryKey()` 匹配所有输入 转到 `invalidateQueries`键包括服务器 URL,前缀, 命名空间路径、合同方法和路由标识,以及输入。 信头不是密钥的一部分 。 清除或分区 当认证用户更改时, 您的查询缓存 .

同样的选项与 `queryClient.fetchQuery`, (中文(简体) ), `prefetchQuery`,以及 `ensureQueryData`。例如,一个 TanStack 路由器加载器可以返回 `context.queryClient.ensureQueryData(api.page.get.queryOptions({ input: { id: params.id } }))`。 。 。 . 密钥返回 `queryOptions` 和具体投入 `queryKey` 也推断 缓存输出类型 `getQueryData`。 。 。 .

对于 TanStack DB , 将选项传递到 `queryCollectionOptions` 并供应你的 拥有 `queryClient`, (中文(简体) ), `getKey`,以及任意 `select` 需要转换成相接反应 排成一行。 收藏身份、画相、乐观写作和同步 突变后仍为应用责任. 页面编辑器演示 标准查询突变加其他收藏的明确收藏回溯 消费者.

## 常见问题

### @brickkit/core 是什么？

Brick-TS 框架的核心引擎原始

### 如何安装 @brickkit/core？

在项目目录运行 npm install @brickkit/core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：drizzle-orm（^0\.45\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @brickkit/core 支持 TypeScript 吗？

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

### @brickkit/core 支持 ESM 还是 CommonJS？

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

### @brickkit/core 可以商用吗？

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

### @brickkit/core 的下载量有多少？

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

### @brickkit/core 还在维护吗？

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