@ brickkit/ 核心
Brick-TS框架的服务、行动、资源和数据库。 您用 TypeBox 计划定义打字服务, 用挂载 brick(),并获得一个带有 OpenAPI 输出和输入客户端的 Elysia HTTP 服务器.
晚点要买一分钱 仅装箱的API是懒惰的,因此套件在严格的节点无害环境管理下也干净地进口.
bun add @brickkit/core
定义服务
创建一个服务,注册一个行动,并服务它。 每个动作都暴露出一条路线: POST /api/{service}/{action} 默认.
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。 。 。 .
bun add @brickkit/core drizzle-orm postgres
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 自动 :
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读取和 已键入客户端指南 用于 Vite 设置和错误处理.
MCP工具
定义诸如动作等工具,包括输入/输出计划和内置元数据:
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://github.com/get-brickkit/brick 页面存档备份,存于互联网档案馆。 。 。 .
追踪
Brick 记录 HTTP, 动作, 和 RPC 跨度 @opentelemetry/api. 追查
默认关闭。 每个应用打开 telemetry 选项和注册
一个OpenTeleometry追踪器提供商,所以时间跨度有去处:
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 * 每当追踪提供者注册时,记录.
import { traceRoute } from "@brickkit/core";
app.all(
"/api/auth/*",
traceRoute("/api/auth/*", ({ request }) => auth.handler(request)),
);
brick dev 注册一个提供者,并将跨度发送到它的仪表板,所以应用程序
有必要 telemetry: true 我也一样.
活动
生成 CRUD 写入可以记录与行相同的交易中的事件,并且
Brick在犯罪后把它交给听众 重试失败者.
添加 outboxTable() 到数据库,定义一个听众,然后传递给 brick()。 。 。 .
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 表现得跟以前一样 见 活动指南。 。 。 .
TanStack 查询选项
安装 @tanstack/query-core v5 与您框架的 TanStack 查询软件包并列 .
导入浏览器条目和生成的合同 :
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 需要转换成相接反应
排成一行。 收藏身份、画相、乐观写作和同步
突变后仍为应用责任. 页面编辑器演示
标准查询突变加其他收藏的明确收藏回溯
消费者.