# @classytic/arc 中文文档

规范地址：https://npmcn.com/package/%40classytic/arc/

版本：2\.51\.0
npm 元数据更新时间：2026-11-07T14:53:03.062Z
中文译文更新时间：2026-11-09T23:53:52.400Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：3.4 MB，331 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：4 个
- peer 依赖：zod \>=4\.6\.7，jose \>=6\.0\.0，h3-js \>=4\.0\.0，bullmq \>=6\.7\.2，fastify \>=5\.12\.8，ioredis \>=6\.0\.0，typebox \>=1\.0\.0，better-auth \>=1\.7\.18，pino-pretty \>=13\.0\.0，@fastify/jwt \>=10\.0\.0，@fastify/cors \>=11\.0\.0，@fastify/helmet \>=13\.0\.0，@fastify/static \>=10\.0\.0，fastify-raw-body \>=6\.0\.3，@fastify/sensible \>=6\.0\.0，@fastify/multipart \>=10\.0\.0，@fastify/websocket \>=11\.0\.0，@opentelemetry/api \>=1\.9\.0，@fastify/rate-limit \>=11\.0\.0，@classytic/repo-core \>=0\.38\.0，@classytic/primitives \>=0\.37\.0，@classytic/streamline \>=2\.12\.0，@fastify/under-pressure \>=9\.0\.0，@opentelemetry/sdk-node \>=0\.50\.0，@modelcontextprotocol/node \>=2\.1\.2，@modelcontextprotocol/client \>=2\.4\.0，@modelcontextprotocol/server \>=2\.4\.0，@fastify/type-provider-typebox \>=6\.0\.0，@opentelemetry/instrumentation-http \>=0\.50\.0，@opentelemetry/instrumentation-mongodb \>=0\.40\.0，@opentelemetry/exporter-trace-otlp-http \>=0\.50\.0，@opentelemetry/auto-instrumentations-node \>=0\.40\.0
- 首次发布：2026-01-21T17:20:21.302Z
- 最新版本发布：2026-11-07T14:53:02.853Z
- 近 30 天下载量：2740（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：124（近 12 个月 124 个）

## 中文简介

Fastify的面向资源的后端框架 - 干净、最小、强大、可树摇摆

## 安装

```sh
npm install @classytic/arc
```

也可以使用：`pnpm add @classytic/arc`、`yarn add @classytic/arc`、`bun add @classytic/arc`

## README

# @ 经典/ arc

[![Sponsor](https://img.shields.io/github/sponsors/classytic?style=flat-square&label=Sponsor&logo=GitHub&color=EA4AAA)](https://github.com/sponsors/classytic)

Fastify数据库不可知资源框架. 一个 `defineResource()` 调用 - > REST + 认证 + 权限 + 事件 + 缓存 + OpenAPI + MCP 工具.

仅将5+ + + + 节点.js 22+ + + + 无害环境管理

```bash
npm install @classytic/arc fastify

# Security defaults createApp() loads (each opt-out via `cors: false` etc.)
npm install @fastify/cors @fastify/helmet @fastify/rate-limit @fastify/under-pressure @fastify/sensible

# Storage adapter — pick one (kits ship their own adapters under `/adapter`)
npm install @classytic/mongokit mongoose             # MongoDB → @classytic/mongokit/adapter
# OR @classytic/sqlitekit drizzle-orm better-sqlite3 # → @classytic/sqlitekit/adapter
# OR @classytic/prismakit @prisma/client             # → @classytic/prismakit/adapter
# OR implement DataAdapter / RepositoryLike from @classytic/repo-core/adapter
```

* * *

## 为什么弧

|  |  |
| --- | --- |
| **一通电话,全速前进** | `defineResource({ name, adapter, presets, permissions })` → `GET /`, (中文(简体) ), `GET /:id`, (中文(简体) ), `POST /`, (中文(简体) ), `PATCH /:id`, (中文(简体) ), `DELETE /:id` +自定义路线+动作 |
| **DB 不可知论** | Mong (`@classytic/mongokit/adapter`), Drizzle/SQLite (英语:`@classytic/sqlitekit/adapter`),普里斯玛(`@classytic/prismakit/adapter`),或任意 `RepositoryLike` impl – 互换后端而无需重写路径 。 适应者合同居住在 `@classytic/repo-core/adapter`; 弧形 2.12 舰只为零套具专用适配器. |
| **默认多租户** | 租户田地自动注入,有视野的查询,每升缓存密钥,高地事件. |
| **树上可动摇的子路径** | `@classytic/arc/auth`, (中文(简体) ), `/events`, (中文(简体) ), `/cache`, (中文(简体) ), `/mcp`, (中文(简体) ), `/integrations/jobs` ——只支付进口品. |
| **免费MCP工具** | 资源自动生成模型背景协议工具用于AI代理. 相同的权限,相同的字段规则. |

* * *

## 快开始

```typescript
import mongoose from 'mongoose';
import { createApp, loadResources } from '@classytic/arc/factory';

await mongoose.connect(process.env.DB_URI);

// Fail fast on missing CORS env — silent `undefined` here drops to surprising
// browser defaults. Browser apps: declare an explicit allowlist (below).
// Server-to-server / API-key services: `cors: { origin: '*', credentials: false }`
// or `cors: false` to disable entirely (CORS is a browser-only concern).
const ALLOWED_ORIGINS = process.env.ALLOWED_ORIGINS;
if (!ALLOWED_ORIGINS) throw new Error('ALLOWED_ORIGINS env is required');

const app = await createApp({
  preset: 'production',
  resourcePrefix: '/api/v1',
  resources: await loadResources(import.meta.url),  // auto-discover *.resource.ts
  auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
  cors: { origin: ALLOWED_ORIGINS.split(','), credentials: true },
});

await app.listen({ port: 8040, host: '0.0.0.0' });
```

资源可以是静态阵列,Async厂(引擎装入),也可以是从磁盘上自动发现的:

```typescript
// Auto-discover (recommended for >5 resources)
resources: await loadResources(import.meta.url),

// Explicit list
resources: [productResource, orderResource],

// Async factory — runs after `bootstrap[]`, before route wiring
resources: async () => {
  const [catalog, flow] = await Promise.all([ensureCatalogEngine(), ensureFlowEngine()]);
  return loadResources(import.meta.url, { context: { catalog, flow } });
},
```

`loadResources({ context })` 线程引擎处理为默认导出的资源 `(ctx) => defineResource(...)`。没有并行的工厂文件,没有 `exclude: [...]` 簿记.

* * *

## 定义资源

```typescript
import { defineResource } from '@classytic/arc';
import { allowPublic, requireRoles, requireAuth } from '@classytic/arc/permissions';
import { createMongooseAdapter } from '@classytic/mongokit/adapter';
import { buildCrudSchemasFromModel } from '@classytic/mongokit';
import ProductModel from './product.model.js';
import productRepository from './product.repository.js';

export default defineResource({
  name: 'product',
  adapter: createMongooseAdapter({
    model: ProductModel,
    repository: productRepository,
    schemaGenerator: buildCrudSchemasFromModel,    // auto-derives CRUD schemas
  }),
  presets: ['softDelete', 'slugLookup', { name: 'multiTenant', tenantField: 'organizationId' }],
  permissions: {
    list: allowPublic(),
    get: allowPublic(),
    create: requireRoles(['admin']),
    update: requireRoles(['admin']),
    delete: requireRoles(['admin']),
  },
  schemaOptions: {
    fieldRules: {
      name: { minLength: 2, maxLength: 200 },
      sku: { pattern: '^[A-Z]{3}-\\d{3}$' },
      status: { enum: ['draft', 'active', 'archived'] },
      priceMode: { nullable: true },                          // accept null for round-trips
      organizationId: { systemManaged: true, preserveForElevated: true },
    },
    query: {
      allowedPopulate: ['category', 'createdBy'],             // populate whitelist
      filterableFields: { status: { type: 'string' } },
    },
  },
  cache: { staleTime: 30, gcTime: 300, tags: ['catalog'] },
  routes: [
    { method: 'GET', path: '/featured', handler: 'getFeatured', permissions: allowPublic() },
  ],
  actions: {
    approve: { handler: approveOrder, permissions: requireRoles(['admin']) },
  },
  // mcp: false,    // opt out of MCP tool generation for this resource
});
```

自动生成 : `GET /products`, (中文(简体) ), `GET /products/:id`, (中文(简体) ), `POST /products`, (中文(简体) ), `PATCH /products/:id`, (中文(简体) ), `DELETE /products/:id` + 软删除后添加 `GET /products/deleted`, (中文(简体) ), `POST /products/:id/restore` + 搜索键添加 `GET /products/slug/:slug` + 定制路线 + `POST /products/:id/action`。 。 。 .

### 资源简称

```typescript
// Reference data — read-only list+get, fetch-all limits (1000), 5min/10min cache.
defineResource({ name: 'currency', adapter, referenceData: true });

// Service resource — custom routes only, no adapter, no auto-CRUD, no registry entry.
defineResource({
  name: 'health',
  customRoutesOnly: true,
  routes: [{ method: 'GET', path: '/ping', permissions: allowPublic(), handler: () => ({ ok: true }) }],
});

// Tune pagination caps inline (no custom queryParser needed).
defineResource({ name: 'pipeline', adapter, defaultLimit: 200, maxLimit: 500 });
```

A 类 `?limit=` 上限以上为 **夹住它** 已服过役,未遭拒绝(在2.33中更改)。 拒绝使有记录的夹子无法取用,并将一个良性的任务变成400个通常由呼叫者制作的空清单。 有效的封顶在 OpenAPI 参数描述中被携带, 并且响应是自己的 `limit` 报告适用的情况.

* * *

## 权限

基于功能的——非洲区域局、ABAC、REBAC或任何组合.

```typescript
import {
  allowPublic, requireAuth, requireRoles, requireOwnership,
  requireOrgMembership, requireOrgRole, requireServiceScope,
  requireScopeContext, requireOrgInScope,
  allOf, anyOf, when, denyAll,
  createDynamicPermissionMatrix,
} from '@classytic/arc/permissions';

permissions: {
  list: allowPublic(),
  get: requireAuth(),
  create: requireRoles(['admin', 'editor']),
  update: anyOf(requireOwnership('userId'), requireRoles(['admin'])),
  delete: allOf(requireAuth(), requireRoles(['admin'])),
}
```

自定义检查返回 `{ granted, reason?, filters?, scope? }` —— 说 `filters` 传播到 repo 查询( row- level ABAC) , `scope` 下游的邮票属性.

* * *

## 合计

添加 `aggregations: { … }` 到一个资源和弧登记册 `GET /:prefix/aggregations/:name` 每个条目。 每个运行一个便携式 `$match → $group → $project → $sort → $limit` 输油管对装箱 `repo.aggregate(req, options)` ——同形状横跨mongokit / sqlitekit / prismakit,所以仪表板在后端工作不变.

```typescript
import { defineResource, defineAggregation } from '@classytic/arc';

defineResource({
  name: 'transaction',
  adapter,
  presets: [multiTenantPreset({ tenantField: 'organizationId' })],
  permissions: { list: canViewRevenue() },

  aggregations: {
    byPaymentMethod: defineAggregation({
      groupBy: 'method',
      measures: { total: 'sum:amount', count: 'count' },
      sort: { total: -1 },
      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
      permissions: canViewRevenue(),
    }),
    byDay: defineAggregation({
      dateBuckets: { day: { field: 'createdAt', interval: 'day' } },
      groupBy: 'flow',
      measures: { total: 'sum:amount', count: 'count' },
      requireDateRange: { field: 'createdAt', maxRangeDays: 365 },
      cache: { staleTime: 60, swr: true, tags: ['revenue'] },
      permissions: canViewRevenue(),
    }),
  },
});
```

通过查询字符串调用过滤器与声明一起组成 :

```
GET /api/transactions/aggregations/byPaymentMethod?status=verified
GET /api/transactions/aggregations/byDay?createdAt[gte]=2026-01-01&createdAt[lt]=2026-02-01
```

租户范围流经 `repo.aggregate(req, options)` – 工具包的多租户插件处理类型强制(字符串) – ObjectId for mongokit `fieldType: 'objectId'`,用于 sqlitekit 的UUID/文本等). 弧本身不进入滤波槽,因为它具有DB-不可知性. 申报的警卫: `requireFilters`, (中文(简体) ), `requireDateRange { maxRangeDays }`, (中文(简体) ), `maxGroups`。 SWR 缓存 + 标记无效绑定集合到 CRUD 写入 。 每个聚合自导出作为具有相同权限和过滤验证的MCP工具.

* * *

## 认证

歧视工会 `type`数字 :

```typescript
// JWT (with optional revocation + custom token extractor)
auth: { type: 'jwt', jwt: { secret, expiresIn: '15m' } }

// Better Auth (recommended for SaaS with orgs)
import { createBetterAuthAdapter } from '@classytic/arc/auth';
auth: { type: 'betterAuth', betterAuth: createBetterAuthAdapter({ auth: getAuth(), orgContext: true }) }

// Custom Fastify plugin
auth: { type: 'custom', plugin: myAuthPlugin }

// Disabled (e.g. internal services)
auth: false
```

更好的Auth + 弧度资源超过 BA 表:工具包拥有桥. `@classytic/mongokit/better-auth` 船舶 `createBetterAuthOverlay()` (按年计) `DataAdapter` 页:1 `defineResource`和 `registerBetterAuthStubs()` (用于 `populate()`) (中文(简体) ). Sqlitekit 用户手卷 Drizzle 表格——见 [auth-bet-auth-overlay.md (英语)](https://npmcn.com/package/%40classytic/arc/skills/arc/references/auth-better-auth-overlay.md)。 。 。 .

* * *

## 子路径导入

仅导入您需要的子路径 :

| 子路径 | 目的 |
| --- | --- |
| `@classytic/arc` | `defineResource`, (中文(简体) ), `BaseController`,错误类别 |
| `@classytic/repo-core/adapter` | 适应合同类型: `DataAdapter`, (中文(简体) ), `RepositoryLike`, (中文(简体) ), `AdapterRepositoryInput`, (中文(简体) ), `asRepositoryLike`, (中文(简体) ), `isRepository`。 。 。 . **直接从还原核心导入** ——arc故意不再出口合同以保持一个真相来源. |
| `@classytic/arc/factory` | `createApp`, (中文(简体) ), `loadResources`预设 |
| `@classytic/arc/auth` | JWT + 更好的认证适配器 |
| `@classytic/mongokit/better-auth` | BA为蒙哥斯: `createBetterAuthOverlay`, (中文(简体) ), `registerBetterAuthStubs` (公斤拥有) |
| `@classytic/repo-core/better-auth` | 每套包件的共享BA收集登记册 |
| `@classytic/arc/permissions` | 所有权限助手 |
| `@classytic/arc/scope` | `RequestScope` 访问者`isMember`, (中文(简体) ), `isElevated`, (中文(简体) ), `getOrgId`, (...) (中文(简体) ) |
| `@classytic/arc/cache` | `QueryCache`,运输,插件 |
| `@classytic/arc/events` | 事件插件, `MemoryEventTransport`外框(活动类型) `@classytic/primitives/events`(中文(简体) ) |
| `@classytic/arc/events/redis` • 妇女 `/redis-stream` | Redis Pub/Sub + 流运输(选择入) |
| `@classytic/arc/plugins` | 健康、请求识别、版本、追踪、反应-缓存 |
| `@classytic/arc/integrations/jobs` | BullMQ 工作调度器 |
| `@classytic/arc/integrations/websocket` | WebSocket 集成系统 |
| `@classytic/arc/mcp` | 示范背景协议工具+ `createMcpAuthFromBetterAuthApiKey` (Better Auth API- key settlementer),(更好的Auth API-键解析器), `resolveToolCollisions` |
| `@classytic/arc/utils` | `pipeUIMessageStreamToReply`, (中文(简体) ), `UI_MESSAGE_STREAM_HEADERS` (Vercel AI SDK → 快速回复);错误、查询解析器、断路器 |
| `@classytic/arc/testing` | `createTestApp`, (中文(简体) ), `expectArc`, (中文(简体) ), `TestAuthProvider`, (中文(简体) ), `createTestFixtures` |
| `@classytic/arc/types` | 仅管型(零运行时间成本) |

* * *

## 测试

```typescript
import { createTestApp, expectArc } from '@classytic/arc/testing';
import productResource from './product.resource.js';

const ctx = await createTestApp({
  resources: [productResource],
  authMode: 'jwt',
  connectMongoose: true,           // in-memory Mongo + Mongoose connect
});
ctx.auth.register('admin', { user: { id: '1', role: 'admin' }, orgId: 'org-1' });

const res = await ctx.app.inject({
  method: 'POST',
  url: '/products',
  headers: ctx.auth.as('admin').headers,
  payload: { name: 'Widget' },
});
expectArc(res).ok().hidesField('password');

await ctx.close();
```

三个切入点: `createTestApp` (海关设想), `createHttpTestHarness` (~16个自动生成的CRUD/每个资源允许/验证测试),, `runStorageContract` (适应).

* * *

## 国 际

```bash
arc init my-api --mongokit --better-auth --ts    # scaffold a new project
arc generate resource product                    # generate a resource
arc generate resource product --mcp              # + MCP tools file
arc docs ./openapi.json --entry ./dist/index.js  # emit OpenAPI
arc introspect --entry ./dist/index.js           # introspect resources
arc doctor                                       # diagnose env
```

* * *

## 文档

-   **技能** 对于人工智能特工: `npx skills add classytic/arc` ——电线弧入克洛德代码/代理流.
-   **概念参考**数字 : [维基文库/index.md](https://npmcn.com/package/%40classytic/arc/wiki/index.md) ——短而相通的页.
-   **指南**数字 : [文档/](https://npmcn.com/package/%40classytic/arc/docs/) ——启动,框架延伸,生产操作,测试,生态系统.
-   **发布注释**数字 : [变化日志/v2.md](https://npmcn.com/package/%40classytic/arc/changelog/v2.md)。 。 。 .

* * *

## 许可证

麻省理工学院

## 商标

密码是麻省理工学院许可的. **"classytic","arc",并标志为: 经典专卖局长** 并且现在 **没有** 根据麻省理工学院颁发的许可证——见 [贸易商](https://npmcn.com/package/%40classytic/arc/TRADEMARK.md)。 。 。 . 叉子必须更名;许可证覆盖了代码,而不是品牌.

## 常见问题

### @classytic/arc 是什么？

Fastify的面向资源的后端框架 - 干净、最小、强大、可树摇摆

### 如何安装 @classytic/arc？

在项目目录运行 npm install @classytic/arc，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：fastify（\>=5\.12\.8）、@classytic/repo-core（\>=0\.38\.0）、@classytic/primitives（\>=0\.37\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 arc，可以用 npx arc 直接运行。

### @classytic/arc 支持 TypeScript 吗？

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

### @classytic/arc 支持 ESM 还是 CommonJS？

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

### @classytic/arc 需要什么版本的 Node\.js？

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

### @classytic/arc 可以商用吗？

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

### @classytic/arc 的下载量有多少？

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

### @classytic/arc 还在维护吗？

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