组件

组件是自包含的软件片段，被设计成黑盒：它们接收其他组件（或不接收任何组件）来完成自身任务。其主要目标是解耦代码段并最大化可测试性。

目录结构

所有组件 MUST 定义在一个专用目录中，该目录至少包含以下四个文件：

• component.ts - 包含组件的实现代码

• types.ts - 包含组件的接口和公开类型

• errors.ts - 包含所有导出的错误类

• index.ts - 导出组件的公共 API

示例结构

src/
└── components/
    └── my-component/
        ├── component.ts
        ├── types.ts
        ├── errors.ts
        └── index.ts

类型文件

组件遵循一个定义其公共 API 的接口。该接口可在可互换的组件之间共享，或用于了解组件公开的方法。

所有具有自己接口的组件 MUST 将其定义在组件目录中的一个 types.ts 文件里。

组件公开的其他类型也 MUST 放在此文件中。

示例： types.ts

export type Something = {
  aValue: boolean
  anotherValue: string
}

export interface IMyComponent {
  myFunction: () => boolean
  getSomething: () => Something
}

共享类型

多个组件之间共享的类型，例如通用接口，MUST 放在项目源代码根目录中的一个 types.ts 文件中（/src/types.ts).

组件文件

组件文件包含组件创建者函数。该函数遵循特定的命名和结构约定。

命名约定

组件创建者函数 MUST 命名为： create + 组件名称 + Component

示例： createMyNewComponent

函数签名

创建者函数 MUST：

1. 接收一个 components 对象作为第一个参数，其中包含所有依赖项

2. 可选地接收额外的配置参数

3. 返回一个包含公开（公共）方法的对象

组件结构

在组件创建者函数开始时：

1. 从 components 对象中提取依赖项

2. 初始化通用变量（例如日志记录器、配置）

3. 定义内部辅助函数

4. 定义公共方法

5. 返回公共 API

示例： component.ts

import { IMyComponent, Something } from './types'
import { WrongStringError } from './errors'

export function createMyNewComponent(
  components: Pick<AppComponents, 'logs'>
): IMyComponent {
  const { logs } = components
  const logger = logs.getLogger('my-component')

  // 内部方法 - 不对外暴露
  function computeString(fstString: string, sndString: string): string {
    if (fstString.length === 0) {
      throw new WrongStringError()
    }
    
    return fstString + ' ' + sndString
  }

  // 公共方法 - 在返回对象中暴露
  function myFunction(): boolean {
    return true
  }

  // 公共方法 - 在返回对象中暴露
  function getSomething(): Something {
    logger.info('正在获取某些内容')
    
    return {
      aValue: true,
      anotherValue: computeString('aString', 'anotherString')
    }
  }

  // 返回公共 API
  return {
    myFunction,
    getSomething
  }
}

错误文件

错误文件包含组件可以抛出的自定义错误类。这些错误可在其他组件或控制器中使用，以便正确识别并处理特定错误情况。

示例： errors.ts

export class WrongStringError extends Error {
  constructor(message?: string) {
    super(message || '字符串不正确')
    this.name = 'WrongStringError'
  }
}

export class ComponentNotInitializedError extends Error {
  constructor() {
    super('Component has not been initialized')
    this.name = 'ComponentNotInitializedError'
  }
}

错误处理最佳实践

• 为不同的错误情况创建特定的错误类

• 包含有意义的错误消息

• 将 名称 属性应与类名匹配，以便更轻松地调试

• 记录每个公共方法可能抛出的错误

索引文件

索引文件作为组件的公共入口点，仅导出应用程序其他部分应该能访问的内容。

示例： index.ts

export { createMyNewComponent } from './component'
export type { IMyComponent, Something } from './types'
export { WrongStringError } from './errors'

最佳实践

1. 单一职责 - 每个组件都应只有一个明确的用途

2. 显式依赖 - 所有依赖都应通过 components 参数注入

3. 不可变性 - 尽可能优先使用不可变数据结构

4. 错误处理 - 为不同的错误情况使用自定义错误类

5. 日志记录 - 使用日志记录器进行调试和监控

6. 类型安全 - 充分利用 TypeScript 的类型系统

7. 文档 - 记录复杂的方法和业务逻辑

组件生命周期

某些组件可能需要执行初始化或清理操作。WKC 提供了生命周期方法：

• [START_COMPONENT] - 在组件启动时调用

• [STOP_COMPONENT] - 在组件停止时调用

请参阅 适配器 使用生命周期方法的组件示例部分。