# @geekmidas/services 中文文档

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

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

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

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

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

- 包体积（解压后）：271 kB，60 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@middy/core \>=6\.3\.1，@trpc/server \>=11\.0\.0，@geekmidas/envkit ^9\.6\.1，@geekmidas/logger ^9\.6\.1，@types/aws-lambda \>=8\.10\.92
- 首次发布：2025-10-19T18:21:45.440Z
- 最新版本发布：2026-11-16T09:28:56.981Z
- 近 30 天下载量：14969（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：206（近 12 个月 205 个）

## 中文简介

用于TypeScript应用的服务发现和依赖性注射系统,具有完全类型的安全和自动生命周期管理.

## 安装

```sh
npm install @geekmidas/services
```

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

## README

# @geekmidas/服务

用于TypeScript应用的服务发现和依赖性注射系统,具有完全类型的安全和自动生命周期管理.

## 特征

-   **类型安全服务**: 完整类型脚本支持,并带有通用类型推论
-   **懒惰初始化**:服务仅在需要时才初始化
-   **单子图案**:服务被缓存和重复使用
-   **依赖性注射**: 自动服务分辨率和注入
-   **环境一体化**页:1
-   **服务发现**:集中服务登记和发现
-   **处理错误**: 服务初始化期间处理重大错误

## 安装

```bash
pnpm add @geekmidas/services
```

## 快速启动

### 定义服务

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

// Define your database service
const databaseService = {
  serviceName: 'database' as const,
  async register(envParser: EnvironmentParser<{}>) {
    const config = envParser.create((get) => ({
      url: get('DATABASE_URL').string(),
      ssl: get('DATABASE_SSL').string().transform(Boolean).default('false')
    })).parse();

    const db = new Kysely({ /* config */ });
    await db.connection().execute('SELECT 1'); // Health check

    return db;
  }
} satisfies Service<'database', Kysely<Database>>;

export { databaseService };
```

### 在构造中使用服务

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

export const getUser = e
  .get('/users/:id')
  .params(z.object({ id: z.string() }))
  .services([databaseService])
  .handle(async ({ params, services }) => {
    // services.database is fully typed as Kysely<Database>
    const user = await services.database
      .selectFrom('users')
      .where('id', '=', params.id)
      .selectAll()
      .executeTakeFirstOrThrow();

    return user;
  });
```

## 服务发现

服务发现班管理服务生命周期和依赖性注射:

```typescript
import { ServiceDiscovery } from '@geekmidas/services';
import { ConsoleLogger } from '@geekmidas/logger/console';
import { EnvironmentParser } from '@geekmidas/envkit';

const logger = new ConsoleLogger();
const envParser = new EnvironmentParser(process.env).create(() => ({})).parse();

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

// Services are lazily initialized
const database = await serviceDiscovery.discover(databaseService);
```

## 创建服务

### 数据库服务

```typescript
import type { Service } from '@geekmidas/services';
import { Kysely, PostgresDialect } from 'kysely';
import { Pool } from 'pg';

const databaseService = {
  serviceName: 'database' as const,
  async register(envParser: EnvironmentParser<{}>) {
    const config = envParser.create((get) => ({
      host: get('DB_HOST').string(),
      port: get('DB_PORT').string().transform(Number).default('5432'),
      database: get('DB_NAME').string(),
      user: get('DB_USER').string(),
      password: get('DB_PASSWORD').string(),
      ssl: get('DB_SSL').string().transform(Boolean).default('false')
    })).parse();

    const db = new Kysely<Database>({
      dialect: new PostgresDialect({
        pool: new Pool({
          host: config.host,
          port: config.port,
          database: config.database,
          user: config.user,
          password: config.password,
          ssl: config.ssl
        })
      })
    });

    return db;
  }
} satisfies Service<'database', Kysely<Database>>;
```

### Redis/缓存服务

```typescript
import type { Service } from '@geekmidas/services';
import { UpstashCache } from '@geekmidas/cache/upstash';

const cacheService = {
  serviceName: 'cache' as const,
  async register(envParser: EnvironmentParser<{}>) {
    const config = envParser.create((get) => ({
      url: get('UPSTASH_REDIS_URL').string().url(),
      token: get('UPSTASH_REDIS_TOKEN').string()
    })).parse();

    return new UpstashCache({
      url: config.url,
      token: config.token
    });
  }
} satisfies Service<'cache', UpstashCache<any>>;
```

### 电子邮件服务

```typescript
import type { Service } from '@geekmidas/services';
import { createEmailClient } from '@geekmidas/emailkit';
import * as templates from './email-templates';

const emailService = {
  serviceName: 'email' as const,
  async register(envParser: EnvironmentParser<{}>) {
    const config = envParser.create((get) => ({
      host: get('SMTP_HOST').string(),
      port: get('SMTP_PORT').string().transform(Number),
      user: get('SMTP_USER').string(),
      pass: get('SMTP_PASS').string(),
      from: get('EMAIL_FROM').string().email()
    })).parse();

    return createEmailClient({
      smtp: {
        host: config.host,
        port: config.port,
        auth: {
          user: config.user,
          pass: config.pass
        }
      },
      templates,
      defaults: { from: config.from }
    });
  }
} satisfies Service<'email', ReturnType<typeof createEmailClient>>;
```

### 事件出版服务

```typescript
import type { Service } from '@geekmidas/services';
import type { EventPublisher, PublishableMessage } from '@geekmidas/events';

type UserEvents =
  | PublishableMessage<'user.created', { userId: string }>
  | PublishableMessage<'user.updated', { userId: string }>;

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>>;
```

## 多种服务

将多种服务注入一个构造 :

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

export const createUser = e
  .post('/users')
  .body(z.object({
    name: z.string(),
    email: z.string().email()
  }))
  .services([databaseService, cacheService, emailService])
  .handle(async ({ body, services }) => {
    // Check cache first
    const cached = await services.cache.get(`user:${body.email}`);
    if (cached) {
      return cached;
    }

    // Create user in database
    const user = await services.database
      .insertInto('users')
      .values(body)
      .returningAll()
      .executeTakeFirstOrThrow();

    // Send welcome email
    await services.email.sendTemplate('welcome', {
      to: user.email,
      props: { name: user.name }
    });

    // Cache result
    await services.cache.set(`user:${user.email}`, user, 3600);

    return user;
  });
```

## 服务周期

### 懒惰初始化

服务只有在第一次提出要求时才初始化:

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

// Not initialized yet
const service1 = databaseService;

// Initialized here
const db = await serviceDiscovery.discover(databaseService);

// Reuses same instance (singleton)
const db2 = await serviceDiscovery.discover(databaseService);
assert(db === db2); // true
```

### 单子图案

服务发现确保每项服务都是单通:

```typescript
// First call initializes the service
const db1 = await serviceDiscovery.discover(databaseService);

// Subsequent calls return cached instance
const db2 = await serviceDiscovery.discover(databaseService);
const db3 = await serviceDiscovery.discover(databaseService);

// All references point to same instance
console.log(db1 === db2 && db2 === db3); // true
```

### 请求范围日志

因为服务是单顿, `register()` 运行 **一次** 请求时 每个请求都更改日志 . `serviceContext.getLogger()` 返回 a **请求范围代理** 重新解答当前请求的日志器, 因此,服务可以安全地捕捉记录器一次 `register()` 继续日志 反对正确的要求:

```typescript
register({ context }) {
  const logger = context.getLogger().child({ svc: 'db' }); // ✅ safe to capture

  return {
    async query(sql: string) {
      logger.debug({ sql }, 'Executing query'); // logs to the CURRENT request
    },
  };
}
```

见 [文件/请求范围-logy.md](https://npmcn.com/package/%40geekmidas/services/docs/request-scoped-logging.md) 全文 问题描述( 和它防止的bug: 抓取的日志冻结第一个 请求的 `requestId` (对以后的每一个请求).

## 处理错误

优雅地处理服务初始化错误 :

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

      const db = new Kysely({ /* config */ });

      // Test connection
      await db.connection().execute('SELECT 1');

      return db;
    } catch (error) {
      throw new Error(`Failed to initialize database: ${error.message}`);
    }
  }
} satisfies Service<'database', Kysely<Database>>;
```

## 测试

测试中的模拟服务 :

```typescript
import { ServiceDiscovery } from '@geekmidas/services';
import { vi } from 'vitest';

// Create mock database
const mockDb = {
  selectFrom: vi.fn(() => ({
    where: vi.fn(() => ({
      selectAll: vi.fn(() => ({
        executeTakeFirstOrThrow: vi.fn().mockResolvedValue({
          id: '1',
          name: 'Test User'
        })
      }))
    }))
  }))
};

// Create mock service
const mockDatabaseService = {
  serviceName: 'database' as const,
  async register() {
    return mockDb;
  }
} satisfies Service<'database', typeof mockDb>;

// Use in tests
const serviceDiscovery = ServiceDiscovery.getInstance(logger, envParser);
const db = await serviceDiscovery.discover(mockDatabaseService);

// Test your code
```

## 服务模式

### 仓库模式

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

class UserRepository {
  constructor(private db: Kysely<Database>) {}

  async findById(id: string) {
    return this.db
      .selectFrom('users')
      .where('id', '=', id)
      .selectAll()
      .executeTakeFirst();
  }

  async create(data: NewUser) {
    return this.db
      .insertInto('users')
      .values(data)
      .returningAll()
      .executeTakeFirstOrThrow();
  }
}

const userRepositoryService = {
  serviceName: 'userRepository' as const,
  async register(envParser: EnvironmentParser<{}>) {
    const db = await databaseService.register(envParser);
    return new UserRepository(db);
  }
} satisfies Service<'userRepository', UserRepository>;
```

### 服务构成

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

class UserService {
  constructor(
    private repository: UserRepository,
    private email: EmailClient,
    private cache: Cache
  ) {}

  async createUser(data: NewUser) {
    const user = await this.repository.create(data);
    await this.email.sendTemplate('welcome', {
      to: user.email,
      props: { name: user.name }
    });
    await this.cache.set(`user:${user.id}`, user, 3600);
    return user;
  }
}

const userServiceService = {
  serviceName: 'userService' as const,
  async register(envParser: EnvironmentParser<{}>) {
    const repository = await userRepositoryService.register(envParser);
    const email = await emailService.register(envParser);
    const cache = await cacheService.register(envParser);

    return new UserService(repository, email, cache);
  }
} satisfies Service<'userService', UserService>;
```

## 类型脚本

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

// Service interface
interface Service<TName extends string = string, TInstance = unknown> {
  serviceName: TName;
  register(envParser: EnvironmentParser<{}>): Promise<TInstance> | TInstance;
}

// Infer service name
type ServiceName<T> = T extends Service<infer N, any> ? N : never;

// Infer service instance type
type ServiceInstance<T> = T extends Service<any, infer I> ? I : never;
```

## 最佳做法

### 1\. 用途 `satisfies` 类型安全

```typescript
// ✅ Use satisfies to ensure correct implementation
const service = {
  serviceName: 'myService' as const,
  async register(envParser) {
    return new MyService();
  }
} satisfies Service<'myService', MyService>;

// ❌ Don't use type annotation (loses type inference)
const service: Service = {
  serviceName: 'myService',
  async register(envParser) {
    return new MyService();
  }
};
```

### 2\. 用途 `as const` 用于服务名称

```typescript
// ✅ Literal type for better type inference
serviceName: 'database' as const

// ❌ String type loses specificity
serviceName: 'database'
```

### 3\. 验证配置

```typescript
async register(envParser: EnvironmentParser<{}>) {
  const config = envParser.create((get) => ({
    url: get('DATABASE_URL').string().url(), // Validates URL format
    port: get('PORT').string().transform(Number).default('5432'),
    ssl: get('SSL').string().transform(Boolean).default('false')
  })).parse();

  return new Database(config);
}
```

### 4\. 测试连接

```typescript
async register(envParser: EnvironmentParser<{}>) {
  const db = new Database(config);

  // Test connection during initialization
  await db.connection().execute('SELECT 1');

  return db;
}
```

## 相关软件包

-   [@geekmidas/ 构造](https://npmcn.com/package/%40geekmidas/constructs) - 依赖性注射服务
-   [@geekmidas/envkit (英语)](https://npmcn.com/package/%40geekmidas/envkit) - 服务的环境配置
-   [@ geekmidas/ logger (英语)](https://npmcn.com/package/%40geekmidas/logger) - 在服务部门内部进行记录
-   [@ geekmidas/ cache (笑声)](https://npmcn.com/package/%40geekmidas/cache) - 缓存服务
-   [@geekmidas/活动](https://npmcn.com/package/%40geekmidas/events) - 活动出版商服务

## 许可证

麻省理工学院

## 常见问题

### @geekmidas/services 是什么？

用于TypeScript应用的服务发现和依赖性注射系统,具有完全类型的安全和自动生命周期管理\.

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

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

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

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

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

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

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

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

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

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

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

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

