# @geekmidas/constructs 中文文档

规范地址：https://npmcn.com/package/%40geekmidas/constructs/

版本：9\.6\.1
npm 元数据更新时间：2026-11-16T09:28:53.845Z
中文译文更新时间：2026-11-16T09:33:29.741Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：3.2 MB，287 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：msw \>=2\.0\.0，hono \>=4\.8\.2，@middy/core \>=6\.3\.1，@geekmidas/db ^9\.6\.1，@geekmidas/audit ^9\.6\.1，@geekmidas/cache ^9\.6\.1，@geekmidas/envkit ^9\.6\.1，@geekmidas/errors ^9\.6\.1，@geekmidas/events ^9\.6\.1，@geekmidas/logger ^9\.6\.1，@geekmidas/schema ^9\.6\.1，@types/aws-lambda \>=8\.10\.92，@geekmidas/services ^9\.6\.1，@geekmidas/rate-limit ^9\.6\.1
- 首次发布：2025-10-19T18:21:56.551Z
- 最新版本发布：2026-11-16T09:28:53.510Z
- 近 30 天下载量：14332（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：259（近 12 个月 252 个）

## 中文简介

一个构建类型安全HTTP端点,云功能,计划任务,以及事件订阅器的综合框架,具备了全面的TypeScript支持和AWS Lambda部署能力.

## 安装

```sh
npm install @geekmidas/constructs
```

也可以使用：`pnpm add @geekmidas/constructs`、`yarn add @geekmidas/constructs`、`bun add @geekmidas/constructs`

## README

# @geekmidas/ 构造

一个构建类型安全HTTP端点,云功能,计划任务,以及事件订阅器的综合框架,具备了全面的TypeScript支持和AWS Lambda部署能力.

## 特征

-   **类型安全终点**: 以完全类型推论构建 HTTP 端点
-   **云函数**: 创建无服务器功能并进行计划验证
-   **计划任务**: 用类型安全处理器定义 cron 任务
-   **事件订阅者**: 处理结构化消息的事件
-   **服务发现**: 内置依赖性注射系统
-   **多个适配器**: AWS Lambda, API Gateway (v1/v2) 和 Hono 支持
-   **标准计划验证**: 与Zod、Valibot和其他验证图书馆合作
-   **事件出版**: 从任意构造中综合事件发布
-   **审计日志**: 具有自动回滚支持的交易意识审计系统
-   **限制费率**: 使用可配置储存限制内置率
-   **OpenAPI 集成**: 从端点生成 OpenAPI 规格

## 安装

```bash
pnpm add @geekmidas/constructs
```

## 软件包导出

```typescript
// Endpoints
import { e, EndpointBuilder } from '@geekmidas/constructs/endpoints';

// Functions
import { f, FunctionBuilder } from '@geekmidas/constructs/functions';

// Crons
import { cron, CronBuilder } from '@geekmidas/constructs/crons';

// Subscribers
import { SubscriberBuilder } from '@geekmidas/constructs/subscribers';
```

## 快速启动

### HTTP 终点

以流畅的构建器模式创建类型安全 HTTP 端点 :

```typescript
import { e } from '@geekmidas/constructs/endpoints';
import { z } from 'zod';

// Simple GET endpoint
export const getUsers = e
  .get('/users')
  .output(z.array(z.object({
    id: z.string(),
    name: z.string(),
    email: z.string().email()
  })))
  .handle(async () => {
    return [
      { id: '1', name: 'John Doe', email: 'john@example.com' }
    ];
  });

// POST endpoint with body validation
export const createUser = e
  .post('/users')
  .body(z.object({
    name: z.string().min(1),
    email: z.string().email()
  }))
  .output(z.object({
    id: z.string(),
    name: z.string(),
    email: z.string()
  }))
  .handle(async ({ body }) => {
    // body is fully typed as { name: string; email: string }
    return {
      id: crypto.randomUUID(),
      name: body.name,
      email: body.email
    };
  });

// Endpoint with query parameters
export const searchUsers = e
  .get('/users/search')
  .query(z.object({
    q: z.string(),
    limit: z.coerce.number().default(10)
  }))
  .output(z.array(z.object({
    id: z.string(),
    name: z.string()
  })))
  .handle(async ({ query }) => {
    // query is typed as { q: string; limit: number }
    return [];
  });
```

### 云函数

以输入/输出验证创建无服务器功能 :

```typescript
import { f } from '@geekmidas/constructs/functions';
import { z } from 'zod';

export const processOrder = f
  .input(z.object({
    orderId: z.string(),
    items: z.array(z.object({
      id: z.string(),
      quantity: z.number().int().positive()
    }))
  }))
  .output(z.object({
    orderId: z.string(),
    status: z.enum(['processing', 'completed', 'failed']),
    processedAt: z.string().datetime()
  }))
  .timeout(300000) // 5 minutes
  .handle(async ({ input, logger }) => {
    logger.info(`Processing order ${input.orderId}`);

    // Process order logic
    for (const item of input.items) {
      logger.info(`Processing item ${item.id}, quantity: ${item.quantity}`);
    }

    return {
      orderId: input.orderId,
      status: 'completed',
      processedAt: new Date().toISOString()
    };
  });
```

### 计划任务( Crons)

定义带有时间表的 cron 工作 :

```typescript
import { cron } from '@geekmidas/constructs/crons';

// Daily report at 9 AM UTC
export const dailyReport = cron
  .schedule('cron(0 9 * * ? *)')
  .timeout(600000) // 10 minutes
  .handle(async ({ logger }) => {
    logger.info('Generating daily report');

    const reportDate = new Date().toISOString().split('T')[0];
    const reportData = {
      date: reportDate,
      totalOrders: 150,
      totalRevenue: 12500.00
    };

    logger.info('Daily report generated', reportData);
    return reportData;
  });

// Hourly cleanup
export const hourlyCleanup = cron
  .schedule('cron(0 * * * *)')
  .timeout(300000) // 5 minutes
  .handle(async ({ logger }) => {
    logger.info('Running hourly cleanup');

    const itemsCleaned = 42;
    logger.info(`Cleaned ${itemsCleaned} items`);

    return { itemsCleaned };
  });
```

### 事件订阅者

处理类型安全消息的事件 :

```typescript
import { SubscriberBuilder } from '@geekmidas/constructs/subscribers';
import { z } from 'zod';

export const userEventsSubscriber = new SubscriberBuilder()
  .subscribe(['user.created', 'user.updated', 'user.deleted'])
  .timeout(30000)
  .output(z.object({
    processed: z.number(),
    success: z.boolean()
  }))
  .handle(async ({ events, logger }) => {
    logger.info(
      { eventCount: events.length },
      'Processing user events'
    );

    for (const event of events) {
      try {
        switch (event.type) {
          case 'user.created':
            logger.info({ userId: event.data.userId }, 'User created');
            break;
          case 'user.updated':
            logger.info({ userId: event.data.userId }, 'User updated');
            break;
          case 'user.deleted':
            logger.info({ userId: event.data.userId }, 'User deleted');
            break;
        }
      } catch (error) {
        logger.error({ error, event }, 'Failed to process event');
        throw error;
      }
    }

    return {
      processed: events.length,
      success: true
    };
  });
```

## 高级特性

### 安保计划

为您的 API 定义 OpenAPI 安全方案。 这些用于: `@geekmidas/cli` 在客户端中生成类型安全认证.

#### 内设安保计划

下列授权方名称自动映射到 OpenAPI 安全方案 :

| 授权者 | 安保计划 |
| --- | --- |
| `jwt` | `{ type: 'http', scheme: 'bearer', bearerFormat: 'JWT' }` |
| `bearer` | `{ type: 'http', scheme: 'bearer' }` |
| `apiKey` | `{ type: 'apiKey', in: 'header', name: 'X-API-Key' }` |
| `oauth2` | `{ type: 'oauth2', flows: {} }` |
| `oidc` | `{ type: 'openIdConnect', openIdConnectUrl: '' }` |
| `iam` | `{ type: 'apiKey', in: 'header', name: 'Authorization' }` (AWS SigV4号) |

```typescript
import { e } from '@geekmidas/constructs/endpoints';

// Using built-in 'jwt' scheme
export const getUsers = e
  .get('/users')
  .authorizer('jwt')  // Automatically uses JWT security scheme
  .handle(async ({ session }) => {
    // session contains JWT claims
    return [];
  });
```

#### 自定义安全方案

对于自定义认证方法, 使用 `.securitySchemes()` 终点事实 :

```typescript
import { EndpointFactory } from '@geekmidas/constructs/endpoints';

const api = new EndpointFactory()
  .securitySchemes({
    // Custom OAuth2 with specific flows
    oauth2: {
      type: 'oauth2',
      flows: {
        authorizationCode: {
          authorizationUrl: 'https://auth.example.com/authorize',
          tokenUrl: 'https://auth.example.com/token',
          scopes: {
            'read:users': 'Read user data',
            'write:users': 'Modify user data',
          },
        },
      },
    },
    // Custom API key in query parameter
    queryApiKey: {
      type: 'apiKey',
      in: 'query',
      name: 'api_key',
    },
  });

// Use custom security scheme
export const getUsers = api
  .get('/users')
  .authorizer('oauth2')
  .handle(async () => []);
```

#### 默认授权器

设置工厂所有端点的默认授权符 :

```typescript
const api = new EndpointFactory()
  .authorizer('jwt');  // All endpoints inherit this authorizer

// Protected by default
export const getProfile = api
  .get('/profile')
  .handle(async ({ session }) => {
    return { userId: session.claims.sub };
  });

// Override to make public
export const getHealth = api
  .get('/health')
  .authorizer('none')  // Explicitly public
  .handle(async () => ({ status: 'ok' }));
```

### 服务发现

向您的构造注入服务 :

```typescript
import { e } from '@geekmidas/constructs/endpoints';
import type { Service } from '@geekmidas/services';
import type { EnvironmentParser } from '@geekmidas/envkit';
import { Kysely } from 'kysely';
import { z } from 'zod';

// Define a database service
const databaseService = {
  serviceName: 'database' as const,
  async register(envParser: EnvironmentParser<{}>) {
    const config = envParser.create((get) => ({
      url: get('DATABASE_URL').string()
    })).parse();

    const db = new Kysely({ /* config */ });
    return db;
  }
} satisfies Service<'database', Kysely<Database>>;

// Use service in endpoint
export const getUserFromDb = e
  .get('/users/:id')
  .params(z.object({ id: z.string() }))
  .services([databaseService])
  .handle(async ({ params, services }) => {
    // services.database is fully typed
    const user = await services.database
      .selectFrom('users')
      .where('id', '=', params.id)
      .selectAll()
      .executeTakeFirst();

    return user;
  });
```

### 事件出版

从任意构造发布事件 :

```typescript
import { e } from '@geekmidas/constructs/endpoints';
import type { Service } from '@geekmidas/services';
import type { EventPublisher, PublishableMessage } from '@geekmidas/events';
import { z } from 'zod';

// Define event types
type UserEvents =
  | PublishableMessage<'user.created', { userId: string; email: string }>
  | PublishableMessage<'user.updated', { userId: string }>;

// Create event publisher service
const userEventPublisher = {
  serviceName: 'userEventPublisher' as const,
  async register(envParser: EnvironmentParser<{}>) {
    const config = envParser.create((get) => ({
      publisherUrl: get('EVENT_PUBLISHER_URL').string()
    })).parse();

    const { Publisher } = await import('@geekmidas/events');
    return Publisher.fromConnectionString<UserEvents>(config.publisherUrl);
  }
} satisfies Service<'userEventPublisher', EventPublisher<UserEvents>>;

// Use in endpoint with event publishing
export const createUser = e
  .post('/users')
  .body(z.object({
    name: z.string(),
    email: z.string().email()
  }))
  .publisher(userEventPublisher)
  .event('user.created', (body, result) => ({
    userId: result.id,
    email: body.email
  }))
  .handle(async ({ body, publish }) => {
    const user = {
      id: crypto.randomUUID(),
      name: body.name,
      email: body.email
    };

    // Events are automatically published after successful execution
    return user;
  });
```

### 数据库背景

使用 `.database()`数字 :

```typescript
import { e } from '@geekmidas/constructs/endpoints';
import type { Service } from '@geekmidas/services';
import type { EnvironmentParser } from '@geekmidas/envkit';
import { Kysely, PostgresDialect } from 'kysely';
import { z } from 'zod';

// Define a database service
const databaseService = {
  serviceName: 'database' as const,
  async register(envParser: EnvironmentParser<{}>) {
    const config = envParser.create((get) => ({
      url: get('DATABASE_URL').string()
    })).parse();

    return new Kysely<Database>({
      dialect: new PostgresDialect({
        connectionString: config.url
      })
    });
  }
} satisfies Service<'database', Kysely<Database>>;

// Use .database() to inject db into context
export const getUsers = e
  .get('/users')
  .output(z.array(userSchema))
  .database(databaseService)
  .handle(async ({ db }) => {
    // db is always defined when .database() is called (not optional)
    const users = await db
      .selectFrom('users')
      .selectAll()
      .execute();

    return users;
  });
```

**关键特性:**

-   **类型安全**数字 : `db` 仅在上下文中 `.database()` 名为
-   **非可选**: 与 `services.database`, (中文(简体) ), `db` 总是被定义(不是) `undefined`(中文(简体) )
-   **自动交易**: 与 `.auditor()` 使用 `KyselyAuditStorage`, (中文(简体) ), `db` 自动进行交易

#### 审计交易数据库

在使用两者时 `.database()` 财务报告和审定财务报表 `.auditor()` 拥有同样的数据库, `db` 自动为交易 - 确保ACID 遵守,而不附加任何代码 :

```typescript
export const createUser = e
  .post('/users')
  .body(z.object({ name: z.string(), email: z.string().email() }))
  .output(userSchema)
  .database(databaseService)
  .auditor(auditStorageService)
  .handle(async ({ body, db }) => {
    // db is automatically the transaction when auditor uses KyselyAuditStorage
    // Both the user insert and audit records commit/rollback together
    const user = await db
      .insertInto('users')
      .values({ id: crypto.randomUUID(), ...body })
      .returningAll()
      .executeTakeFirstOrThrow();

    return user;
  });
```

**如何运作:**

-   无 `.auditor()`数字 : `db` 是原始数据库连接
-   与 `.auditor()` 使用 `KyselyAuditStorage` **与匹配 `databaseServiceName`**数字 : `db` 自动进行交易
-   与 `.auditor()` 使用不同的存储或不同的数据库: `db` 仍为原始数据库

对于自动交易共享,审计存储必须声明相同的数据库服务名称:

```typescript
const auditStorageService = {
  serviceName: 'auditStorage' as const,
  async register(envParser: EnvironmentParser<{}>) {
    const db = await databaseService.register(envParser);
    return new KyselyAuditStorage({
      db,
      tableName: 'audit_logs',
      databaseServiceName: 'database', // Must match databaseService.serviceName
    });
  }
};
```

### 审计日志

添加了解交易的审计记录以跟踪数据变化。 审计 **内部** 同样的数据库交易 与您的突变, 确保它们被解剖 或滚回一起.

#### 建立审计存储

首先,利用 `@geekmidas/audit`数字 :

```typescript
import { KyselyAuditStorage } from '@geekmidas/audit/kysely';
import type { Service } from '@geekmidas/services';
import type { EnvironmentParser } from '@geekmidas/envkit';

const auditStorageService = {
  serviceName: 'auditStorage' as const,
  async register(envParser: EnvironmentParser<{}>) {
    const db = await databaseService.register(envParser);
    return new KyselyAuditStorage({
      db,
      tableName: 'audit_logs',
      // Set this to enable automatic transaction sharing with .database()
      databaseServiceName: databaseService.serviceName,
    });
  }
} satisfies Service<'auditStorage', KyselyAuditStorage<Database>>;
```

#### 界定审计行动类型

为您的应用程序定义类型安全的审计动作 :

```typescript
import type { AuditableAction } from '@geekmidas/audit';

type AppAuditAction =
  | AuditableAction<'user.created', { userId: string; email: string }>
  | AuditableAction<'user.updated', { userId: string; changes: string[] }>
  | AuditableAction<'user.deleted', { userId: string; reason?: string }>
  | AuditableAction<'order.placed', { orderId: string; total: number }>;
```

#### 申报审计

定义在结束点上宣布的审计 - 在成功处理器执行后自动记录:

```typescript
import { e } from '@geekmidas/constructs/endpoints';
import { z } from 'zod';

const userSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email()
});

export const createUser = e
  .post('/users')
  .body(z.object({ name: z.string(), email: z.string().email() }))
  .output(userSchema)
  .database(databaseService)
  .auditor(auditStorageService)
  // Optional: extract actor from request context
  .actor(({ session, header }) => ({
    id: session?.userId ?? 'anonymous',
    type: session ? 'user' : 'anonymous',
    ip: header('x-forwarded-for'),
  }))
  // Declarative audits - type-safe with AppAuditAction
  .audit<AppAuditAction>([
    {
      type: 'user.created',
      payload: (response) => ({
        userId: response.id,
        email: response.email,
      }),
      // Optional: only audit when condition is true
      when: (response) => response.email !== 'system@example.com',
      // Optional: link audit to entity for querying
      entityId: (response) => response.id,
      table: 'users',
    },
  ])
  .handle(async ({ body, db }) => {
    // db is automatically the transaction when auditor uses KyselyAuditStorage
    const user = await db
      .insertInto('users')
      .values({ id: crypto.randomUUID(), ...body })
      .returningAll()
      .executeTakeFirstOrThrow();

    return user;
  });
```

**重要**: 当使用时 `KyselyAuditStorage`,适配器将处理器执行包在一个数据库交易中。 这个 `db` 在上下文中是自动交易,因此可以直接用于符合ACID的突变.

#### 手动操作的审计

对于复杂的情景,使用 `ctx.auditor` 以手动记录操作器内的审计 :

```typescript
export const processOrder = e
  .post('/orders')
  .database(databaseService)
  .services([paymentService])
  .auditor(auditStorageService)
  .actor(({ session }) => ({ id: session.userId, type: 'user' }))
  .handle(async ({ body, db, services, auditor }) => {
    // db is automatically the transaction when auditor uses KyselyAuditStorage
    const order = await db
      .insertInto('orders')
      .values(body)
      .returningAll()
      .executeTakeFirstOrThrow();

    // Manual audit for payment (external service call)
    const payment = await services.payment.charge(order.total);
    auditor.audit('payment.processed', {
      orderId: order.id,
      amount: order.total,
      transactionId: payment.transactionId,
    });

    // Conditional audit for high-value orders
    if (order.total > 10000) {
      auditor.audit('order.high_value', {
        orderId: order.id,
        total: order.total,
        requiresReview: true,
      });
    }

    return order;
  });
```

#### 合并申报和人工审计

你们可以一起使用两种方法:

```typescript
export const updateUser = e
  .put('/users/:id')
  .params(z.object({ id: z.string() }))
  .body(z.object({ name: z.string().optional(), email: z.string().email().optional() }))
  .output(userSchema)
  .database(databaseService)
  .auditor(auditStorageService)
  .actor(({ session }) => ({ id: session.userId, type: 'user' }))
  // Declarative audit - always runs on success
  .audit<AppAuditAction>([
    {
      type: 'user.updated',
      payload: (response) => ({
        userId: response.id,
        changes: ['profile'],
      }),
    },
  ])
  .handle(async ({ params, body, db, auditor }) => {
    // db is automatically the transaction when auditor uses KyselyAuditStorage

    // Fetch old values for comparison
    const oldUser = await db
      .selectFrom('users')
      .where('id', '=', params.id)
      .selectAll()
      .executeTakeFirstOrThrow();

    // Update user
    const user = await db
      .updateTable('users')
      .set(body)
      .where('id', '=', params.id)
      .returningAll()
      .executeTakeFirstOrThrow();

    // Manual audit with old/new values for detailed change tracking
    if (oldUser.email !== user.email) {
      auditor.audit('user.email_changed', {
        userId: user.id,
        oldEmail: oldUser.email,
        newEmail: user.email,
      });
    }

    return user;
  });
```

#### 交易支助如何运作

使用时 `KyselyAuditStorage`,自动调整器:

1.  **创建审计背景** 处理器执行前
2.  **在交易中环绕执行** 使用 `withAuditableTransaction`
3.  **通过审计员** 通过 `ctx.auditor`
4.  **申报性审计过程** 处理器成功后
5.  **取消所有审计** 在交易中存储
6.  **提交或滚回** - 如果操作员丢弃,数据和审计都会回滚

```
┌─────────────────────────────────────────────────────────────┐
│                    Request Flow                              │
├─────────────────────────────────────────────────────────────┤
│  1. Create audit context (auditor + storage)                │
│  2. BEGIN TRANSACTION                                        │
│     ├── Execute handler (with ctx.auditor)                  │
│     ├── Handler calls auditor.audit() for manual audits     │
│     ├── Process declarative .audit() definitions            │
│     ├── Flush all audit records to storage                  │
│  3. COMMIT (or ROLLBACK if handler throws)                  │
└─────────────────────────────────────────────────────────────┘
```

这确保:

-   **原子**: 如果突变失败, 审计永远不会被写入
-   **一致性**: 没有因操作失败而成为孤儿的审计记录
-   **回滚安全**:在日后出现错误之前记录的手工审计也被卷回

#### 审计表

为审计表创建 Kysely 迁移 :

```typescript
// migrations/YYYYMMDDHHMMSS_create_audit_logs.ts
import type { Kysely } from 'kysely';
import { sql } from 'kysely';

export async function up(db: Kysely<unknown>): Promise<void> {
  await db.schema
    .createTable('audit_logs')
    .addColumn('id', 'varchar(32)', (col) => col.primaryKey())
    .addColumn('type', 'varchar', (col) => col.notNull())
    .addColumn('operation', 'varchar', (col) => col.notNull())
    .addColumn('table', 'varchar')
    .addColumn('entity_id', 'varchar')
    .addColumn('old_values', 'jsonb')
    .addColumn('new_values', 'jsonb')
    .addColumn('payload', 'jsonb')
    .addColumn('timestamp', 'timestamp', (col) =>
      col.defaultTo(sql`now()`).notNull(),
    )
    .addColumn('actor_id', 'varchar')
    .addColumn('actor_type', 'varchar')
    .addColumn('actor_data', 'jsonb')
    .addColumn('metadata', 'jsonb')
    .execute();

  // Create indexes for common queries
  await db.schema
    .createIndex('idx_audit_logs_type')
    .on('audit_logs')
    .column('type')
    .execute();

  await db.schema
    .createIndex('idx_audit_logs_entity')
    .on('audit_logs')
    .column('entity_id')
    .execute();

  await db.schema
    .createIndex('idx_audit_logs_actor')
    .on('audit_logs')
    .column('actor_id')
    .execute();

  await db.schema
    .createIndex('idx_audit_logs_timestamp')
    .on('audit_logs')
    .column('timestamp')
    .execute();
}

export async function down(db: Kysely<unknown>): Promise<void> {
  await db.schema.dropTable('audit_logs').execute();
}
```

如果使用带有 Kysely 的 CameCase 列名称 `CamelCasePlugin`数字 :

```typescript
// migrations/YYYYMMDDHHMMSS_create_audit_logs.ts
import type { Kysely } from 'kysely';
import { sql } from 'kysely';

export async function up(db: Kysely<unknown>): Promise<void> {
  await db.schema
    .createTable('auditLogs')
    .addColumn('id', 'varchar(32)', (col) => col.primaryKey())
    .addColumn('type', 'varchar', (col) => col.notNull())
    .addColumn('operation', 'varchar', (col) => col.notNull())
    .addColumn('table', 'varchar')
    .addColumn('entityId', 'varchar')
    .addColumn('oldValues', 'jsonb')
    .addColumn('newValues', 'jsonb')
    .addColumn('payload', 'jsonb')
    .addColumn('timestamp', 'timestamp', (col) =>
      col.defaultTo(sql`now()`).notNull(),
    )
    .addColumn('actorId', 'varchar')
    .addColumn('actorType', 'varchar')
    .addColumn('actorData', 'jsonb')
    .addColumn('metadata', 'jsonb')
    .execute();

  await db.schema
    .createIndex('idx_audit_logs_type')
    .on('auditLogs')
    .column('type')
    .execute();

  await db.schema
    .createIndex('idx_audit_logs_entity')
    .on('auditLogs')
    .column('entityId')
    .execute();

  await db.schema
    .createIndex('idx_audit_logs_actor')
    .on('auditLogs')
    .column('actorId')
    .execute();

  await db.schema
    .createIndex('idx_audit_logs_timestamp')
    .on('auditLogs')
    .column('timestamp')
    .execute();
}

export async function down(db: Kysely<unknown>): Promise<void> {
  await db.schema.dropTable('auditLogs').execute();
}
```

#### 查询审计记录

这个 `KyselyAuditStorage` 页:1 `query` 方法 :

```typescript
// In a handler or service
const audits = await auditStorage.query({
  entityId: userId,
  table: 'users',
  limit: 50,
  orderBy: 'timestamp',
  orderDirection: 'desc',
});
```

### 限制费率

添加限制终点的速率 :

```typescript
import { e } from '@geekmidas/constructs/endpoints';
import { InMemoryCache } from '@geekmidas/cache/memory';
import { z } from 'zod';

export const sendMessage = e
  .post('/api/messages')
  .rateLimit({
    limit: 10,
    windowMs: 60000, // 1 minute
    cache: new InMemoryCache(),
  })
  .body(z.object({
    content: z.string()
  }))
  .handle(async ({ body }) => {
    // Rate limited to 10 requests per minute
    return { success: true };
  });
```

## AWS Lambda 适应器

向AWS Lambda部署您的构造:

### API 网关 v1 适应器

```typescript
import { AmazonApiGatewayV1Endpoint } from '@geekmidas/constructs/aws';
import { getUsers } from './endpoints';
import { envParser } from './env';

const adapter = new AmazonApiGatewayV1Endpoint(envParser, getUsers);

export const handler = adapter.handler;
```

### API 网关 v2 适配器

```typescript
import { AmazonApiGatewayV2Endpoint } from '@geekmidas/constructs/aws';
import { getUsers } from './endpoints';
import { envParser } from './env';

const adapter = new AmazonApiGatewayV2Endpoint(envParser, getUsers);

export const handler = adapter.handler;
```

### Lambda 函数适配器

```typescript
import { AWSLambdaFunction } from '@geekmidas/constructs/aws';
import { processOrder } from './functions';
import { envParser } from './env';

const adapter = new AWSLambdaFunction(envParser, processOrder);

export const handler = adapter.handler;
```

### Lambda Cron 适应器

```typescript
import { AWSScheduledFunction } from '@geekmidas/constructs/aws';
import { dailyReport } from './crons';
import { envParser } from './env';

const adapter = new AWSScheduledFunction(envParser, dailyReport);

export const handler = adapter.handler;
```

### Lambda 订户适应器

```typescript
import { AWSLambdaSubscriber } from '@geekmidas/constructs/aws';
import { userEventsSubscriber } from './subscribers';
import { envParser } from './env';

const adapter = new AWSLambdaSubscriber(envParser, userEventsSubscriber);

export const handler = adapter.handler;
```

## Hono 服务器适配器

将您的端点作为 Hono 服务器 :

```typescript
import { HonoEndpoint } from '@geekmidas/constructs/endpoints';
import { ServiceDiscovery } from '@geekmidas/services';
import { Hono } from 'hono';
import { envParser } from './env';
import { logger } from './logger';
import { getUsers, createUser } from './endpoints';

export function createApp(app?: Hono): Hono {
  const honoApp = app || new Hono();

  const endpoints = [getUsers, createUser];

  const serviceDiscovery = ServiceDiscovery.getInstance(logger, envParser);

  HonoEndpoint.addRoutes(endpoints, serviceDiscovery, honoApp);

  return honoApp;
}

// server.ts
import { serve } from '@hono/node-server';
import { createApp } from './app';

const app = createApp();

serve({
  fetch: app.fetch,
  port: 3000
}, () => {
  console.log('Server running on http://localhost:3000');
});
```

## OpenAPI 支持

从端点提取 OpenAPI 组件 :

```typescript
import { OpenApiExtractor } from '@geekmidas/constructs/endpoints';
import { getUsers, createUser } from './endpoints';

const extractor = new OpenApiExtractor();
const components = extractor.extractComponents([getUsers, createUser]);

// Use with @geekmidas/cli to generate full OpenAPI spec
```

## 环境可变检测

所有建筑都支持自动环境可变检测以提供建设时的基础设施。 这使部署工具能够确切了解每个构造需要哪些环境变量.

### 使用 `getEnvironment()`

每个构造都有一个同位素 `getEnvironment()` 返回其服务所需的环境变量的方法:

```typescript
import { e } from '@geekmidas/constructs/endpoints';
import { databaseService } from './services/database';
import { cacheService } from './services/cache';

const endpoint = e
  .get('/users')
  .services([databaseService, cacheService])
  .handle(async ({ services }) => {
    // Implementation
  });

// Detect required environment variables
const envVars = await endpoint.getEnvironment();
// Returns: ['CACHE_URL', 'DATABASE_URL'] (sorted alphabetically)
```

### 如何运作

探测工作由:

1.  创建“ 偷窥” `EnvironmentParser` 带有空配置
2.  呼叫每个服务 `register()` 使用嗅探器的方法
3.  跟踪哪些环境变量通过 `get('VAR_NAME')`
4.  收集和删除可变名称
5.  返回排序的可变名称数组

**重要**: 环境变量在 `get('VAR_NAME')` 被称为, **在此之前** `.parse()` 验证数值。 这意味着即使实际环境值不存在(建设时间),检测也是有效的.

### 检测服务模式

为使环境探测发挥作用,服务应返回 `ConfigParser` 从 `envParser.create()`数字 :

```typescript
import type { Service } from '@geekmidas/services';
import type { EnvironmentParser } from '@geekmidas/envkit';

// ✅ Sync service - returns ConfigParser directly
const databaseService = {
  serviceName: 'database' as const,
  register(envParser: EnvironmentParser<{}>) {
    // Return the ConfigParser - this tracks env vars
    return envParser.create((get) => ({
      url: get('DATABASE_URL').string(),
      port: get('DATABASE_PORT').string().transform(Number).default('5432')
    }));
  }
} satisfies Service<'database', any>;

// ✅ Async service - check for empty env to support detection
const eventService = {
  serviceName: 'events' as const,
  register(envParser: EnvironmentParser<{}>) {
    const configParser = envParser.create((get) => ({
      connectionString: get('EVENT_CONNECTION_STRING').string()
    }));

    // Return ConfigParser for environment detection (build time)
    // @ts-ignore - accessing internal property to detect sniffer
    if (Object.keys(envParser.env || {}).length === 0) {
      return configParser;
    }

    // Return Promise for runtime
    return (async () => {
      const config = configParser.parse();
      // Initialize service with config
      return await createService(config);
    })();
  }
} satisfies Service<'events', any>;
```

### 构建时间使用

这个 `@geekmidas/cli` 自动调用 `getEnvironment()` 在构建时填充列表 :

```json
{
  "routes": [
    {
      "path": "/users",
      "method": "GET",
      "handler": ".gkm/getUsers.handler",
      "environment": [
        "DATABASE_URL",
        "DATABASE_PORT"
      ]
    }
  ]
}
```

然后,这个表可以被基础设施-as-code工具(Terraform,CDK,SST等)使用,以正确的环境变量自动配置Lambda函数.

### 特征

-   **自动检测**: 不需要手动配置
-   **Async 服务支持**: 既同步又同步服务
-   **复制**: 即使被多个服务使用, 每一个变量都列出一次
-   **排序输出**: 变量总是按字母顺序返回
-   **反应错误**: 解析失败不影响检测
-   **出版商支持**: 从中检测变量 `.publisher()` 服务

### 多服务示例

```typescript
import { e } from '@geekmidas/constructs/endpoints';
import { databaseService } from './services/database';
import { cacheService } from './services/cache';
import { emailService } from './services/email';

const endpoint = e
  .post('/users')
  .services([databaseService, cacheService, emailService])
  .handle(async ({ services }) => {
    // Create user
  });

// Automatically detects all variables from all services
const envVars = await endpoint.getEnvironment();
// Returns: [
//   'CACHE_URL',
//   'DATABASE_URL',
//   'DATABASE_PORT',
//   'SMTP_HOST',
//   'SMTP_PORT',
//   'SMTP_USER',
//   'SMTP_PASS'
// ]
```

## 相关软件包

-   [@geekmidas/服务](https://npmcn.com/package/%40geekmidas/services) - 服务发现和依赖性注射
-   [@geekmidas/活动](https://npmcn.com/package/%40geekmidas/events) - 活动出版和订阅
-   [@geekmidas/审计](https://npmcn.com/package/%40geekmidas/audit) - 了解交易的审计记录
-   [@ geekmidas/ logger (英语)](https://npmcn.com/package/%40geekmidas/logger) - 结构化伐木
-   [@geekmidas/envkit (英语)](https://npmcn.com/package/%40geekmidas/envkit) - 环境配置
-   [@geekmidas/错误](https://npmcn.com/package/%40geekmidas/errors) - HTTP 错误分类
-   [@geekmidas/ 客户端](https://npmcn.com/package/%40geekmidas/client) - 消费终点的安全型客户端
-   [@geekmidas/ cli (英语)](https://npmcn.com/package/%40geekmidas/cli) - 用于建设和部署的CLI工具

## 许可证

麻省理工学院

## 常见问题

### @geekmidas/constructs 是什么？

一个构建类型安全HTTP端点,云功能,计划任务,以及事件订阅器的综合框架,具备了全面的TypeScript支持和AWS Lambda部署能力\.

### 如何安装 @geekmidas/constructs？

在项目目录运行 npm install @geekmidas/constructs，或使用 pnpm add / yarn add / bun add。

### @geekmidas/constructs 支持 TypeScript 吗？

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

### @geekmidas/constructs 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @geekmidas/constructs 可以商用吗？

@geekmidas/constructs 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @geekmidas/constructs 的下载量有多少？

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

### @geekmidas/constructs 还在维护吗？

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

