fix(gateway): 语义门收口——type白名单对齐WfTypes(防误拒存量)+透传下游结构化errors+TOCTOU文档
评审 T3.2 收口(2 Important + 2 Minor):
- I-1(功能回归):ModelSemanticValidator.TYPE_WHITELIST 10 种→16 种,对齐 flowable-service WfTypes
配置类型 + OrgDirectoryJdbc 运行期分派(权威源,非 BasePropertiesConverter,注释已改)。
psql 窄查询实证:缺失 6 种里 initiatorDepartManager(24 文档)/fixedDimension(12 文档)在真实
candidateUsers 有非零命中,旧白名单会 422 误拒这些存量流程(载入→编辑无关节点→发布)。
网关不依赖 flowable-service 故复刻常量并注同步提醒。
- I-2(UX):FlowRemoteException 加 responseBody;FlowableClient.execute 携带下游原始体;
FlowGatewayExceptionHandler.onRemote 解析并把下游 errors 数组并入网关响应顶层——发布下游 422
的引擎结构校验 errors[{activityId,problem,defaultDescription}] 现能到前端,与网关语义 422 顶层
errors 契约统一(前端 T3.3 同一渲染)。非发布路径纯文本体照旧不加 errors 键(无回归)。
- I-3(TOCTOU):deploy 端点加「已接受风险」javadoc(超管低频+窄窗+非安全洞,v1 不做 content-hash 409)。
- 补测 M-1(flowable: 前缀 candidateUsers 按本地名匹配同校验)+ M-2(新增 4 种 type 放行,锁 I-1)+
I-2 客户端携带体/handler 并入顶层 errors 两用例。
测试:语义 19(+2)、审计 3、客户端 24(+1)、控制器 30(+1)。全 reactor mvn clean install 退出码 0,
零 <<< FAILURE,ArchitectureRulesTest 6/6。
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
@@ -62,10 +62,17 @@ public class ModelSemanticValidator {
|
||||
private static final String MULTI_PREFIX = "${multiInstanceUsersHandler.getUsers(execution,'";
|
||||
private static final String SUFFIX = "')}";
|
||||
|
||||
/** 办理人/会签项合法 type(§0 实测 10 种,逐字对齐 BasePropertiesConverter)。 */
|
||||
/**
|
||||
* 办理人/会签项合法 type。<b>权威集 = flowable-service {@code WfTypes} 的 16 个配置类型 + {@code OrgDirectoryJdbc}
|
||||
* 运行期分派</b>(非 BasePropertiesConverter——它只 setType,不做白名单)。网关不依赖 flowable-service 故此处复刻
|
||||
* 常量值;<b>WfTypes 新增类型时两处必须同步</b>。此前只列 10 种会 422 误拒含 {@code initiatorDepartManager}
|
||||
* (实测 24 文档)/{@code fixedDimension}(12 文档)等运行期完全支持的存量流程(from-procdef 载入→编辑无关节点→发布)。
|
||||
*/
|
||||
static final Set<String> TYPE_WHITELIST = Set.of(
|
||||
"user", "depart", "position", "formSpecifiedDimension", "initiator",
|
||||
"sameToTask", "beforeTaskLeader", "beforeTaskDepartManager", "scriptUser", "projectRoleType");
|
||||
"user", "roles", "depart", "position", "initiator",
|
||||
"initiatorDepartManager", "initiatorLeader", "initiatorSubordinate", "initiatorDepart",
|
||||
"sameToTask", "beforeTaskLeader", "beforeTaskDepartManager",
|
||||
"fixedDimension", "formSpecifiedDimension", "projectRoleType", "scriptUser");
|
||||
|
||||
/** 会签完成条件三预设(与 Eip4Panel.tsx:60-77 逐字一致):全票 / 过半 / 指定数。 */
|
||||
private static final Pattern COMPLETION_ALL =
|
||||
|
||||
@@ -8,17 +8,33 @@ import org.springframework.http.HttpStatusCode;
|
||||
* <p>与 {@link FlowServiceUnavailableException} 区分:那个是"引擎进程不可达"(→ 503);
|
||||
* 这个是"引擎在线但拒绝了这次操作"(原状态码透传给调用方,保留 Flowable 语义,
|
||||
* 如挂起拒办 409、参数错 400)。
|
||||
*
|
||||
* <p><b>responseBody(可空)</b>:携带下游原始响应体,供 {@code FlowGatewayExceptionHandler} 透传结构化错误
|
||||
* ——如流程发布下游 422 的 {@code {errors:[{activityId,problem,defaultDescription}]}}(引擎 ProcessValidator 结构校验)
|
||||
* 需并入网关响应,与网关语义校验 422 的顶层 {@code errors} 契约统一(T3.2 评审 I-2:此前只留状态码丢体,
|
||||
* 结构化错误到不了前端)。旧两参构造(无体)保留,非发布路径不受影响。
|
||||
*/
|
||||
public class FlowRemoteException extends RuntimeException {
|
||||
|
||||
private final HttpStatusCode status;
|
||||
private final String responseBody;
|
||||
|
||||
public FlowRemoteException(HttpStatusCode status, String message) {
|
||||
this(status, message, null);
|
||||
}
|
||||
|
||||
public FlowRemoteException(HttpStatusCode status, String message, String responseBody) {
|
||||
super(message);
|
||||
this.status = status;
|
||||
this.responseBody = responseBody;
|
||||
}
|
||||
|
||||
public HttpStatusCode getStatus() {
|
||||
return status;
|
||||
}
|
||||
|
||||
/** 下游原始响应体(可空);供 handler 解析并透传结构化 errors。 */
|
||||
public String getResponseBody() {
|
||||
return responseBody;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -490,10 +490,12 @@ public class FlowableClient {
|
||||
sleepBackoff();
|
||||
}
|
||||
} catch (RestClientResponseException e) {
|
||||
// 业务级:引擎在线但返回 4xx/5xx(如挂起拒办 409)——透传原状态码,绝不重试
|
||||
// 业务级:引擎在线但返回 4xx/5xx(如挂起拒办 409)——透传原状态码,绝不重试。
|
||||
// 携带原始响应体:发布下游 422 的结构化 errors(activityId/problem) 交 handler 并入网关响应(评审 I-2)。
|
||||
HttpStatusCode status = e.getStatusCode();
|
||||
log.debug("flowable-service {}调用返回业务状态 {}: {}", op, status, e.getMessage());
|
||||
throw new FlowRemoteException(status, "flowable-service " + op + "返回 " + status.value());
|
||||
throw new FlowRemoteException(status, "flowable-service " + op + "返回 " + status.value(),
|
||||
e.getResponseBodyAsString());
|
||||
}
|
||||
}
|
||||
// 重试耗尽仍连不上 —— 熔断降级为 503 语义
|
||||
|
||||
@@ -1,7 +1,10 @@
|
||||
package com.eip4.platform.flowgateway.web;
|
||||
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.Map;
|
||||
|
||||
import org.slf4j.Logger;
|
||||
import org.slf4j.LoggerFactory;
|
||||
import org.springframework.http.HttpStatus;
|
||||
import org.springframework.http.ResponseEntity;
|
||||
import org.springframework.web.bind.annotation.ExceptionHandler;
|
||||
@@ -9,6 +12,8 @@ import org.springframework.web.bind.annotation.RestControllerAdvice;
|
||||
|
||||
import com.eip4.platform.flowgateway.client.FlowRemoteException;
|
||||
import com.eip4.platform.flowgateway.client.FlowServiceUnavailableException;
|
||||
import com.fasterxml.jackson.databind.JsonNode;
|
||||
import com.fasterxml.jackson.databind.ObjectMapper;
|
||||
|
||||
/**
|
||||
* 流程网关异常 → 干净 HTTP 语义(只管本网关 client 抛出的两类异常,不拦其他)。
|
||||
@@ -17,12 +22,17 @@ import com.eip4.platform.flowgateway.client.FlowServiceUnavailableException;
|
||||
* <li>{@link FlowServiceUnavailableException}(引擎进程不可达,重试耗尽)→ <b>503</b>
|
||||
* Service Unavailable —— 待办聚合在引擎宕机/网络分区时返回明确的服务不可用语义,而非 500 堆栈。</li>
|
||||
* <li>{@link FlowRemoteException}(引擎在线但拒绝,如挂起拒办 409)→ <b>透传原状态码</b>,
|
||||
* 保留 Flowable 语义。</li>
|
||||
* 保留 Flowable 语义;若下游响应体带结构化 {@code errors} 数组(如发布 422 的引擎结构校验错误
|
||||
* {@code [{activityId,problem,defaultDescription}]}),<b>并入</b>网关响应顶层 {@code errors},
|
||||
* 与网关语义校验 422 的顶层 {@code errors} 契约统一(评审 I-2)。</li>
|
||||
* </ul>
|
||||
*/
|
||||
@RestControllerAdvice(basePackages = "com.eip4.platform.flowgateway")
|
||||
public class FlowGatewayExceptionHandler {
|
||||
|
||||
private static final Logger log = LoggerFactory.getLogger(FlowGatewayExceptionHandler.class);
|
||||
private static final ObjectMapper MAPPER = new ObjectMapper();
|
||||
|
||||
@ExceptionHandler(FlowServiceUnavailableException.class)
|
||||
public ResponseEntity<Map<String, Object>> onUnavailable(FlowServiceUnavailableException e) {
|
||||
return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
|
||||
@@ -34,10 +44,33 @@ public class FlowGatewayExceptionHandler {
|
||||
|
||||
@ExceptionHandler(FlowRemoteException.class)
|
||||
public ResponseEntity<Map<String, Object>> onRemote(FlowRemoteException e) {
|
||||
return ResponseEntity.status(e.getStatus())
|
||||
.body(Map.of(
|
||||
"status", e.getStatus().value(),
|
||||
"error", "FLOW_REMOTE_ERROR",
|
||||
"message", e.getMessage()));
|
||||
Map<String, Object> body = new LinkedHashMap<>();
|
||||
body.put("status", e.getStatus().value());
|
||||
body.put("error", "FLOW_REMOTE_ERROR");
|
||||
body.put("message", e.getMessage());
|
||||
Object errors = extractErrors(e.getResponseBody());
|
||||
if (errors != null) {
|
||||
body.put("errors", errors);
|
||||
}
|
||||
return ResponseEntity.status(e.getStatus()).body(body);
|
||||
}
|
||||
|
||||
/**
|
||||
* 从下游原始响应体抽结构化 {@code errors} 数组(非空才返回)。下游体非 JSON / 无 errors / 空数组 → null
|
||||
* (回原 FLOW_REMOTE_ERROR 信封,不加 errors 键)。防御性:解析失败静默降级,不让异常翻译再抛异常。
|
||||
*/
|
||||
private static Object extractErrors(String responseBody) {
|
||||
if (responseBody == null || responseBody.isBlank()) {
|
||||
return null;
|
||||
}
|
||||
try {
|
||||
JsonNode errors = MAPPER.readTree(responseBody).get("errors");
|
||||
if (errors != null && errors.isArray() && !errors.isEmpty()) {
|
||||
return MAPPER.convertValue(errors, Object.class);
|
||||
}
|
||||
} catch (Exception ex) {
|
||||
log.debug("下游响应体非 JSON 或无 errors,回原信封: {}", ex.toString());
|
||||
}
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -169,6 +169,14 @@ public class ProcessModelerController {
|
||||
|
||||
// ---------------------------------------------------------------- 发布门(T3.2)
|
||||
|
||||
/**
|
||||
* <b>TOCTOU 已接受风险(评审 I-3)</b>:本端点先 {@link FlowableClient#getModel} 读草稿源做语义校验,再由下游
|
||||
* deploy 重新读 editorSource 部署——两次读之间存在并发 PUT 改写草稿的窗口(校验的是旧内容、部署的是新内容)。
|
||||
* v1 <b>接受</b>该风险,不做 content-hash 乐观锁 409:①发布是超管手动、低频、通常单人操作,并发改写窗口极窄;
|
||||
* ②非安全洞(超管门已限定调用者,下游 deploy 仍过引擎 ProcessValidator 结构校验兜底);③content-hash 409
|
||||
* 对 v1 过重(需前端拿版本号回传+冲突重试 UI)。与 {@link FlowableClient} 幂等段同风格声明,v2 有多人协同编辑
|
||||
* 需求再引入乐观锁。
|
||||
*/
|
||||
@Operation(summary = "发布草稿为流程定义(超管 + 语义校验门 + 审计)",
|
||||
description = "超管门 → 取草稿源 XML(FlowableClient.getModel)→ EIP4 语义校验"
|
||||
+ "(ModelSemanticValidator:办理人/会签内嵌 JSON items 非空+type 白名单、formKey 存在于 view_wftemplate、"
|
||||
|
||||
@@ -469,6 +469,30 @@ class FlowableClientTest {
|
||||
server.verify();
|
||||
}
|
||||
|
||||
@Test
|
||||
void 发布_下游422结构化errors体被FlowRemoteException携带_不丢弃() {
|
||||
// 评审 I-2:execute 曾只留状态码丢响应体,引擎结构校验 errors 到不了前端。现携带原始体供 handler 透传。
|
||||
FlowGatewayProperties p = props();
|
||||
RestClient.Builder builder = RestClient.builder().baseUrl(p.getBaseUrl());
|
||||
MockRestServiceServer server = MockRestServiceServer.bindTo(builder).build();
|
||||
String engineBody = "{\"status\":1,\"msg\":\"流程校验未通过\",\"errors\":"
|
||||
+ "[{\"activityId\":\"t1\",\"problem\":\"flowable-noOutgoingSeq\",\"defaultDescription\":\"节点未连出边\"}]}";
|
||||
server.expect(ExpectedCount.once(), requestTo("http://localhost:8089/api/flow/models/m1/deploy"))
|
||||
.andExpect(method(HttpMethod.POST))
|
||||
.andRespond(withStatus(HttpStatus.UNPROCESSABLE_ENTITY)
|
||||
.body(engineBody).contentType(MediaType.APPLICATION_JSON));
|
||||
FlowableClient client = new FlowableClient(builder.build(), p);
|
||||
|
||||
assertThatThrownBy(() -> client.deployModel("m1"))
|
||||
.isInstanceOf(FlowRemoteException.class)
|
||||
.satisfies(e -> {
|
||||
FlowRemoteException fre = (FlowRemoteException) e;
|
||||
assertThat(fre.getStatus().value()).isEqualTo(422);
|
||||
assertThat(fre.getResponseBody()).contains("activityId").contains("节点未连出边");
|
||||
});
|
||||
server.verify();
|
||||
}
|
||||
|
||||
@Test
|
||||
void 发布影响_GET_models_id_impact_透传下游结果() {
|
||||
FlowGatewayProperties p = props();
|
||||
|
||||
@@ -107,6 +107,33 @@ class ModelSemanticValidatorTest {
|
||||
assertThat(validator.validate(xml)).isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
void M1_flowable前缀candidateUsers_按本地名匹配同样校验() {
|
||||
// 语料有 flowable 命名空间文档(3docs);按本地名匹配,flowable:candidateUsers 与 activiti: 同样被校验。
|
||||
String xml = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
|
||||
+ "<definitions xmlns=\"http://www.omg.org/spec/BPMN/20100524/MODEL\" "
|
||||
+ "xmlns:flowable=\"http://flowable.org/bpmn\" targetNamespace=\"n\">"
|
||||
+ "<process id=\"p1\" name=\"流程\">"
|
||||
+ "<userTask id=\"t1\" name=\"flowable节点\" flowable:candidateUsers=\""
|
||||
+ attr(candidateExpr("[{\"type\":\"bogusType\",\"content\":\"x\"}]")) + "\"/>"
|
||||
+ "</process></definitions>";
|
||||
List<String> errors = validator.validate(xml);
|
||||
assertThat(errors).hasSize(1);
|
||||
assertThat(errors.get(0)).contains("flowable节点").contains("bogusType");
|
||||
}
|
||||
|
||||
@Test
|
||||
void M2_新增4种type放行_锁I1白名单对齐WfTypes() {
|
||||
// roles/initiatorLeader/initiatorDepartManager/fixedDimension:WfTypes 配置类型、OrgDirectoryJdbc 运行期支持,
|
||||
// 但旧 10 种白名单缺失。实测 initiatorDepartManager(24 文档)/fixedDimension(12 文档)真存量命中→曾会 422 误拒。
|
||||
for (String type : new String[]{"roles", "initiatorLeader", "initiatorDepartManager", "fixedDimension",
|
||||
"initiatorSubordinate", "initiatorDepart"}) {
|
||||
String xml = bpmn(userTaskWithCandidate("节点",
|
||||
candidateExpr("[{\"type\":\"" + type + "\",\"content\":\"x\"}]")));
|
||||
assertThat(validator.validate(xml)).as("type=%s 应放行", type).isEmpty();
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- 办理人 JSON 错误
|
||||
|
||||
@Test
|
||||
|
||||
@@ -472,4 +472,24 @@ class ProcessModelerControllerTest {
|
||||
|
||||
verify(flowableClient, never()).deployModel(anyString());
|
||||
}
|
||||
|
||||
@Test
|
||||
void 胶水_发布_语义过但下游引擎422结构化errors经handler并入顶层() throws Exception {
|
||||
// I-2:语义门放行 → 转发 deploy → 下游引擎 ProcessValidator 结构校验 422(对象式 errors) → handler 并入网关响应。
|
||||
// 两条 422 契约统一:顶层 errors(语义=字符串数组 / 引擎=对象数组),前端 T3.3 同一渲染。
|
||||
when(flowableClient.getModel("m1"))
|
||||
.thenReturn(Map.of("found", true, "bpmnXml", "<definitions/>"));
|
||||
when(semanticValidator.validate("<definitions/>")).thenReturn(List.of()); // 语义过
|
||||
String engineBody = "{\"status\":1,\"msg\":\"流程校验未通过\",\"errors\":"
|
||||
+ "[{\"activityId\":\"t1\",\"problem\":\"noOutgoing\",\"defaultDescription\":\"节点未连出边\"}]}";
|
||||
when(flowableClient.deployModel("m1")).thenThrow(
|
||||
new FlowRemoteException(HttpStatus.UNPROCESSABLE_ENTITY,
|
||||
"flowable-service 发布草稿返回 422", engineBody));
|
||||
|
||||
glueMvc().perform(post("/api/workflow/models/{id}/deploy", "m1"))
|
||||
.andExpect(status().isUnprocessableEntity())
|
||||
.andExpect(jsonPath("$.error").value("FLOW_REMOTE_ERROR"))
|
||||
.andExpect(jsonPath("$.errors[0].activityId").value("t1"))
|
||||
.andExpect(jsonPath("$.errors[0].defaultDescription").value("节点未连出边"));
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user