typed-service-contracts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Typed Service Contracts (Spec & Handler Pattern)

类型化服务契约（Spec & Handler模式）

This skill defines a Vertical Slice Architecture backed by Design by Contract (DbC) principles. It treats application logic as rigorously defined Units of Work where inputs are parsed (not just validated) and errors are treated as values (Result Pattern) rather than exceptions.

该技能定义了一种基于契约式设计（DbC）原则的垂直切片架构。它将应用逻辑视为严格定义的工作单元，其中输入会被解析（而非仅验证），错误被当作值（结果模式）而非异常处理。

When to use this skill

何时使用该技能

Building CLIs or Libraries: When you need strict boundaries between user input and system logic.
Complex Validation: When inputs require transformation (parsing) before being useful (e.g., ensuring a string is a valid file path).
High-Reliability Requirements: When you cannot afford unhandled runtime exceptions and need exhaustive error handling.
Testing Focus: When you want to separate data validation tests from business logic tests.

构建CLI或库： 当你需要在用户输入与系统逻辑之间建立严格边界时。
复杂验证场景： 当输入需要经过转换（解析）才能生效时（例如，确保字符串是有效的文件路径）。
高可靠性要求： 当你无法承受未处理的运行时异常，需要全面的错误处理时。
测试聚焦： 当你希望将数据验证测试与业务逻辑测试分离时。

Architecture Components

架构组件

1. The Spec (

spec.ts

)

1. Spec（

spec.ts

）

The "Contract" or "Port". It defines the What. It must contain:

Input Schema: A Zod schema that parses raw input into a valid DTO.
Output Schema: A Zod schema defining the successful data structure.
Error Schema: A discriminated union of specific failure modes (not generic errors).
Result Type: A
```
DiscriminatedUnion
```
of
```
Success | Failure
```
.
Interface: The capability definition (e.g.,
```
interface ConfigureSpec
```
).

即“契约”或“端口”。它定义了做什么。必须包含：

输入Schema： 一个Zod schema，用于将原始输入解析为有效的DTO。
输出Schema： 定义成功数据结构的Zod schema。
错误Schema： 特定失败模式的可区分联合类型（而非通用错误）。
结果类型：
```
Success | Failure
```
的
```
DiscriminatedUnion
```
类型。
接口： 能力定义（例如，
```
interface ConfigureSpec
```
）。

2. The Handler (

handler.ts

)

2. Handler（

handler.ts

）

The "Implementation" or "Adapter". It defines the How. It must:

Implement the Interface defined in the Spec.
Be an "Impure" class that handles side effects (File System, API calls).
NEVER throw exceptions. It must catch internal errors and map them to the
```
Result
```
type.

即“实现”或“适配器”。它定义了怎么做。必须：

实现Spec中定义的接口。
是一个处理副作用（文件系统、API调用）的“不纯”类。
绝不抛出异常。必须捕获内部错误并将其映射为
```
Result
```
类型。

How to use it

使用方法

Step 1: Define the Contract (

spec.ts

)

步骤1：定义契约（

spec.ts

）

Follow this template to define the boundaries.

typescript

import { z } from 'zod';

// 1. VALIDATION HELPERS (Reusable Refinements)
export const SafePathSchema = z.string()
  .min(1)
  .refine(p => !p.includes('..'), "No traversal allowed");

// 2. INPUT (The Command) - "Parse, don't validate"
export const MyTaskInputSchema = z.object({
  path: SafePathSchema,
  force: z.boolean().default(false),
});
export type MyTaskInput = z.infer<typeof MyTaskInputSchema>;

// 3. ERROR CODES (Exhaustive)
export const MyTaskErrorCode = z.enum([
  'FILE_NOT_FOUND',
  'PERMISSION_DENIED', 
  'UNKNOWN_ERROR'
]);

// 4. RESULT (The Monad)
export const MyTaskSuccess = z.object({
  success: z.literal(true),
  data: z.string(), // The output payload
});

export const MyTaskFailure = z.object({
  success: z.literal(false),
  error: z.object({
    code: MyTaskErrorCode,
    message: z.string(),
    suggestion: z.string().optional(),
    recoverable: z.boolean(),
  })
});

export type MyTaskResult = 
  | z.infer<typeof MyTaskSuccess> 
  | z.infer<typeof MyTaskFailure>;

// 5. INTERFACE (The Capability)
export interface MyTaskSpec {
  execute(input: MyTaskInput): Promise<MyTaskResult>;
}

遵循以下模板定义边界。

typescript

import { z } from 'zod';

// 1. VALIDATION HELPERS (Reusable Refinements)
export const SafePathSchema = z.string()
  .min(1)
  .refine(p => !p.includes('..'), "No traversal allowed");

// 2. INPUT (The Command) - "Parse, don't validate"
export const MyTaskInputSchema = z.object({
  path: SafePathSchema,
  force: z.boolean().default(false),
});
export type MyTaskInput = z.infer<typeof MyTaskInputSchema>;

// 3. ERROR CODES (Exhaustive)
export const MyTaskErrorCode = z.enum([
  'FILE_NOT_FOUND',
  'PERMISSION_DENIED', 
  'UNKNOWN_ERROR'
]);

// 4. RESULT (The Monad)
export const MyTaskSuccess = z.object({
  success: z.literal(true),
  data: z.string(), // The output payload
});

export const MyTaskFailure = z.object({
  success: z.literal(false),
  error: z.object({
    code: MyTaskErrorCode,
    message: z.string(),
    suggestion: z.string().optional(),
    recoverable: z.boolean(),
  })
});

export type MyTaskResult = 
  | z.infer<typeof MyTaskSuccess> 
  | z.infer<typeof MyTaskFailure>;

// 5. INTERFACE (The Capability)
export interface MyTaskSpec {
  execute(input: MyTaskInput): Promise<MyTaskResult>;
}

Step 2: Implement the Handler (

handler.ts

)

步骤2：实现Handler（

handler.ts

）

Follow this template to implement the logic.

typescript

import { MyTaskSpec, MyTaskInput, MyTaskResult } from './spec.js';
import * as fs from 'fs';

export class MyTaskHandler implements MyTaskSpec {
  async execute(input: MyTaskInput): Promise<MyTaskResult> {
    try {
      // 1. Business Logic
      if (!fs.existsSync(input.path)) {
        // 2. Explicit Error Return (No Throwing)
        return {
          success: false,
          error: {
            code: 'FILE_NOT_FOUND',
            message: `Path does not exist: ${input.path}`,
            recoverable: true
          }
        };
      }

      // 3. Success Return
      return {
        success: true,
        data: 'Operation complete'
      };

    } catch (error) {
      // 4. Safety Net: Catch unknown runtime errors
      return {
        success: false,
        error: {
          code: 'UNKNOWN_ERROR',
          message: error instanceof Error ? error.message : String(error),
          recoverable: false
        }
      };
    }
  }
}

遵循以下模板实现逻辑。

typescript

import { MyTaskSpec, MyTaskInput, MyTaskResult } from './spec.js';
import * as fs from 'fs';

export class MyTaskHandler implements MyTaskSpec {
  async execute(input: MyTaskInput): Promise<MyTaskResult> {
    try {
      // 1. Business Logic
      if (!fs.existsSync(input.path)) {
        // 2. Explicit Error Return (No Throwing)
        return {
          success: false,
          error: {
            code: 'FILE_NOT_FOUND',
            message: `Path does not exist: ${input.path}`,
            recoverable: true
          }
        };
      }

      // 3. Success Return
      return {
        success: true,
        data: 'Operation complete'
      };

    } catch (error) {
      // 4. Safety Net: Catch unknown runtime errors
      return {
        success: false,
        error: {
          code: 'UNKNOWN_ERROR',
          message: error instanceof Error ? error.message : String(error),
          recoverable: false
        }
      };
    }
  }
}

Step 3: Testing Strategy

步骤3：测试策略

Do not write monolithic tests. Split them into Contract Tests and Logic Tests.

不要编写单体测试。将测试拆分为契约测试和逻辑测试。

A. Contract Tests (Schema)

A. 契约测试（Schema）

Test the Bouncer. Ensure invalid data is rejected before it reaches the handler.

Focus: Edge cases, validation rules, Zod refinements.
Style: Data-driven (Table tests).

typescript

// spec.test.ts
import { MyTaskInputSchema } from './spec';

const invalidCases = [
  { val: '../etc/passwd', err: 'No traversal allowed' },
  { val: '', err: 'min(1)' },
];

test.each(invalidCases)('validates paths', ({ val, err }) => {
  const result = MyTaskInputSchema.safeParse({ path: val });
  expect(result.success).toBe(false);
});

测试“守门人”。确保无效数据在到达Handler之前被拒绝。

重点： 边缘情况、验证规则、Zod refinements。
风格： 数据驱动（表格测试）。

typescript

// spec.test.ts
import { MyTaskInputSchema } from './spec';

const invalidCases = [
  { val: '../etc/passwd', err: 'No traversal allowed' },
  { val: '', err: 'min(1)' },
];

test.each(invalidCases)('validates paths', ({ val, err }) => {
  const result = MyTaskInputSchema.safeParse({ path: val });
  expect(result.success).toBe(false);
});

B. Logic Tests (Handler)

B. 逻辑测试（Handler）

Test the Chef. Mock external dependencies (fs, network) and assert the Result Object.

Focus: Business logic flow, error mapping, success states.
Style: Mocked unit tests or Scenario Runners.

typescript

// handler.test.ts
import { MyTaskHandler } from './handler';
import { vi } from 'vitest'; // or jest

test('returns FILE_NOT_FOUND if path missing', async () => {
  // MOCK
  vi.mocked(fs.existsSync).mockReturnValue(false);
  
  // EXECUTE
  const handler = new MyTaskHandler();
  const result = await handler.execute({ path: '/fake' });

  // ASSERT (Check the Result Object)
  expect(result.success).toBe(false);
  if (!result.success) {
    expect(result.error.code).toBe('FILE_NOT_FOUND');
  }
});

测试“执行者”。模拟外部依赖（文件系统、网络）并断言结果对象。

重点： 业务逻辑流程、错误映射、成功状态。
风格： 模拟单元测试或场景运行器。

typescript

// handler.test.ts
import { MyTaskHandler } from './handler';
import { vi } from 'vitest'; // or jest

test('returns FILE_NOT_FOUND if path missing', async () => {
  // MOCK
  vi.mocked(fs.existsSync).mockReturnValue(false);
  
  // EXECUTE
  const handler = new MyTaskHandler();
  const result = await handler.execute({ path: '/fake' });

  // ASSERT (Check the Result Object)
  expect(result.success).toBe(false);
  if (!result.success) {
    expect(result.error.code).toBe('FILE_NOT_FOUND');
  }
});

typed-service-contracts

Original

Translation

Typed Service Contracts (Spec & Handler Pattern)

类型化服务契约（Spec & Handler模式）

When to use this skill

何时使用该技能

Architecture Components

架构组件

1. The Spec (
`spec.ts`
)

1. Spec（
`spec.ts`
）

2. The Handler (
`handler.ts`
)

2. Handler（
`handler.ts`
）

How to use it

使用方法

Step 1: Define the Contract (
`spec.ts`
)

步骤1：定义契约（
`spec.ts`
）

Step 2: Implement the Handler (
`handler.ts`
)

步骤2：实现Handler（
`handler.ts`
）

Step 3: Testing Strategy

步骤3：测试策略

A. Contract Tests (Schema)

A. 契约测试（Schema）

B. Logic Tests (Handler)

B. 逻辑测试（Handler）

typed-service-contracts

Original

Translation

Typed Service Contracts (Spec & Handler Pattern)

类型化服务契约（Spec & Handler模式）

When to use this skill

何时使用该技能

Architecture Components

架构组件

1. The Spec (spec.ts)

1. Spec（spec.ts）

2. The Handler (handler.ts)

2. Handler（handler.ts）

How to use it

使用方法

Step 1: Define the Contract (spec.ts)

步骤1：定义契约（spec.ts）

Step 2: Implement the Handler (handler.ts)

步骤2：实现Handler（handler.ts）

Step 3: Testing Strategy

步骤3：测试策略

A. Contract Tests (Schema)

A. 契约测试（Schema）

B. Logic Tests (Handler)

B. 逻辑测试（Handler）

1. The Spec (
`spec.ts`
)

1. Spec（
`spec.ts`
）

2. The Handler (
`handler.ts`
)

2. Handler（
`handler.ts`
）

Step 1: Define the Contract (
`spec.ts`
)

步骤1：定义契约（
`spec.ts`
）

Step 2: Implement the Handler (
`handler.ts`
)

步骤2：实现Handler（
`handler.ts`
）