# @tars/dyeing

## @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

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tarscloud.gitbook.io/tarsdocs/tars.js/tars-dyeing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.