|
| 1 | +# Reply 模块中文说明文档 |
| 2 | + |
| 3 | + |
| 4 | + |
| 5 | +## 1. 代码架构 |
| 6 | + |
| 7 | +### 树形图 |
| 8 | + |
| 9 | +``` |
| 10 | +reply_module/ |
| 11 | +├── reply.py |
| 12 | +├── reply_factory.py |
| 13 | +├── reply_target/ |
| 14 | +│ ├── dingtalk_reply.py |
| 15 | +│ ├── gitlab_reply.py |
| 16 | +│ └── 更多自定义reply |
| 17 | +└── abstract_reply.py |
| 18 | +``` |
| 19 | + |
| 20 | +### 文件功能简要说明 |
| 21 | + |
| 22 | +- **reply.py**: 主要负责回复消息的管理和发送逻辑。包括添加回复消息、发送所有消息以及实时发送单条消息。 |
| 23 | +- **reply_factory.py**: 实现了回复目标的工厂模式，用于创建不同类型的回复实例。 |
| 24 | +- **abstract_reply.py**: 定义了一个抽象基类 `AbstractReply`，所有具体的回复类型都需要继承这个基类并实现其抽象方法,即**开发者需要通过继承此类来实现添加新Reply**。 |
| 25 | +- **reply_target/**: 存放具体的回复实现类，例如 `dingtalk_reply.py` 和 `gitlab_reply.py`，**自定义的回复类可以放于此处**。 |
| 26 | + |
| 27 | +## 2. 如何添加自定义的通知方式 |
| 28 | + |
| 29 | +>> 🚀 **增强功能**: 添加新的通知方式可以扩展系统的功能，使项目能够支持更多的消息发送平台。例如，除了现有的 Gitlab 和 Dingtalk 外，还可以添加对 Slack、Email 或其他平台的支持。 |
| 30 | +
|
| 31 | +### 步骤详细说明 |
| 32 | + |
| 33 | +1. **创建新的 Reply 类** |
| 34 | + |
| 35 | + * 在 `reply_target` 目录下创建一个新的 Python 文件，例如 `slack_reply.py`。 |
| 36 | + * 文件中新建一个Reply类，例如`SlackReply`，并实现`AbstractReply`类，示例如下： |
| 37 | + |
| 38 | + ```python |
| 39 | + from reply_module.abstract_reply import AbstractReply |
| 40 | + |
| 41 | + class SlackReply(AbstractReply): |
| 42 | + def __init__(self, config): |
| 43 | + self.config = config |
| 44 | + |
| 45 | + def send(self, message): |
| 46 | + # 这里实现发送消息到 Slack 的逻辑 |
| 47 | + print(f"Sending message to Slack: {message}") |
| 48 | + return True |
| 49 | + ``` |
| 50 | + |
| 51 | + * config 主要包含了需要处理的请求的类型（`type`），如 `merge_request`，`push`等，参见[Config参数说明](#31-config)。 |
| 52 | + * message 为`String`，内容为要发送的信息。 |
| 53 | + |
| 54 | +2. **将新的 Reply 类添加到工厂中** |
| 55 | + |
| 56 | + 在 `reply_factory.py` 文件中注册新的 Reply 类： |
| 57 | + |
| 58 | + ```python |
| 59 | + from reply_module.reply_target.slack_reply import SlackReply |
| 60 | + |
| 61 | + ReplyFactory.register_target('slack', SlackReply) |
| 62 | + ``` |
| 63 | + |
| 64 | + 这样，工厂类 `ReplyFactory` 就可以自动创建新的 `SlackReply` 实例了。 |
| 65 | + |
| 66 | +3. **使用自定义类** |
| 67 | + |
| 68 | + 可以在自定义的Handle中使用新定义的类，使用方法参考使用示例。 |
| 69 | + |
| 70 | +## 3. 参数说明 |
| 71 | + |
| 72 | +### 3.1 Config |
| 73 | + |
| 74 | +#### 3.1.1 功能 |
| 75 | + |
| 76 | +`config` 是一个字典，包含了初始化 Reply 实例时需要的配置信息。其功能如下： |
| 77 | + |
| 78 | +1. **说明当前 Hook 的类型**: 如 `merge_request`，`push` 等。 |
| 79 | +2. **包含项目的参数**: 如 `project_id`，`merge_request_iid` 等。 |
| 80 | + |
| 81 | +#### 3.1.2 格式 |
| 82 | + |
| 83 | +##### 基本格式 |
| 84 | + |
| 85 | +- `type`: 每个 `config` 一定包含该参数，根据 `type` 的不同，其他参数会有所不同。 |
| 86 | +- **目前项目只会有 `merge_request` 一种 `type`，其他事件加急开发中**。 |
| 87 | + |
| 88 | +```python |
| 89 | +config = { |
| 90 | + "type": "merge_request" |
| 91 | + # 其他参数 |
| 92 | +} |
| 93 | +``` |
| 94 | + |
| 95 | +##### merge_request 事件 |
| 96 | + |
| 97 | +- `project_id`: |
| 98 | + - 类型: `int` |
| 99 | + - 说明: 项目的唯一标识符，用于标识具体的项目。 |
| 100 | + |
| 101 | +- `merge_request_iid`: |
| 102 | + - 类型: `int` |
| 103 | + - 说明: 合并请求的唯一标识符，用于标识具体的合并请求。 |
| 104 | + |
| 105 | + |
| 106 | +```python |
| 107 | +config = { |
| 108 | + "type": "merge_request", |
| 109 | + "project_id": 95536, # 项目ID |
| 110 | + "merge_request_iid": 10 # 合并请求IID |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +### 3.2 Reply Message (reply_msg) |
| 115 | + |
| 116 | +#### 3.2.1 功能 |
| 117 | + |
| 118 | +`reply_msg` 是一个字典，包含了发送消息时所需的信息。其功能如下： |
| 119 | + |
| 120 | +1. **包含消息的实际内容**: 如消息的文本内容、标题等。 |
| 121 | +2. **定义消息的类型**: 如 `MAIN`，`TITLE_IGNORE`，`SINGLE`，`NORM` 等。 |
| 122 | +3. **分组消息**: 通过 `group_id` 将相同组的消息一起发送。 |
| 123 | + |
| 124 | +#### 3.2.2 格式 |
| 125 | + |
| 126 | +##### 基本格式 |
| 127 | + |
| 128 | +- `content`: 每个 `reply_msg` 一定包含该参数，表示消息的实际内容。 |
| 129 | +- `title`: 可选参数，表示消息的标题。 |
| 130 | +- `msg_type`: 表示消息的类型，默认值为 `NORM`。 |
| 131 | +- ``target``：标识发送给哪些平台，默认为``all`` |
| 132 | +- `group_id`: 表示消息的分组ID，默认值为 `0`。 |
| 133 | + |
| 134 | +```python |
| 135 | +reply_msg = { |
| 136 | + "content": "This is a message content", |
| 137 | + "title": "Optional Title", |
| 138 | + "msg_type": "NORM", |
| 139 | + "target": "all", |
| 140 | + "group_id": 0 |
| 141 | +} |
| 142 | +``` |
| 143 | + |
| 144 | +##### 字段说明 |
| 145 | + |
| 146 | +- `content`: |
| 147 | + - 类型: `str` |
| 148 | + - 说明: 必须包含的字段，表示消息的实际内容。 |
| 149 | + |
| 150 | +- `title`: |
| 151 | + - 类型: `str` |
| 152 | + - 说明: 可选字段，表示消息的标题，如果无此字段或内容为空，则等同于``msg_type``为``TITLE_IGNORE``。 |
| 153 | + |
| 154 | +- `msg_type`: |
| 155 | + - 类型: `str` |
| 156 | + - 说明: 表示消息的类型, 可以为多个类型，通过逗号``,``分割。默认值为 `NORM`，可选值包括： |
| 157 | + - `MAIN`: 标识主消息，要求唯一，项目自带handle默认使用。 |
| 158 | + - `TITLE_IGNORE`: 忽略标题，即只发送内容。 |
| 159 | + - `SINGLE`: 直接发送单条消息。 |
| 160 | + - `NORMAL`: 正常消息类型，等待所有handle处理完成后拼接成一条消息发送。 |
| 161 | + |
| 162 | +- ``target``： |
| 163 | + - 类型：``str`` |
| 164 | + - 说明：标识调用哪些Reply通知类进行·发送，可以同时选择多个Reply，通过逗号``,``分割。默认值为 `all`，可选值包括： |
| 165 | + - ``all``：发送给所有在``reply_factory.py``中注册过的Reply通知类。 |
| 166 | + - ``gitlab``：发送给gitlab平台，即在merge界面发送comment |
| 167 | + - ``dingtalk``：配置好钉钉机器人后，可以通过机器人发送到钉钉 |
| 168 | + - ``自定义``：可以参考上文自定义Reply并在``reply_factory.py``中注册，然后可以使用自定义的通知类。 |
| 169 | +- `group_id`: |
| 170 | + - 类型: `int` |
| 171 | + - 说明: 表示消息的分组ID。相同 `group_id` 的消息会一起发送。默认值为 `0`。 |
| 172 | +- |
| 173 | + |
| 174 | +##### 示例 |
| 175 | + |
| 176 | +```python |
| 177 | +reply_msg = { |
| 178 | + "content": "This is the main content of the message.", |
| 179 | + "title": "Important Update", |
| 180 | + "msg_type": "MAIN, SINGLE", |
| 181 | + "target": "dingtalk, gitlab", |
| 182 | + "group_id": 1 |
| 183 | +} |
| 184 | +``` |
| 185 | + |
| 186 | +在上述示例中，`reply_msg` 包含了一个主要类型的消息，带有标题，并且属于组 `1`。 |
| 187 | + |
| 188 | +## 4. 其他说明 |
| 189 | + |
| 190 | +### 示例代码 |
| 191 | + |
| 192 | +以下是一个简单的使用示例： |
| 193 | + |
| 194 | +```python |
| 195 | +from reply_module.reply import Reply |
| 196 | + |
| 197 | +# 配置字典 |
| 198 | +config = { |
| 199 | + 'type': 'merge_request', |
| 200 | + 'project_id': 9885, |
| 201 | + 'merge_request_iid': 18 |
| 202 | +} |
| 203 | + |
| 204 | +# 创建 Reply 实例 |
| 205 | +reply = Reply(config) |
| 206 | + |
| 207 | +# 添加回复消息 |
| 208 | +reply.add_reply({ |
| 209 | + "target": "slack", |
| 210 | + "content": "This is a test message", |
| 211 | + "title": "Test Title", |
| 212 | + "msg_type": "NORM", |
| 213 | + "group_id": 0 |
| 214 | +}) |
| 215 | + |
| 216 | +# 发送所有消息 |
| 217 | +success = reply.send() |
| 218 | +print(f"Messages sent successfully: {success}") |
| 219 | +``` |
| 220 | + |
| 221 | +通过以上步骤和示例代码，您可以轻松地在项目中添加和使用新的回复类型。 |
| 222 | + |
0 commit comments