# dyeing

**Repository Path**: tars-node/dyeing

## Basic Information

- **Project Name**: dyeing
- **Description**: TARS 染色基础模块
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2019-09-13
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @tars/dyeing

TARS 染色基础模块，提供获取与判断 `染色对象` 的方法。

__使用者：不应该直接使用此模块，而应使用其他符合 `染色标准` 的模块获取 `染色对象`__

__模块开发者：获取 `TARS染色对象` 应使用此模块的 `gen()` 方法获取 `染色对象`__

## 染色（简介）

染色是在接口的调用链（服务端 <==> 客户端）上传递的一种状态，用于标识一次特定的请求处理过程。

这种状态由一个 标志位 与 附加信息 `KEY` _（可选）_ 构成。

调用链上的服务可以设置（发起）与读取（接收）这种状态，并作对应的处理（如输出特定的日志、特性）。

在系统中，染色由此模块与其对应的约定构成。 

## 标准（约定）

如模块使用染色体系，则需遵守如下约定（与此同时，我们将符合约定的模块称之为符合 `染色标准` 的模块）：

1. 提供 `getDyeingObj()` 方法，返回 `染色对象`。
2. 通过 `@tars/dyeing.gen` 方法，生成 `染色对象`。
3. 通过 `@tars/dyeing.is()` 方法，判断 `染色对象` 是否有效。

## 模块方法

### TarsDyeing.gen(dyeing[, key, args])

通过调用此方法，可获得 `染色对象`：

__dyeing__: 是否需要染色  
__key__: 染色附加信息 `KEY`（可选）  
__args__: 程序的附加参数（可选）

`key` 会通过调用链传递给下一个服务，而 `args` 仅只会在当前的染色对象中有效（并不会进行传递）。

__请注意：染色对象 与 染色发起原因，这是不同的（东西）。此模块仅关心 染色对象，而不关心 染色发起原因。__

### TarsDyeing.is(obj)

调用此方法，可以判断 一个传入的对象是否是 `染色对象`：

如传入空对象，方法同样会返回 `false`

## 染色对象 属性

### dyeingObj.dyeing

是否需要染色，此为 `Boolean`

### dyeingObj.key

染色传递的附加信息，此为 `String` 且为可选值，不一定存在

### dyeingObj.args

染色对象本身的附加信息，业务代码不应将其在服务间进行传递（仅作为本地参数使用）。

此对象类型不限，同时也为可选值