orm-ignore.md
... ...
@@ -0,0 +1,205 @@
1
+# 跳过ORM的默认行为
2
+
3
+## 1. 跳过作用域过滤
4
+
5
+引擎提供了两种在业务操作中临时跳过作用域过滤的方法。以下是具体的实现方式和代码示例，以确保在执行特定业务操作时能够忽略作用域限制，并在操作完成后正确清理上下文，避免对后续操作产生影响。
6
+
7
+### 1.1 整个方法体及其调用链路都忽略作用域过滤
8
+
9
+#### 实现说明
10
+
11
+1. **设置忽略作用域标记**：在业务方法开始执行前，通过`meta.getContext().put(MetaConstant.IGNORE_SCOPE, true)`将忽略作用域的标记添加到上下文中。这样整个方法体及其所有调用链路都会跳过作用域过滤。
12
+2. **执行业务操作**：在设置忽略标记后，执行需要跳过作用域过滤的业务逻辑。
13
+3. **清理作用域标记**：无论业务操作成功与否，都应在方法结束时清理作用域标记，确保系统恢复正常的作用域过滤状态。
14
+
15
+**示例代码**
16
+
17
+```java
18
+@MethodService(name = "getById", auth = "read")
19
+public TestUser testIgnoreScope(String id) {
20
+ Meta meta = BaseContextHandler.getMeta();
21
+ try {
22
+ meta.getContext().put(MetaConstant.IGNORE_SCOPE, true);
23
+ RecordSet rs = meta.get("TestUser");
24
+ // 整个方法体包含调用链路会忽略作用域过滤
25
+ TestUser results = (TestUser)rs.call("getOrgByUserId", id);
26
+ } finally {
27
+ meta.getContext().remove(MetaConstant.IGNORE_SCOPE);
28
+ }
29
+ // 此处作用域过滤会重新生效
30
+ return selectById(id);
31
+}
32
+```
33
+
34
+**注意事项**
35
+
36
+- **必须使用try-finally结构**：确保无论业务操作是否异常，都能执行清理标记的代码
37
+- **谨慎使用**：仅在确实需要时使用，避免潜在的安全风险
38
+- **作用范围**：此方式会影响当前方法及所有嵌套调用的作用域过滤
39
+
40
+### 1.2 单次调用忽略作用域过滤
41
+
42
+#### 实现说明
43
+
44
+有时只需要在单次方法调用中跳过作用域过滤，调用结束后立即恢复。这种方法适用于需要在特定操作中临时跳过作用域检查，但不希望影响后续操作的情况。
45
+
46
+1. **添加临时参数**：通过`meta.addArgument(MetaConstant.IGNORE_SCOPE, true)`添加跳过作用域的临时参数
47
+2. **执行业务操作**：执行需要跳过作用域过滤的操作
48
+3. **参数自动清理**：由于是临时参数，方法执行完毕后会自动清理，无需手动移除
49
+
50
+**示例代码**
51
+
52
+```java
53
+@MethodService(name = "getOrgByUserId")
54
+public TestUser getOrgByUserId(String id) {
55
+ TestUser testUser = new TestUser();
56
+ testUser.setId(id);
57
+
58
+ // 第一次添加跳过参数
59
+ BaseContextHandler.getMeta().addArgument(MetaConstant.IGNORE_SCOPE, true);
60
+ TestOrg testOrg = testUser.getOrg();
61
+ testOrg.search(Filter.greater("age", 10), Arrays.asList("*"), null, null, null);
62
+
63
+ // 第二次添加跳过参数（每次调用前都需要重新添加）
64
+ BaseContextHandler.getMeta().addArgument(MetaConstant.IGNORE_SCOPE, true);
65
+ testUser.search(Filter.greater("age", 10), Arrays.asList("*"), null, null, null);
66
+
67
+ return testUser.selectById(id);
68
+}
69
+```
70
+
71
+**注意事项**
72
+
73
+- **参数的有效性**：参数仅对当前调用有效，每次需要跳过的操作前都需要重新添加
74
+- **独立性**：每次方法调用都是独立的，参数的添加和清理不会影响其他调用
75
+
76
+## 2. 跳过逻辑删除过滤
77
+
78
+在业务场景中，有时需要查询已被逻辑删除的数据。以下方法可以实现这一需求。
79
+
80
+**实现说明**
81
+
82
+1. **设置忽略逻辑删除标记**：在查询前添加忽略逻辑删除的标记
83
+2. **执行数据查询**：执行需要查询逻辑删除数据的操作
84
+3. **清理标记**：操作完成后清理标记
85
+
86
+**示例代码**
87
+
88
+```java
89
+Meta meta = BaseContextHandler.getMeta();
90
+try {
91
+ // 添加忽略逻辑删除的标记
92
+ meta.addArgument(MetaConstant.IGNORE_LOGIC_DELETE, true);
93
+
94
+ // 执行业务操作
95
+
96
+} finally {
97
+ // 清理忽略逻辑删除的标记
98
+ meta.getArguments().remove(MetaConstant.IGNORE_LOGIC_DELETE);
99
+}
100
+```
101
+
102
+**注意事项**
103
+
104
+- **使用try-finally结构**：确保标记被正确清理
105
+- **数据完整性**：注意查询到的数据可能包含已删除记录
106
+
107
+## 3. 跳过数据校验
108
+
109
+当业务已经自行完成数据校验时，可以跳过系统的数据校验以提升性能。
110
+
111
+**实现说明**
112
+
113
+1. **设置跳过校验标记**：在操作前添加跳过数据校验的标记
114
+2. **执行业务操作**：执行数据新增或修改操作
115
+3. **清理标记**：操作完成后清理标记
116
+
117
+**示例代码**
118
+
119
+```java
120
+Meta meta = BaseContextHandler.getMeta();
121
+try {
122
+ // 跳过数据校验（业务侧已自行校验）
123
+ meta.addArgument(MetaConstant.IGNORE_VALIDATE, true);
124
+
125
+ // 执行业务操作
126
+
127
+} finally {
128
+ // 清理标记
129
+ meta.getArguments().remove(MetaConstant.IGNORE_VALIDATE);
130
+}
131
+```
132
+
133
+**注意事项**
134
+
135
+- **必须使用try-finally结构**：确保标记被正确清理
136
+- **确保数据安全**：仅在业务已进行完整校验的情况下使用
137
+
138
+## 4. 跳过操作日志记录
139
+
140
+在性能敏感的场景中，可以不记录操作日志以提升系统性能。
141
+
142
+**实现说明**
143
+
144
+1. **设置跳过日志标记**：在操作前添加跳过操作日志的标记
145
+2. **执行业务操作**：执行数据操作
146
+3. **清理标记**：操作完成后清理标记
147
+
148
+**示例代码**
149
+
150
+```java
151
+Meta meta = BaseContextHandler.getMeta();
152
+try {
153
+ // 跳过操作日志记录
154
+ meta.addArgument(MetaConstant.IGNORE_OPERATOR_LOG, true);
155
+
156
+ // 执行业务操作
157
+
158
+} finally {
159
+ // 清理标记
160
+ meta.getArguments().remove(MetaConstant.IGNORE_OPERATOR_LOG);
161
+}
162
+```
163
+
164
+**注意事项**
165
+
166
+- **使用try-finally结构**：确保标记被正确清理
167
+- **审计考虑**：跳过日志可能影响操作审计，需谨慎使用
168
+
169
+## 5. 跳过审计字段自动填充
170
+
171
+当业务需要自行指定审计字段（如创建人、创建时间、修改人、修改时间）时，可以跳过系统的自动填充。
172
+
173
+**实现说明**
174
+
175
+1. **设置跳过审计标记**：在操作前添加跳过审计字段的标记
176
+2. **执行业务操作**：执行数据新增或修改操作
177
+3. **清理标记**：操作完成后清理标记
178
+
179
+**示例代码**
180
+
181
+```java
182
+Meta meta = BaseContextHandler.getMeta();
183
+try {
184
+ // 跳过审计字段自动填充
185
+ meta.addArgument(MetaConstant.IGNORE_AUTO_LOG, true);
186
+
187
+ // 执行业务操作
188
+
189
+} finally {
190
+ // 清理标记
191
+ meta.getArguments().remove(MetaConstant.IGNORE_AUTO_LOG);
192
+}
193
+```
194
+
195
+**注意事项**
196
+
197
+- **使用try-finally结构**：确保标记被正确清理
198
+- **数据完整性**：业务需自行维护审计字段的准确性
199
+
200
+## 通用注意事项
201
+
202
+1. **清理机制**：所有跳过操作都应使用try-finally结构确保标记被清理
203
+2. **使用场景**：仅在确实需要的业务场景中使用跳过功能
204
+3. **安全性**：跳过系统默认行为可能带来安全风险，需谨慎评估
205
+4. **测试验证**：对跳过默认行为的代码进行充分测试
... ...
\ No newline at end of file