【Next.js 项目实战系列】05-从UI到API：构建一个健壮的Issue删除功能

原创于 2026-02-27 02:11:39 发布 · 158 阅读

本内容遵循CC 4.0 BY-SA版权协议

1. 从UI到API：一个完整删除功能的蓝图

在开发一个任务管理或者Bug追踪系统时，删除功能看似简单，不就是点个按钮、发个请求、删条数据吗？但如果你真这么想，那在实际项目中很可能会踩坑。我见过不少项目，删除按钮一点，页面就卡住，用户不知道是删了还是没删；或者网络一波动，数据没删掉，用户却以为成功了；更糟糕的是，没有二次确认，一不小心就把重要数据给误删了。所以，一个健壮的删除功能，远不止调用一个API那么简单。

今天，我们就以Next.js项目中的Issue（问题/任务）删除为例，手把手构建一个从用户界面到后端API，再到状态和错误处理的完整流程。这个流程会覆盖前端确认对话框的构建、后端API的安全校验、网络请求的可靠发送，以及加载状态、错误反馈等用户体验细节。我们的目标，是做出一个让用户用起来放心、开发者维护起来安心的功能。无论你是Next.js的新手，还是想优化现有项目交互的老手，这套从UI到API的实战思路，都能给你带来直接的启发。

2. 前端基石：用Radix UI构建用户友好的确认对话框

直接放一个删除按钮在页面上是非常危险的。用户可能误触，也可能在点击后反悔。因此，一个确认对话框是删除操作不可或缺的“安全门”。在React生态里，有很多UI库提供对话框组件，但Radix UI的AlertDialog以其出色的无障碍访问能力和轻量级的设计，成为了我的首选。它不强制样式，只提供行为和状态管理，这让我们可以灵活地搭配像@radix-ui/themes这样的主题库，快速构建出既美观又实用的组件。

2.1 创建删除按钮组件

首先，我们在Issue详情页的侧边栏，为删除功能预留一个位置。参考原始文章的布局，我们使用Grid来实现响应式：在移动设备上，编辑和删除按钮会堆叠显示；在中等屏幕以上，它们会显示在Issue详情内容的右侧。

// /app/issues/[id]/page.tsx
import { Grid, Box, Flex } from '@radix-ui/themes';
import IssueDetails from './IssueDetails';
import EditIssueButton from './EditIssueButton';
import DeleteIssueButton from './DeleteIssueButton';

interface Props {
  params: { id: string };
}

const IssueDetailPage = async ({ params }: Props) => {
  // ... 获取issue数据的逻辑
  const issue = await fetchIssue(params.id);

  return (
    <Grid columns={{ initial: "1", sm: "5" }} gap="5">
      <Box className="md:col-span-4">
        <IssueDetails issue={issue} />
      </Box>
      <Box>
        <Flex direction="column" gap="3">
          <EditIssueButton issueId={issue.id} />
          <DeleteIssueButton issueId={issue.id} />
        </Flex>
      </Box>
    </Grid>
  );
};

export default IssueDetailPage;

接下来，我们创建核心的DeleteIssueButton组件。这个组件将包裹在Radix UI的AlertDialog.Root中。AlertDialog.Trigger就是用户看到的那个红色的删除按钮。点击它，并不会直接删除，而是会弹出对话框。

// /app/issues/[id]/DeleteIssueButton.tsx
"use client"; // 这是一个客户端组件，因为需要交互

import { AlertDialog, Button, Flex } from "@radix-ui/themes";
import { Cross2Icon } from "@radix-ui/react-icons";

const DeleteIssueButton = ({ issueId }: { issueId: number }) => {
  return (
    <AlertDialog.Root>
      <AlertDialog.Trigger>
        <Button color="red">
          <Cross2Icon />
          Delete Issue
        </Button>
      </AlertDialog.Trigger>
      <AlertDialog.Content>
        <AlertDialog.Title>Confirm Deletion</AlertDialog.Title>
        <AlertDialog.Description>
          Are you sure you want to delete this issue? This action cannot be undone.
        </AlertDialog.Description>
        <Flex mt="4" gap="4" justify="end">
          <AlertDialog.Cancel>
            <Button variant="soft" color="gray">
              Cancel
            </Button>
          </AlertDialog.Cancel>
          <AlertDialog.Action>
            <Button color="red">Delete Issue</Button>
          </AlertDialog.Action>
        </Flex>
      </AlertDialog.Content>
    </AlertDialog.Root>
  );
};

export default DeleteIssueButton;

这段代码已经实现了一个标准的确认对话框。AlertDialog.Content内部定义了对话框的标题、描述和操作按钮。这里有两个关键部分：AlertDialog.Cancel和AlertDialog.Action。点击Cancel按钮（或按ESC键、点击对话框外部）会关闭对话框，操作取消。而点击Action按钮，目前还不会触发删除逻辑，它只是对话框的默认关闭行为。我们需要把真正的删除请求绑定到它上面。

2.2 对话框的视觉与交互细节

你可能注意到了，我在Flex容器上加了justify="end"，这让取消和删除两个按钮右对齐，符合大多数桌面端应用的操作习惯。AlertDialog.Description中的文案“This action cannot be undone.”（此操作不可逆）非常重要，它是一种强烈的风险提示，能有效防止用户草率操作。

在实际项目中，我建议根据删除对象的重要性来调整描述文案。比如，删除一个普通的评论和删除一个包含大量子任务的项目，其风险等级完全不同，提示语的严厉程度也应该有所区别。Radix UI的对话框默认会有优雅的弹出动画和焦点管理，这意味着用户可以用键盘（Tab键）在按钮间导航，这对于无障碍访问是极大的加分项。

3. 后端核心：设计安全可靠的删除API路由

前端做好了“门”，后端的“锁”更要牢固。在Next.js中，我们使用App Router的API路由来处理后端请求。对于删除操作，我们自然要使用DELETE方法。这个API的核心任务很简单：接收一个Issue的ID，从数据库中删除它。但“简单”不等于“简陋”，我们必须加入必要的校验和错误处理。

3.1 实现基础的DELETE API

我们在/app/api/issues/[id]/route.ts中创建API路由。这里使用了Prisma作为ORM来操作数据库。

// /app/api/issues/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server';
import prisma from '@/prisma/client';

interface Props {
  params: { id: string };
}

export async function DELETE(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  // 1. 参数校验：确保ID是有效的数字
  const id = parseInt(params.id);
  if (isNaN(id)) {
    return NextResponse.json(
      { error: 'Invalid issue ID format.' },
      { status: 400 }
    );
  }

  // 2. 查询验证：确认要删除的Issue存在
  const issue = await prisma.issue.findUnique({
    where: { id: id },
  });

  if (!issue) {
    return NextResponse.json(
      { error: 'Issue not found.' },
      { status: 404 }
    );
  }

  // 3. 执行删除
  try {
    await prisma.issue.delete({
      where: { id: issue.id },
    });
    // 4. 返回成功响应
    return NextResponse.json(
      { message: 'Issue deleted successfully.' },
      { status: 200 }
    );
  } catch (error) {
    // 5. 处理数据库操作错误
    console.error('Failed to delete issue:', error);
    return NextResponse.json(
      { error: 'An internal server error occurred.' },
      { status: 500 }
    );
  }
}

这个API包含了五个关键步骤，构成了一个健壮后端处理的模板。第一步校验参数，防止客户端传递非数字ID导致数据库查询错误。第二步在删除前先查询，确保目标存在，这比直接调用delete（如果记录不存在会抛出异常）更友好，也能返回更精确的404错误。第三步是核心的删除操作。第四步返回一个明确的成功信息，而不仅仅是状态码，这对前端调试有帮助。第五步用try-catch包裹数据库操作，捕获任何意外错误（如数据库连接中断），并返回500内部错误，避免将敏感的数据库错误信息暴露给客户端。

3.2 权限与业务逻辑的考量

在真实的生产环境中，删除API往往不会这么“单纯”。我们至少还需要考虑两点：身份验证和级联删除。对于身份验证，你需要在API开头检查请求中是否包含有效的用户会话或Token，确保只有有权限的用户（如Issue的创建者或管理员）才能执行删除。这通常通过Next.js的中间件或API路由内的校验逻辑实现。

关于级联删除，如果你的Issue关联了评论（Comment）、附件（Attachment）等其他数据，直接在Prisma模型定义中设置onDelete: Cascade是最省事的。这样，删除Issue时，所有关联数据会被自动清理。但如果你需要更复杂的清理逻辑（比如删除前备份、通知相关人员），那么就需要在这个API路由中，在删除Issue之前，手动执行这些操作。记住，数据库事务（Transaction）是你的好朋友，它能确保关联的多个操作要么全部成功，要么全部失败回滚，保持数据一致性。

4. 前后端握手：发起请求与页面导航

现在，我们有了漂亮的前端对话框和稳固的后端API，是时候把它们连接起来了。当用户在确认对话框中点击“Delete Issue”按钮时，我们需要做三件事：向后端发送DELETE请求、在请求成功后跳转到问题列表页、刷新列表数据以反映删除后的状态。

4.1 使用axios发送请求

在前端组件中，我们需要处理AlertDialog.Action的点击事件。我习惯使用axios库来发送HTTP请求，因为它内置了对错误状态码的处理，比原生的fetch更方便。首先，安装axios：npm install axios。

然后，我们修改DeleteIssueButton组件，添加点击处理函数。

// /app/issues/[id]/DeleteIssueButton.tsx
"use client";

import { AlertDialog, Button, Flex } from "@radix-ui/themes";
import { Cross2Icon } from "@radix-ui/react-icons";
import axios from "axios";
import { useRouter } from "next/navigation"; // 注意：App Router使用`next/navigation`
import { useState } from "react";

const DeleteIssueButton = ({ issueId }: { issueId: number }) => {
  const router = useRouter();
  const [isDeleting, setDeleting] = useState(false); // 新增：加载状态
  const [error, setError] = useState(false); // 新增：错误状态

  const handleDelete = async () => {
    // 防止重复提交
    if (isDeleting) return;
    
    setDeleting(true);
    setError(false); // 开始新请求时重置错误状态

    try {
      // 发送DELETE请求到我们的API路由
      await axios.delete(`/api/issues/${issueId}`);
      // 请求成功，跳转到问题列表页
      router.push("/issues");
      // 刷新列表页的数据，确保显示最新的列表（无已删除的项）
      router.refresh();
    } catch (error) {
      // 请求失败，设置错误状态
      setError(true);
      setDeleting(false); // 请求结束，关闭加载状态
      // 在实际项目中，这里可以根据error.response.status进行更细致的错误处理
      console.error("Delete failed:", error);
    }
    // 注意：成功跳转后，这个组件的状态会被卸载，所以不需要setDeleting(false)
  };

  return (
    <>
      <AlertDialog.Root>
        <AlertDialog.Trigger>
          <Button color="red" disabled={isDeleting}>
            <Cross2Icon />
            Delete Issue
          </Button>
        </AlertDialog.Trigger>
        <AlertDialog.Content>
          <AlertDialog.Title>Confirm Deletion</AlertDialog.Title>
          <AlertDialog.Description>
            Are you sure you want to delete this issue? This action cannot be undone.
          </AlertDialog.Description>
          <Flex mt="4" gap="4" justify="end">
            <AlertDialog.Cancel>
              <Button variant="soft" color="gray" disabled={isDeleting}>
                Cancel
              </Button>
            </AlertDialog.Cancel>
            <AlertDialog.Action asChild>
              {/* 使用asChild，将点击事件绑定到我们自己的Button上 */}
              <Button color="red" onClick={handleDelete} disabled={isDeleting}>
                Delete Issue
              </Button>
            </AlertDialog.Action>
          </Flex>
        </AlertDialog.Content>
      </AlertDialog.Root>
    </>
  );
};

export default DeleteIssueButton;

这里有几个关键点。第一，我们使用了useRouter的push方法进行页面跳转。在App Router中，它来自next/navigation。第二，router.refresh()是一个非常重要的调用。它会刷新当前活动路由（即我们跳转到的/issues页面）的服务器组件数据，而不会丢失客户端组件的状态（比如滚动位置、输入框内容等）。这确保了用户看到的列表是最新的。第三，注意AlertDialog.Action的asChild属性。这个属性告诉Radix UI，不要渲染它默认的按钮，而是使用我们传入的子元素（即我们自定义的Button），这样我们才能将onClick={handleDelete}绑定上去。

4.2 处理网络请求的潜在问题

网络是不稳定的。用户的网络可能中断，服务器可能暂时无响应。我们的代码必须处理这些情况。axios.delete调用被包裹在try...catch块中。如果请求失败（例如网络错误，或API返回4xx/5xx状态码），axios会抛出异常，代码会进入catch块。这里我们设置了一个错误状态error，并关闭了加载状态isDeleting。在下一节，我们会利用这个error状态给用户一个明确的反馈。

5. 用户体验升华：加载状态、错误反馈与按钮禁用

一个专业的交互，必须让用户时刻知道发生了什么。点击删除后，如果页面毫无反应，用户会困惑甚至重复点击。如果删除失败了却不告知原因，用户会以为操作成功。我们来优化这些细节。

5.1 添加加载指示器和按钮禁用

当删除请求发出后，我们应该立即给用户一个视觉反馈。最常见的做法是在按钮上显示一个加载动画（Spinner），并禁用按钮以防止重复提交。

首先，我们创建一个简单的Spinner组件（或者从你的组件库导入）。

// /app/components/Spinner.tsx
import { ReloadIcon } from "@radix-ui/react-icons";

const Spinner = () => {
  return (
    <ReloadIcon className="animate-spin ml-2 h-4 w-4" />
  );
};

export default Spinner;

然后，在DeleteIssueButton组件中集成它。我们之前已经定义了isDeleting状态。现在我们来使用它。

// /app/issues/[id]/DeleteIssueButton.tsx (部分代码)
import Spinner from "@/app/components/Spinner";

const DeleteIssueButton = ({ issueId }: { issueId: number }) => {
  const [isDeleting, setDeleting] = useState(false);
  // ... other states and handlers

  return (
    <>
      <AlertDialog.Root>
        <AlertDialog.Trigger>
          <Button color="red" disabled={isDeleting}>
            <Cross2Icon />
            Delete Issue
            {isDeleting && <Spinner />} {/* 加载时显示Spinner */}
          </Button>
        </AlertDialog.Trigger>
        <AlertDialog.Content>
          {/* ... dialog content ... */}
          <Flex mt="4" gap="4" justify="end">
            <AlertDialog.Cancel>
              <Button variant="soft" color="gray" disabled={isDeleting}>
                Cancel
              </Button>
            </AlertDialog.Cancel>
            <AlertDialog.Action asChild>
              <Button color="red" onClick={handleDelete} disabled={isDeleting}>
                Delete Issue
                {isDeleting && <Spinner />}
              </Button>
            </AlertDialog.Action>
          </Flex>
        </AlertDialog.Content>
      </AlertDialog.Root>
    </>
  );
};

现在，当isDeleting为true时，删除按钮和取消按钮都会被禁用（disabled），并且按钮内部会显示一个旋转的加载图标。这明确地告诉用户：“操作正在进行中，请稍候”。同时，禁用按钮也从根本上防止了因用户快速双击而导致的重复请求。

5.2 优雅地展示错误信息

如果删除请求失败了，我们需要告知用户。简单地弹出一个浏览器原生的alert框体验很差。我们可以复用Radix UI的AlertDialog组件，来展示一个风格一致的错误提示框。

我们利用之前定义的error状态来控制另一个错误提示对话框的显示。

// /app/issues/[id]/DeleteIssueButton.tsx (return部分)
return (
  <>
    {/* 原有的确认对话框 */}
    <AlertDialog.Root>
      {/* ... 内容省略 ... */}
    </AlertDialog.Root>

    {/* 错误提示对话框 */}
    <AlertDialog.Root open={error} onOpenChange={setError}>
      <AlertDialog.Content>
        <AlertDialog.Title>Error</AlertDialog.Title>
        <AlertDialog.Description>
          This issue could not be deleted. Please try again later.
        </AlertDialog.Description>
        <Flex mt="4" justify="end">
          <Button
            color="gray"
            variant="soft"
            onClick={() => setError(false)}
          >
            OK
          </Button>
        </Flex>
      </AlertDialog.Content>
    </AlertDialog.Root>
  </>
);

这个错误对话框的open属性由error状态控制。当catch块中setError(true)被调用时，对话框会自动弹出。用户点击“OK”按钮，会触发onClick={() => setError(false)}，从而关闭对话框。这种非侵入式的、与应用设计语言一致的错误提示，比系统弹窗友好得多。

在实际项目中，你还可以根据后端返回的错误码（如error.response.status）来显示更具体的错误信息，比如“网络连接失败”、“您没有删除权限”或“该问题已被删除”，从而提供更具指导性的反馈。

6. 生产环境加固：性能、可访问性与边界情况

功能做完了，但在上线前，我们还得从更高维度审视一下，让它更经得起考验。这包括性能优化、可访问性完善以及对各种边界情况的处理。

6.1 性能优化：请求取消与内存泄漏预防

想象一个场景：用户点击删除，请求发出后，在等待响应的过程中，他突然切换到了其他页面。这时，原来的组件被卸载（unmount），但那个删除请求可能还在后台运行。如果请求完成后，它试图去更新一个已卸载组件的状态（比如setDeleting(false)），React会报一个内存泄漏的警告。

为了解决这个问题，我们可以使用axios的取消令牌（Cancel Token）或者更现代的AbortController。这里以AbortController为例：

// 在handleDelete函数内
const handleDelete = async () => {
  if (isDeleting) return;
  setDeleting(true);
  setError(false);

  const controller = new AbortController(); // 创建AbortController

  try {
    await axios.delete(`/api/issues/${issueId}`, {
      signal: controller.signal, // 将signal传入请求配置
    });
    router.push("/issues");
    router.refresh();
  } catch (error) {
    // 只有当错误不是由取消请求引起时，才设置错误状态
    if (!axios.isCancel(error)) {
      setError(true);
      setDeleting(false);
      console.error("Delete failed:", error);
    }
  }
};

// 在组件卸载时取消请求（使用useEffect）
useEffect(() => {
  return () => {
    // 组件卸载时，取消所有未完成的请求
    // 你需要一个更全局的方式来管理controller，这里仅为示例
    // 一种常见做法是使用一个ref来存储controller
  };
}, []);

虽然在这个简单的按钮组件中，内存泄漏警告可能影响不大，但在复杂应用或频繁操作的场景下，养成管理副作用的习惯至关重要。

6.2 可访问性（A11y）增强

Radix UI组件已经提供了很好的可访问性基础，比如正确的ARIA属性、键盘导航和焦点管理。但我们还可以做得更好：

为按钮添加更明确的ARIA标签：对于屏幕阅读器用户，可以更清晰地描述按钮状态。

<Button 
  color="red" 
  disabled={isDeleting}
  aria-label={isDeleting ? "Deleting issue, please wait" : "Delete this issue"}
>
  <Cross2Icon aria-hidden="true" /> {/* 对屏幕阅读器隐藏图标 */}
  Delete Issue
  {isDeleting && <Spinner aria-label="Loading" />}
</Button>

错误对话框的焦点管理：确保错误对话框弹出时，焦点能自动移动到对话框内，并且被限制在对话框内循环（Radix UI已默认处理）。关闭对话框后，焦点应返回到触发它的元素上。

6.3 处理边界情况

并发操作：如果用户极快地连续打开多个Issue标签页，并在其中一个页面删除了某个Issue，其他标签页再操作时就会遇到404。我们的API已经处理了“记录不存在”的情况（返回404），前端也会收到错误提示。这是一种可接受的处理方式。
数据乐观更新：为了极致的用户体验，我们可以考虑“乐观更新”。即在请求发出后、尚未收到成功响应前，就立即在前端更新UI（如从列表移除该Issue）。如果请求最终失败，再回滚UI并提示错误。这能带来“瞬时响应”的感觉，但实现复杂度较高，需要谨慎处理回滚逻辑。对于删除操作，由于是不可逆的，采用保守的“等待确认后再更新”策略（即我们当前的做法）更为稳妥。
离线处理：在PWA或需要考虑离线能力的应用中，删除操作可能需要被放入队列，待网络恢复后同步。这涉及到更复杂的状态管理（如Redux、Zustand）和服务端同步策略，超出了本文范围，但它是构建健壮应用的一个重要方向。

经过以上六个步骤的打磨，我们从零开始，构建了一个不仅功能完整，而且在用户体验、代码健壮性和生产就绪度上都经得起推敲的Issue删除功能。这个过程清晰地展示了在现代全栈开发中，如何将前端交互、后端逻辑和状态管理有机地结合在一起。下次当你需要实现类似功能时，不妨也沿着“UI -> API -> 连接 -> 状态与反馈 -> 生产加固”这条路径思考，相信你也能写出让团队放心、让用户舒心的代码。

标签