聊天机器人表单数据规范化与无服务器数据库集成实战

将公司内部信使机器人接收到的表单输入存入数据库，比想象中要繁琐得多。因为 Slack 和 Discord 的载荷（Payload）结构完全不同。看着 SDK 文档每次都要花时间在 API 集成上，作为后端开发者常常会产生一种无力感。

处理多平台架构碎片化

Slack 在提交模态框（Modal）时会传递 3 层嵌套对象。而 Discord 则以组件数组的形式发送数值。此外，还叠加了必须在接收到 Webhook 后 3 秒内做出响应的压力。

通过将适配器模式（Adapter Pattern）与 Zod 结合，来构建领域规范化层。

使用 Zod 定义后端标准架构。
分别实现 SlackPayloadAdapter 和 DiscordPayloadAdapter。
解析各个渠道异构的数据路径，并将其绑定到公共架构。

`typescript
import { z } from 'zod';

export const CommonFormSchema = z.object({
platform: z.enum(['SLACK', 'DISCORD']),
userId: z.string().min(1),
formId: z.string().min(1),
submittedAt: z.date(),
fields: z.object({
applicantName: z.string().min(2),
contactEmail: z.string().email(),
category: z.enum(['BUG', 'FEATURE', 'INQUIRY']),
description: z.string().max(2000),
}),
});

export type NormalizedFormData = z.infer;

export class SlackPayloadAdapter {
static adapt(rawPayload: any): NormalizedFormData {
const values = rawPayload.view?.state?.values || {};
return CommonFormSchema.parse({
platform: 'SLACK',
userId: rawPayload.user?.id,
formId: rawPayload.view?.callback_id,
submittedAt: new Date(),
fields: {
applicantName: values['name_block']?.['name_action']?.value,
contactEmail: values['email_block']?.['email_action']?.value,
category: values['category_block']?.['category_action']?.selected_option?.value,
description: values['desc_block']?.['desc_action']?.value,
},
});
}
}

export class DiscordPayloadAdapter {
static adapt(rawPayload: any): NormalizedFormData {
const components = rawPayload.data?.components || [];
const fieldMap: Record<string, string> = {};

for (const row of components) {
  for (const comp of row.components || []) {
    if (comp.custom_id) {
      fieldMap[comp.custom_id] = comp.value || comp.values?.[0];
    }
  }
}

return CommonFormSchema.parse({
  platform: 'DISCORD',
  userId: rawPayload.member?.user?.id || rawPayload.user?.id,
  formId: rawPayload.data?.custom_id,
  submittedAt: new Date(),
  fields: {
    applicantName: fieldMap['applicant_name'],
    contactEmail: fieldMap['contact_email'],
    category: fieldMap['category'],
    description: fieldMap['description'],
  },
});

}
}

分离适配器后，即使添加新的信使工具，也无需修改业务逻辑。维护成本大幅降低。

无服务器环境连接池与事务

Vercel 无服务器函数在每次请求时都会启动一个实例。如果以传统方式直接连接 PostgreSQL，会超出 max connections 限制从而引发错误。

使用 Neon 的无服务器连接池（Pooler）可以显著降低连接延迟并处理并发请求。必须通过幂等键（Idempotency Key）防止重复存储。

`typescript
import { Pool } from '@neondatabase/serverless';

const pool = new Pool({ connectionString: process.env.POSTGRES_URL });

export async function insertNormalizedFormsBulk(forms: NormalizedFormData[]) {
const client = await pool.connect();

try {
await client.query('BEGIN');

const insertQuery = `
  INSERT INTO form_responses (
    idempotency_key,
    platform,
    user_id,
    form_id,
    payload,
    created_at
  )
  VALUES ($1, $2, $3, $4, $5, $6)
  ON CONFLICT (idempotency_key) 
  DO UPDATE SET 
    payload = EXCLUDED.payload,
    created_at = EXCLUDED.created_at
  RETURNING id;
`;

for (const form of forms) {
  const idempotencyKey = `${form.platform}:${form.userId}:${form.formId}:${form.submittedAt.getTime()}`;

  await client.query(insertQuery, [
    idempotencyKey,
    form.platform,
    form.userId,
    form.formId,
    JSON.stringify(form.fields),
    form.submittedAt,
  ]);
}

await client.query('COMMIT');

} catch (error) {
await client.query('ROLLBACK');
throw error;
} finally {
client.release();
}
}

Webhook 最好快速返回 200 响应，而实际的写入操作则采用异步处理，这是避开 3 秒超时的唯一途径。

输入值异常与状态管理

如果因为输入错误就关闭模态框并抛出错误，用户会感到疲惫。应当直接在打开的模态框内给予反馈。

`typescript
export function formatSlackValidationErrorResponse(zodError: z.ZodError) {
const errorMap: Record<string, string> = {};

for (const issue of zodError.issues) {
const fieldName = issue.path[issue.path.length - 1];
if (fieldName === 'contactEmail') {
errorMap['email_block'] = issue.message;
} else if (fieldName === 'applicantName') {
errorMap['name_block'] = issue.message;
} else if (fieldName === 'description') {
errorMap['desc_block'] = issue.message;
}
}

return {
statusCode: 200,
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
response_action: 'errors',
errors: errorMap,
}),
};
}

通过 Redis 管理会话并设置 15 分钟的 TTL。收集错误日志后发现，大多数情况下都是卡在邮箱格式或字数限制上。修改模态框提示并附带实时反馈后，输入错误率便会下降。

聊天机器人表单数据规范化与无服务器数据库集成实战

处理多平台架构碎片化

通过将适配器模式（Adapter Pattern）与 Zod 结合，来构建领域规范化层。

使用 Zod 定义后端标准架构。
分别实现 SlackPayloadAdapter 和 DiscordPayloadAdapter。
解析各个渠道异构的数据路径，并将其绑定到公共架构。

`typescript
import { z } from 'zod';

export type NormalizedFormData = z.infer;

export class DiscordPayloadAdapter {
static adapt(rawPayload: any): NormalizedFormData {
const components = rawPayload.data?.components || [];
const fieldMap: Record<string, string> = {};

for (const row of components) {
  for (const comp of row.components || []) {
    if (comp.custom_id) {
      fieldMap[comp.custom_id] = comp.value || comp.values?.[0];
    }
  }
}

return CommonFormSchema.parse({
  platform: 'DISCORD',
  userId: rawPayload.member?.user?.id || rawPayload.user?.id,
  formId: rawPayload.data?.custom_id,
  submittedAt: new Date(),
  fields: {
    applicantName: fieldMap['applicant_name'],
    contactEmail: fieldMap['contact_email'],
    category: fieldMap['category'],
    description: fieldMap['description'],
  },
});

}
}

分离适配器后，即使添加新的信使工具，也无需修改业务逻辑。维护成本大幅降低。

无服务器环境连接池与事务

Vercel 无服务器函数在每次请求时都会启动一个实例。如果以传统方式直接连接 PostgreSQL，会超出 max connections 限制从而引发错误。

使用 Neon 的无服务器连接池（Pooler）可以显著降低连接延迟并处理并发请求。必须通过幂等键（Idempotency Key）防止重复存储。

`typescript
import { Pool } from '@neondatabase/serverless';

const pool = new Pool({ connectionString: process.env.POSTGRES_URL });

export async function insertNormalizedFormsBulk(forms: NormalizedFormData[]) {
const client = await pool.connect();

try {
await client.query('BEGIN');

const insertQuery = `
  INSERT INTO form_responses (
    idempotency_key,
    platform,
    user_id,
    form_id,
    payload,
    created_at
  )
  VALUES ($1, $2, $3, $4, $5, $6)
  ON CONFLICT (idempotency_key) 
  DO UPDATE SET 
    payload = EXCLUDED.payload,
    created_at = EXCLUDED.created_at
  RETURNING id;
`;

for (const form of forms) {
  const idempotencyKey = `${form.platform}:${form.userId}:${form.formId}:${form.submittedAt.getTime()}`;

  await client.query(insertQuery, [
    idempotencyKey,
    form.platform,
    form.userId,
    form.formId,
    JSON.stringify(form.fields),
    form.submittedAt,
  ]);
}

await client.query('COMMIT');

} catch (error) {
await client.query('ROLLBACK');
throw error;
} finally {
client.release();
}
}

Webhook 最好快速返回 200 响应，而实际的写入操作则采用异步处理，这是避开 3 秒超时的唯一途径。

输入值异常与状态管理

如果因为输入错误就关闭模态框并抛出错误，用户会感到疲惫。应当直接在打开的模态框内给予反馈。

`typescript
export function formatSlackValidationErrorResponse(zodError: z.ZodError) {
const errorMap: Record<string, string> = {};

return {
statusCode: 200,
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
response_action: 'errors',
errors: errorMap,
}),
};
}

聊天机器人表单数据规范化与无服务器数据库集成实战

관련 영상

▲ Chat SDK：构建表单机器人

聊天机器人表单数据规范化与无服务器数据库集成实战

处理多平台架构碎片化

无服务器环境连接池与事务

输入值异常与状态管理

커뮤니티의 다른 글

사내 시스템에 llm api 붙일 때 마주하는 현실적인 한계와 대응법

레거시 백엔드에 GPT-6 Astra 붙일 때 예산 승인과 보안 통과를 먼저 끝내는 법이 있습니다

에이전트끼리 대화하다 6천만 원 청구서가 나오는 이유

사내 RAG 벡터 검색에 Okta 권한 필터를 직접 거는 방법

브라우저 에이전트에게 내 구글 계정을 통째로 넘기면 안 되는 이유

Apple Won the AI Race

댓글 (0)

聊天机器人表单数据规范化与无服务器数据库集成实战

处理多平台架构碎片化

无服务器环境连接池与事务

输入值异常与状态管理