@geekmidas/services

中文文档
9.6.1发布于 2026/11/16TypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 1.5万

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

中文使用文档
文档目录29 节
  1. 特征
  2. 安装
  3. 快速启动
  4. 定义服务
  5. 在构造中使用服务
  6. 服务发现
  7. 创建服务
  8. 数据库服务
  9. Redis/缓存服务
  10. 电子邮件服务
  11. 事件出版服务
  12. 多种服务
  13. 服务周期
  14. 懒惰初始化
  15. 单子图案
  16. 请求范围日志
  17. 处理错误
  18. 测试
  19. 服务模式
  20. 仓库模式
  21. 服务构成
  22. 类型脚本
  23. 最佳做法
  24. 1. 用途 satisfies 类型安全
  25. 2. 用途 as const 用于服务名称
  26. 3. 验证配置
  27. 4. 测试连接
  28. 相关软件包
  29. 许可证

@geekmidas/服务

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

特征

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

安装

pnpm add @geekmidas/services

快速启动

定义服务

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

在构造中使用服务

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;
  });

服务发现

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

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

创建服务

数据库服务

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/缓存服务

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

电子邮件服务

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

事件出版服务

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

多种服务

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

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;
  });

服务周期

懒惰初始化

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

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

单子图案

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

// 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() 继续日志 反对正确的要求:

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 全文 问题描述( 和它防止的bug: 抓取的日志冻结第一个 请求的 requestId (对以后的每一个请求).

处理错误

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

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

测试

测试中的模拟服务 :

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

服务模式

仓库模式

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

服务构成

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

类型脚本

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 类型安全

// ✅ 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 用于服务名称

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

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

3. 验证配置

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. 测试连接

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

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

  return db;
}

许可证

麻省理工学院

版本与发布记录

@geekmidas/services 共发布 206 个版本,首次发布于 2025/10/20;过去 12 个月发布了 205 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
9.6.1latest2026/11/16今天
10.0.0-alpha.185alpha2026/11/16今天
10.0.0-alpha.1842026/11/16今天
10.0.0-alpha.1832026/11/16今天
10.0.0-alpha.1822026/11/132 天前
10.0.0-alpha.1812026/11/133 天前

关于 @geekmidas/services 的常见问题

@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 和提交记录判断。