iidp \345\277\275\347\225\245\346\240\207\350\256\260\344\275\277\347\224\250\346\226\207\346\241\243.md
... ...
@@ -0,0 +1,198 @@
1
+# iidp 忽略标记使用文档
2
+
3
+## 1. 概述
4
+
5
+iidp 平台通过 `MetaConstant` 定义了一系列忽略标记，用于在特定业务场景下跳过框架默认行为（如逻辑删除、校验、审计日志等）。
6
+
7
+**核心原则**：所有忽略标记必须通过 `try-finally` 确保清理，防止标记泄漏影响后续请求。
8
+
9
+---
10
+
11
+## 2. 标准使用模式
12
+
13
+```java
14
+Meta meta = BaseContextHandler.getMeta();
15
+try {
16
+ // 1. 添加忽略标记
17
+ meta.addArgument(MetaConstant.XXX, true);
18
+
19
+ // 2. 执行业务操作
20
+
21
+} finally {
22
+ // 3. 必须清理标记
23
+ meta.getArguments().remove(MetaConstant.XXX);
24
+}
25
+```
26
+
27
+---
28
+
29
+## 3. 忽略标记清单
30
+
31
+| 标记常量 | 值 | 作用 | 使用场景 |
32
+| --------------------- | --------------------- | -------------------- | ----------------------------- |
33
+| `IGNORE_LOGIC_DELETE` | `"IgnoreLogicDelete"` | 跳过逻辑删除过滤 | 查询/更新已删除数据、数据恢复 |
34
+| `IGNORE_VALIDATE` | `"IgnoreValidate"` | 跳过数据校验 | 批量导入、系统初始化 |
35
+| `IGNORE_OPERATOR_LOG` | `"IgnoreOperatorLog"` | 跳过操作日志记录 | 高频批量操作、定时任务 |
36
+| `IGNORE_AUTO_LOG` | `"IgnoreAutoLog"` | 跳过审计字段自动填充 | 数据迁移、保留原始审计信息 |
37
+| `IGNORE_SCOPE` | `IS_IGNORE_SCOPE` | 跳过作用域/数据隔离 | 跨租户查询、管理员操作 |
38
+
39
+---
40
+
41
+## 4. 各标记详细示例
42
+
43
+### 4.1 IGNORE_LOGIC_DELETE - 跳过逻辑删除
44
+
45
+**场景**：查询或更新已被逻辑删除的数据（`delete_flag = '1'`）。
46
+
47
+```java
48
+Meta meta = BaseContextHandler.getMeta();
49
+try {
50
+ meta.addArgument(MetaConstant.IGNORE_LOGIC_DELETE, true);
51
+
52
+ TestUser testUser = new TestUser();
53
+ // 查询包含已删除的数据
54
+ List<TestUser> allUsers = testUser.search(null, null, null, null, null);
55
+
56
+} finally {
57
+ meta.getArguments().remove(MetaConstant.IGNORE_LOGIC_DELETE);
58
+}
59
+```
60
+
61
+---
62
+
63
+### 4.2 IGNORE_VALIDATE - 跳过数据校验
64
+
65
+**场景**：批量导入、系统初始化时跳过字段校验。
66
+
67
+```java
68
+Meta meta = BaseContextHandler.getMeta();
69
+try {
70
+ meta.addArgument(MetaConstant.IGNORE_VALIDATE, true);
71
+
72
+ TestUser user = new TestUser();
73
+ user.setName(""); // 空值，正常触发 @Validate.NotBlank
74
+ user.setAge(200); // 超过 @Validate.Max(110)
75
+ user.create(); // 不校验，直接插入
76
+
77
+} finally {
78
+ meta.getArguments().remove(MetaConstant.IGNORE_VALIDATE);
79
+}
80
+```
81
+
82
+---
83
+
84
+### 4.3 IGNORE_OPERATOR_LOG - 跳过操作日志
85
+
86
+**场景**：高频批量操作、定时任务，避免日志爆炸。
87
+
88
+```java
89
+Meta meta = BaseContextHandler.getMeta();
90
+try {
91
+ meta.addArgument(MetaConstant.IGNORE_OPERATOR_LOG, true);
92
+
93
+ TestUser testUser = new TestUser();
94
+ // 批量更新 10万条，不记录操作日志
95
+ for (List<TestUser> batch : batches) {
96
+ testUser.batchUpdate(batch);
97
+ }
98
+
99
+} finally {
100
+ meta.getArguments().remove(MetaConstant.IGNORE_OPERATOR_LOG);
101
+}
102
+```
103
+
104
+---
105
+
106
+### 4.4 IGNORE_AUTO_LOG - 跳过审计字段
107
+
108
+**场景**：数据迁移、保留原始创建人/时间。
109
+
110
+```java
111
+Meta meta = BaseContextHandler.getMeta();
112
+try {
113
+ meta.addArgument(MetaConstant.IGNORE_AUTO_LOG, true);
114
+
115
+ TestUser user = new TestUser();
116
+ user.set("create_user", "old_system"); // 保留原始创建人
117
+ user.set("create_date", "2020-01-01"); // 保留原始创建时间
118
+ user.create(); // 不自动填充审计字段
119
+
120
+} finally {
121
+ meta.getArguments().remove(MetaConstant.IGNORE_AUTO_LOG);
122
+}
123
+```
124
+
125
+---
126
+
127
+### 4.5 IGNORE_SCOPE - 跳过作用域/数据隔离
128
+
129
+**场景**：跨租户查询、管理员查看全局数据。
130
+
131
+```java
132
+Meta meta = BaseContextHandler.getMeta();
133
+try {
134
+ meta.addArgument(MetaConstant.IGNORE_SCOPE, true);
135
+
136
+ TestUser testUser = new TestUser();
137
+ // 查询所有租户的数据
138
+ List<TestUser> allTenantUsers = testUser.search(null, null, null, null, null);
139
+
140
+} finally {
141
+ meta.getArguments().remove(MetaConstant.IGNORE_SCOPE);
142
+}
143
+```
144
+
145
+---
146
+
147
+## 5. 组合使用示例
148
+
149
+**场景**：数据迁移 - 忽略逻辑删除、校验、审计日志。
150
+
151
+```java
152
+Meta meta = BaseContextHandler.getMeta();
153
+try {
154
+ // 组合添加多个标记
155
+ meta.addArgument(MetaConstant.IGNORE_LOGIC_DELETE, true);
156
+ meta.addArgument(MetaConstant.IGNORE_VALIDATE, true);
157
+ meta.addArgument(MetaConstant.IGNORE_AUTO_LOG, true);
158
+ meta.addArgument(MetaConstant.IGNORE_OPERATOR_LOG, true);
159
+
160
+ // 执行数据迁移
161
+ for (Map<String, Object> row : migrateData) {
162
+ TestUser user = new TestUser();
163
+ user.setMap(row);
164
+ user.create();
165
+ }
166
+
167
+} finally {
168
+ // 必须全部清理
169
+ meta.getArguments().remove(MetaConstant.IGNORE_LOGIC_DELETE);
170
+ meta.getArguments().remove(MetaConstant.IGNORE_VALIDATE);
171
+ meta.getArguments().remove(MetaConstant.IGNORE_AUTO_LOG);
172
+ meta.getArguments().remove(MetaConstant.IGNORE_OPERATOR_LOG);
173
+}
174
+```
175
+
176
+---
177
+
178
+## 6. 注意事项
179
+
180
+| 注意点 | 说明 |
181
+| -------------------- | ------------------------------------------------ |
182
+| **必须 try-finally** | 标记存储在 `Meta` 上下文中，不清理会影响后续请求 |
183
+| **最小化作用范围** | 尽量缩小 try 块范围，减少标记生效时间 |
184
+| **避免滥用** | 忽略校验/日志会绕过安全机制，需评估风险 |
185
+| **组合使用** | 多个标记同时使用时，finally 中需全部清理 |
186
+
187
+---
188
+
189
+## 7. 完整常量定义
190
+
191
+```java
192
+// MetaConstant.java
193
+public final static String IGNORE_SCOPE = IS_IGNORE_SCOPE; // "IsIgnoreScope"
194
+public final static String IGNORE_VALIDATE = "IgnoreValidate"; // "IgnoreValidate"
195
+public final static String IGNORE_LOGIC_DELETE = "IgnoreLogicDelete"; // "IgnoreLogicDelete"
196
+public final static String IGNORE_OPERATOR_LOG = "IgnoreOperatorLog"; // "IgnoreOperatorLog"
197
+public final static String IGNORE_AUTO_LOG = "IgnoreAutoLog"; // "IgnoreAutoLog"
198
+```
... ...
\ No newline at end of file