feat(gateway): 实现API网关响应模板和请求映射增强功能

- 添加getLastHttpStepId方法获取最后HTTP步骤ID用于响应体设置判断
- 实现响应模板功能支持自定义JSON响应格式通过responseTemplate配置
- 增强请求映射逻辑支持查询参数、请求头和请求体的灵活映射与合并
- 优化HTTP步骤处理器中的请求载荷转换和响应映射逻辑
- 在START节点中支持公共参数自动继承到后续HTTP步骤
- 添加查询参数环境变量绑定便于JSONata表达式访问
- 实现向后兼容的默认响应格式保持现有功能不变

zt-module-databus/zt-module-databus-server/src/main/java/com/zt/plat/module/databus/framework/integration/gateway/core/ApiGatewayExecutionService.java

@@ -50,6 +50,7 @@ public class ApiGatewayExecutionService {
     private static final String HEADER_REMOTE_ADDRESS = org.springframework.integration.http.HttpHeaders.PREFIX + "remoteAddress";
     private static final String LOCAL_DEBUG_REMOTE_ADDRESS = "127.0.0.1";
     private static final String ATTR_DEBUG_INVOKE = "gatewayDebugInvoke";
+    private static final String ATTR_API_AGGREGATE = "apiDefinitionAggregate";
 
     private final ApiGatewayRequestMapper requestMapper;
     private final ApiFlowDispatcher apiFlowDispatcher;
@@ -78,14 +79,22 @@ public class ApiGatewayExecutionService {
         ApiInvocationContext context = message.getPayload();
         accessLogger.onRequest(context);
         ApiInvocationContext responseContext;
-        ApiDefinitionAggregate debugAggregate = null;
+        ApiDefinitionAggregate aggregate = null;
         try {
             enforceCredentialAuthorization(context);
             if (Boolean.TRUE.equals(context.getAttributes().get(ATTR_DEBUG_INVOKE))) {
-                debugAggregate = resolveDebugAggregate(context);
+                aggregate = resolveDebugAggregate(context);
+            } else {
+                // 对于非调试调用，也需要获取 aggregate 以便后续应用响应模板
+                aggregate = apiDefinitionService.findByCodeAndVersion(context.getApiCode(), context.getApiVersion())
+                        .orElse(null);
             }
-            if (debugAggregate != null) {
+            // 将 aggregate 存储到上下文中，供响应构建时使用
-                responseContext = apiFlowDispatcher.dispatchWithAggregate(debugAggregate, context);
+            if (aggregate != null) {
+                context.getAttributes().put(ATTR_API_AGGREGATE, aggregate);
+            }
+            if (aggregate != null && Boolean.TRUE.equals(context.getAttributes().get(ATTR_DEBUG_INVOKE))) {
+                responseContext = apiFlowDispatcher.dispatchWithAggregate(aggregate, context);
             } else {
                 responseContext = apiFlowDispatcher.dispatch(context.getApiCode(), context.getApiVersion(), context);
             }
@@ -240,6 +249,17 @@ public class ApiGatewayExecutionService {
         String message = StringUtils.hasText(context.getResponseMessage())
                 ? context.getResponseMessage()
                 : HttpStatus.valueOf(status).getReasonPhrase();
+
+        // 尝试从上下文中获取 API 定义聚合对象
+        ApiDefinitionAggregate aggregate = (ApiDefinitionAggregate) context.getAttributes().get(ATTR_API_AGGREGATE);
+        String responseTemplate = aggregate != null ? aggregate.getDefinition().getResponseTemplate() : null;
+
+        // 如果配置了响应模板，则应用模板；否则使用默认格式（向后兼容）
+        if (StringUtils.hasText(responseTemplate)) {
+            return buildResponseWithTemplate(responseTemplate, context, status, message);
+        }
+
+        // 默认响应格式（向后兼容）
         return ApiGatewayResponse.builder()
             .code(status)
             .message(message)
@@ -248,6 +268,47 @@ public class ApiGatewayExecutionService {
             .build();
     }
 
+    /**
+     * 根据响应模板构建响应对象
+     * 模板格式示例：{"code": 0, "message": "success", "data": {...}}
+     * 模板中的 data 字段会被实际响应数据替换，其他字段保持用户配置的原始值
+     */
+    private ApiGatewayResponse buildResponseWithTemplate(String templateJson, ApiInvocationContext context, int status, String message) {
+        try {
+            // 解析模板 JSON
+            Map<String, Object> template = objectMapper.readValue(templateJson, Map.class);
+
+            // 构建最终响应数据，保留模板中的所有字段
+            Map<String, Object> responseData = new LinkedHashMap<>(template);
+
+            // 只替换 data 字段为实际的响应体数据
+            // 其他字段（如 code、message）保持用户配置的原始值
+            if (responseData.containsKey("data")) {
+                responseData.put("data", context.getResponseBody());
+            }
+
+            // 返回使用模板结构的响应
+            // 注意：ApiGatewayResponse 的 code 和 message 是 HTTP 层面的状态
+            // responseData 中的 code 和 message 是业务层面的状态
+            return ApiGatewayResponse.builder()
+                .code(status)
+                .message(message)
+                .response(responseData)
+                .traceId(TracerUtils.getTraceId())
+                .build();
+
+        } catch (JsonProcessingException ex) {
+            log.warn("[API-PORTAL] 解析响应模板失败，使用默认格式: {}", ex.getMessage());
+            // 解析失败时回退到默认格式
+            return ApiGatewayResponse.builder()
+                .code(status)
+                .message(message)
+                .response(context.getResponseBody())
+                .traceId(TracerUtils.getTraceId())
+                .build();
+        }
+    }
+
     /**
      * 调用前校验凭证白名单，非调试调用需匹配绑定的 appId。
      */

zt-module-databus/zt-module-databus-server/src/main/java/com/zt/plat/module/databus/framework/integration/gateway/domain/ApiDefinitionAggregate.java

@@ -40,4 +40,23 @@ public class ApiDefinitionAggregate {
         return credentialBindings == null ? Collections.emptyList() : credentialBindings;
     }
 
+    /**
+     * 获取最后一个 HTTP 步骤的 ID（order 最大的 HTTP 步骤）
+     * 用于判断是否需要设置 responseBody
+     */
+    public Long getLastHttpStepId() {
+        return getSteps().stream()
+                .filter(stepDef -> "HTTP".equalsIgnoreCase(stepDef.getStep().getType()))
+                .max((s1, s2) -> {
+                    Integer order1 = s1.getStep().getStepOrder();
+                    Integer order2 = s2.getStep().getStepOrder();
+                    if (order1 == null && order2 == null) return 0;
+                    if (order1 == null) return -1;
+                    if (order2 == null) return 1;
+                    return order1.compareTo(order2);
+                })
+                .map(stepDef -> stepDef.getStep().getId())
+                .orElse(null);
+    }
+
 }

zt-module-databus/zt-module-databus-server/src/main/java/com/zt/plat/module/databus/framework/integration/gateway/expression/JsonataExpressionEvaluator.java

@@ -43,6 +43,13 @@ public class JsonataExpressionEvaluator implements ExpressionEvaluator {
             environment.setVariable("vars", objectMapper.valueToTree(context.getVariables() == null ? java.util.Collections.emptyMap() : context.getVariables()));
             environment.setVariable("headers", objectMapper.valueToTree(context.getHeaders() == null ? java.util.Collections.emptyMap() : context.getHeaders()));
             environment.setVariable("ctx", objectMapper.valueToTree(context.getInvocation()));
+
+            // 直接绑定查询参数，方便访问
+            if (context.getInvocation() != null && context.getInvocation().getRequestQueryParams() != null) {
+                environment.setVariable("query", objectMapper.valueToTree(context.getInvocation().getRequestQueryParams()));
+            } else {
+                environment.setVariable("query", objectMapper.valueToTree(java.util.Collections.emptyMap()));
+            }
         } catch (EvaluateRuntimeException e) {
             throw ServiceExceptionUtil.exception(API_JSONATA_BIND_FAILED);
         }

zt-module-databus/zt-module-databus-server/src/main/java/com/zt/plat/module/databus/framework/integration/gateway/step/impl/StartStepHandler.java

@@ -18,10 +18,19 @@ import org.springframework.stereotype.Component;
 
 import java.time.Duration;
 import java.time.Instant;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
 import static com.zt.plat.module.databus.service.gateway.impl.GatewayServiceErrorCodeConstants.API_STEP_START_EXECUTION_FAILED;
 
 /**
  * Handler for START orchestration nodes.
+ *
+ * <p>增强功能：START 节点的映射结果会存入 context.requestBody，
+ * 使得后续 HTTP 步骤可以自动继承这些公共参数，避免重复配置。
+ *
+ * <p>注意：不将参数存入 context.variables，避免与后续步骤的响应结果冲突。
+ * variables 应该保留给步骤执行结果使用。
  */
 @Component
 @RequiredArgsConstructor
@@ -40,11 +49,22 @@ public class StartStepHandler implements ApiStepHandler {
             Instant start = Instant.now();
             Object snapshotBefore = GatewayExpressionHelper.snapshotRequest(payload);
             try {
-                ExpressionSpec spec = ExpressionSpecParser.parse(stepDefinition.getStep().getRequestMappingExpr(), ExpressionTypeEnum.JSON);
+                ExpressionSpec spec = ExpressionSpecParser.parse(
+                    stepDefinition.getStep().getRequestMappingExpr(),
+                    ExpressionTypeEnum.JSON
+                );
                 if (spec != null) {
-                    Object evaluated = expressionExecutor.evaluate(spec, payload, payload.getRequestBody(), headers);
+                    // 将查询参数合并到 payload 中，使表达式可以通过 $.query.k 访问
+                    // 这样和 HTTP 步骤的映射逻辑保持一致
+                    Object enrichedPayload = enrichPayloadWithQuery(payload.getRequestBody(), payload.getRequestQueryParams());
+
+                    Object evaluated = expressionExecutor.evaluate(spec, payload, enrichedPayload, headers);
+
+                    // 应用上下文变更（包括 requestBody、requestQuery 等）
+                    // 支持字段级映射，将外部字段名转换为内部字段名
                     GatewayExpressionHelper.applyContextMutations(payload, evaluated, true, false);
                 }
+
                 payload.addStepResult(ApiStepResult.builder()
                         .stepId(stepDefinition.getStep().getId())
                         .stepType(stepDefinition.getStep().getType())
@@ -70,4 +90,26 @@ public class StartStepHandler implements ApiStepHandler {
             return payload;
         };
     }
+
+    /**
+     * 将查询参数合并到 payload 中，使表达式可以通过 $.query.k 访问
+     * 这样可以避免 JSONata 环境变量访问的限制
+     */
+    private Object enrichPayloadWithQuery(Object originalPayload, Map<String, Object> queryParams) {
+        if (queryParams == null || queryParams.isEmpty()) {
+            return originalPayload;
+        }
+
+        Map<String, Object> enriched = new LinkedHashMap<>();
+
+        // 如果原始 payload 是 Map，复制所有字段
+        if (originalPayload instanceof Map) {
+            enriched.putAll((Map<String, Object>) originalPayload);
+        }
+
+        // 添加查询参数到 query 字段
+        enriched.put("query", new LinkedHashMap<>(queryParams));
+
+        return enriched;
+    }
 }