---
title: 响应
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Step, Steps } from 'fumadocs-ui/components/steps'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
import { Image } from '@/components/ui/image'

响应模块是工作流中的最后一步，用于格式化并将结构化的响应发送回 API 调用。它就像整个工作流的 "return" 语句——将结果打包并返回。

<div className="flex justify-center">
  <Image
    src="/static/blocks/response.png"
    alt="响应模块配置"
    width={500}
    height={400}
    className="my-6"
  />
</div>

<Callout type="info">
  响应模块是终端模块——它们结束工作流的执行，无法连接到其他模块。
</Callout>

## 概述

响应模块可以让您：

<Steps>
  <Step>
    <strong>格式化 API 响应</strong>：将工作流结果结构化为正确的 HTTP 响应
  </Step>
  <Step>
    <strong>设置状态码</strong>：根据工作流结果配置适当的 HTTP 状态码
  </Step>
  <Step>
    <strong>控制头信息</strong>：为 API 响应和 Webhooks 添加自定义头信息
  </Step>
  <Step>
    <strong>转换数据</strong>：将工作流变量转换为客户端友好的响应格式
  </Step>
</Steps>

## 工作原理

响应模块完成工作流的执行：

1. **收集数据** - 收集前面模块的变量和输出
2. **格式化响应** - 根据您的配置结构化数据
3. **设置 HTTP 详细信息** - 应用状态码和头信息
4. **发送响应** - 将格式化的响应返回给 API 调用方

## 何时需要响应模块

- **API 端点**：当您的工作流通过 API 调用时，响应模块会格式化返回数据
- **Webhooks**：将确认或数据返回给调用系统
- **测试**：在测试工作流时查看格式化的结果

## 构建响应的两种方式

### 构建器模式（推荐）
用于构建响应结构的可视化界面：
- 拖放字段
- 轻松引用工作流变量
- 响应结构的可视化预览

### 编辑器模式（高级）
直接编写 JSON：
- 完全控制响应格式
- 支持复杂的嵌套结构
- 使用 `<variable.name>` 语法表示动态值

## 配置选项

### 响应数据

响应数据是将返回给 API 调用者的主要内容。它应以 JSON 格式编写，可以包括：

- 静态值
- 使用 `<variable.name>` 语法动态引用工作流变量
- 嵌套对象和数组
- 任何有效的 JSON 结构

### 状态码

设置响应的 HTTP 状态码。常见的状态码包括：

<Tabs items={['成功 (2xx)', '客户端错误 (4xx)', '服务器错误 (5xx)']}>
  <Tab>
    <ul className="list-disc space-y-2 pl-6">
      <li><strong>200</strong>：OK - 标准成功响应</li>
      <li><strong>201</strong>：Created - 资源成功创建</li>
      <li><strong>204</strong>：No Content - 成功但无响应内容</li>
    </ul>
  </Tab>
  <Tab>
    <ul className="list-disc space-y-2 pl-6">
      <li><strong>400</strong>：Bad Request - 请求参数无效</li>
      <li><strong>401</strong>：Unauthorized - 需要身份验证</li>
      <li><strong>404</strong>：Not Found - 资源不存在</li>
      <li><strong>422</strong>：Unprocessable Entity - 验证错误</li>
    </ul>
  </Tab>
  <Tab>
    <ul className="list-disc space-y-2 pl-6">
      <li><strong>500</strong>：Internal Server Error - 服务器端错误</li>
      <li><strong>502</strong>：Bad Gateway - 外部服务错误</li>
      <li><strong>503</strong>：Service Unavailable - 服务暂时不可用</li>
    </ul>
  </Tab>
</Tabs>

<div className="mt-4 text-sm text-gray-600 dark:text-gray-400">
  如果未指定，默认状态码为 200。
</div>

### 响应头

配置响应中包含的额外 HTTP 头信息。

标头被配置为键值对：

| 键 | 值 |
|-----|-------|
| Content-Type | application/json |
| Cache-Control | no-cache |
| X-API-Version | 1.0 |

## 示例用例

### API 端点响应

<div className="mb-4 rounded-md border p-4">
  <h4 className="font-medium">场景：从搜索 API 返回结构化数据</h4>
  <ol className="list-decimal pl-5 text-sm">
    <li>工作流处理搜索查询并检索结果</li>
    <li>功能块格式化并分页结果</li>
    <li>响应块返回包含数据、分页和元数据的 JSON</li>
    <li>客户端接收带有 200 状态的结构化响应</li>
  </ol>
</div>

### Webhook 确认

<div className="mb-4 rounded-md border p-4">
  <h4 className="font-medium">场景：确认 Webhook 的接收和处理</h4>
  <ol className="list-decimal pl-5 text-sm">
    <li>Webhook 触发器接收外部系统数据</li>
    <li>工作流处理传入数据</li>
    <li>响应块返回带有处理状态的确认</li>
    <li>外部系统接收确认信息</li>
  </ol>
</div>

### 错误响应处理

<div className="mb-4 rounded-md border p-4">
  <h4 className="font-medium">场景：返回适当的错误响应</h4>
  <ol className="list-decimal pl-5 text-sm">
    <li>条件块检测到验证失败或系统错误</li>
    <li>路由器引导到错误处理路径</li>
    <li>响应块返回带有错误详情的 400/500 状态</li>
    <li>客户端接收结构化的错误信息</li>
  </ol>
</div>

## 输入和输出

<Tabs items={['Configuration', 'Variables', 'Results']}>
  <Tab>
    <ul className="list-disc space-y-2 pl-6">
      <li>
        <strong>响应数据</strong>：响应体的 JSON 结构
      </li>
      <li>
        <strong>状态码</strong>：HTTP 状态码（默认：200）
      </li>
      <li>
        <strong>标头</strong>：自定义 HTTP 标头，格式为键值对
      </li>
      <li>
        <strong>模式</strong>：用于响应构建的 Builder 或 Editor 模式
      </li>
    </ul>
  </Tab>
  <Tab>
    <ul className="list-disc space-y-2 pl-6">
      <li>
        <strong>response.data</strong>：结构化的响应体
      </li>
      <li>
        <strong>response.status</strong>：发送的 HTTP 状态码
      </li>
      <li>
        <strong>response.headers</strong>：响应中包含的标头
      </li>
      <li>
        <strong>response.success</strong>：指示成功完成的布尔值
      </li>
    </ul>
  </Tab>
  <Tab>
    <ul className="list-disc space-y-2 pl-6">
      <li>
        <strong>HTTP 响应</strong>：发送给 API 调用者的完整响应
      </li>
      <li>
        <strong>工作流终止</strong>：结束工作流执行
      </li>
      <li>
        <strong>访问</strong>：响应块是终端块 - 无后续块
      </li>
    </ul>
  </Tab>
</Tabs>

## 变量引用

使用 `<variable.name>` 语法将工作流变量动态插入到您的响应中：

```json
{
  "user": {
    "id": "<variable.userId>",
    "name": "<variable.userName>",
    "email": "<variable.userEmail>"
  },
  "query": "<variable.searchQuery>",
  "results": "<variable.searchResults>",
  "totalFound": "<variable.resultCount>",
  "processingTime": "<variable.executionTime>ms"
}
```

<Callout type="warning">
  变量名称区分大小写，必须与工作流中可用的变量完全匹配。
</Callout>

## 最佳实践

- **使用有意义的状态码**：选择适当的 HTTP 状态码，准确反映工作流的结果
- **保持响应结构一致**：在所有 API 端点中保持一致的 JSON 结构，以提升开发者体验
- **包含相关元数据**：添加时间戳和版本信息，以便调试和监控
- **优雅地处理错误**：在工作流中使用条件逻辑设置适当的错误响应，并提供描述性消息
- **验证变量引用**：确保所有引用的变量存在并包含预期的数据类型，然后再执行响应块
