alang.ai

007 更改数据与 Server Actions ​

目录

https://nextjs.org/learn/dashboard-app/mutating-data

本文对应 Next.js Learn 入门教程的第 12 章。

Server Actions ​

What are Server Actions?

React Server Actions allow you to run asynchronous code directly on the server. They eliminate the need to create API endpoints to mutate your data. Instead, you write asynchronous functions that execute on the server and can be invoked from your Client or Server Components.

Security is a top priority for web applications, as they can be vulnerable to various threats. This is where Server Actions come in. They offer an effective security solution, protecting against different types of attacks, securing your data, and ensuring authorized access. Server Actions achieve this through techniques like POST requests, encrypted closures, strict input checks, error message hashing, and host restrictions, all working together to significantly enhance your app's safety.

Server Actions 是什么？

React 服务器操作允许你直接在服务器上运行异步代码。它们消除了创建 API 端点以变更数据的需求。相反，你编写在服务器上执行并且可以从客户端或服务器组件调用的异步函数。

对于 Web 应用程序来说，安全性是首要考虑的问题，因为它们可能对多种威胁敏感。这就是服务器操作发挥作用的地方。它们提供了一种有效的安全解决方案，防御不同类型的攻击，保护你的数据，并确保授权访问。服务器操作通过技术如 POST 请求、加密闭包、严格输入校验、错误信息哈希化和主机限制实现这一目标，所有这些措施共同作用，显著提高应用的安全性。

React 文档： https://react.dev/reference/react/use-server

'use server' is needed only if you’re using React Server Components or building a library compatible with them.

'use server' marks server-side functions that can be called from client-side code.

Form 与 Server Actions ​

Using forms with Server Actions

In React, you can use the action attribute in the <form> element to invoke actions. The action will automatically receive the native FormData object, containing the captured data.

For example:

tsx
// Server Component
export default function Page() {
  // Action
  async function create(formData: FormData) {
    'use server';

    // Logic to mutate data...
  }

  // Invoke the action using the "action" attribute
  return <form action={create}>...</form>;
}

An advantage of invoking a Server Action within a Server Component is progressive enhancement - forms work even if JavaScript is disabled on the client.

Next.js with Server Actions ​

Server Actions are also deeply integrated with Next.js caching. When a form is submitted through a Server Action, not only can you use the action to mutate data, but you can also revalidate the associated cache using APIs like revalidatePath and revalidateTag.

服务器操作（Server Actions）与 Next.js 的缓存系统有着深入的整合。当通过服务器操作提交表单时，你不仅可以使用该操作修改数据，还可以利用 API，例如 revalidatePath 和 revalidateTag，来重新验证（re-validate）相关缓存

What's one benefit of using a Server Actions?

B. Progressive Enhancement.

That's right! This allows users to interact with the form and submit data even if the JavaScript for the form hasn't been loaded yet or if it fails to load.

使用服务器端操作的一个好处是什么？

B. 渐进增强。

没错！即使表单的JavaScript尚未加载或者加载失败，这也让用户能够与表单交互并提交数据。

知识讨论 ​

AI 解读

'use server' 和 Server Actions 指的其实是 React 18+ 中引入的一种概念，它允许我们在 React 应用中编写可从客户端调用的服务器端逻辑。这种方式的好处之一确实是可以支持渐进增强（Progressive Enhancement）。

渐进增强是一种前端开发策略，意在保证在不支持某些特性（例如 JavaScript、CSS 进阶特性等）的环境下，应用或网页仍然能够提供基本的功能和可访问性。在这种情况下，即使没有加载完所有的 JavaScript 脚本或者脚本加载失败，用户依旧可以互动并提交数据。

在使用 Server Actions 的 React 应用中，表单处理逻辑可以部署在服务器上，而不是完全依赖于客户端 JavaScript。当客户端环境中 JavaScript 脚本未加载时，用户在表单上的操作（比如填写数据，点击提交按钮）可以直接发送到服务器上，服务器可以处理这些请求并给予相应，比如存储数据、发送响应等，而不需要等待客户端脚本完全加载和运行。

这就意味着即使在低端设备，或者当用户的网络速度慢、JavaScript 因某些原因加载失败时，服务器端的代码仍然可以保证用户基本的交互不受影响，从而提高了用户体验的健壮性和可访问性。

因此，Server Actions 的内在机制通过服务器端处理，为应用提供了一个安全网，以便在客户端技术不完全有效时也能正常工作。这是为何 Server Actions 能在没有加载客户端脚本的情况下仍然使得用户可以交互的原因。

创建新订单 ​

Creating an invoice

Here are the steps you'll take to create a new invoice:

  1. Create a form to capture the user's input.
  2. Create a Server Action and invoke it from the form.
  3. Inside your Server Action, extract the data from the formData object.
  4. Validate and prepare the data to be inserted into your database.
  5. Insert the data and handle any errors.
  6. Revalidate the cache and redirect the user back to invoices page.

以下是你创建新订单需要遵循的步骤：

  1. 创建一个表单，用以捕获用户输入的数据。
  2. 创建一个 Server Action ，并从表单中调用它。
  3. 在你的 Server Action 作内部，从formData对象中提取数据。
  4. 对数据进行验证，并准备将其插入到数据库中。
  5. 将数据插入数据库，并处理任何错误。
  6. 重新验证缓存，并将用户重定向回订单页面。

1. 创建一个表单，用以捕获用户输入的数据。 ​

/dashboard/invoices/create/page.tsx

2. 创建一个 Server Action ，并从表单中调用它。 ​

/app/lib/actions.ts

ts
'use server';

export async function createInvoice(formData: FormData) {}

/app/ui/invoices/create-form.tsx

tsx
import { customerField } from '@/app/lib/definitions';
import Link from 'next/link';
import {
  CheckIcon,
  ClockIcon,
  CurrencyDollarIcon,
  UserCircleIcon,
} from '@heroicons/react/24/outline';
import { Button } from '@/app/ui/button';
import { createInvoice } from '@/app/lib/actions';

export default function Form({
  customers,
}: {
  customers: customerField[];
}) {
  return (
    <form action={createInvoice}>
      // ...
  )
}

Good to know: In HTML, you'd pass a URL to the action attribute. This URL would be the destination where your form data should be submitted (usually an API endpoint).

However, in React, the action attribute is considered a special prop - meaning React builds on top of it to allow actions to be invoked.

Behind the scenes, Server Actions create a POST API endpoint. This is why you don't need to create API endpoints manually when using Server Actions.

在HTML中，你会将URL传递给action属性。此URL将是表单数据应当提交的目标位置（通常是一个API端点）。

然而，在React中，action属性被视为一个特殊的属性（prop）—— 这意味着React在其基础上构建，以便允许调用动作。

在幕后，Server Actions 创建一个POST API端点。这就是为什么当你使用服务器动作时，不需要手动创建API端点。

3. 在你的 Server Action 作内部，从formData对象中提取数据。 ​

（略）

4. 对数据进行验证，并准备将其插入到数据库中。 ​

INFO

Type validation and coercion

https://nextjs.org/learn/dashboard-app/adding-search-and-pagination#best-practice-debouncing#type-validation-and-coercion

It's important to validate that the data from your form aligns with the expected types in your database. For instance, if you add a console.log inside your action:

ts
console.log(typeof rawFormData.amount);

‼️ You'll notice that amount is of type string and not number. This is because input elements with type="number" actually return a string, not a number!

To handle type validation, you have a few options. While you can manually validate types, using a type validation library can save you time and effort. For your example, we'll use Zod, a TypeScript-first validation library that can simplify this task for you.

In your actions.ts file, import Zod and define a schema that matches the shape of your form object. This schema will validate the formData before saving it to a database.

Zod https://zod.dev/

Zod 的使用

ts
import { z } from 'zod';

const FormSchema = z.object({
  id: z.string(),
  customerId: z.string(),
  amount: z.coerce.number(),
  status: z.enum(['pending', 'paid']),
  date: z.string(),
});

const CreateInvoice = FormSchema.omit({ id: true, date: true });

export async function createInvoice(formData: FormData) {
    const rawFormData = {
        customerId: formData.get('customerId'),
        amount: formData.get('amount'),
        status: formData.get('status'),
    };

    const { customerId, amount, status } = CreateInvoice.parse(rawFormData);

      console.log(typeof amount);

}

这段代码使用 zod 库定义了 FormSchema 对表单数据进行验证。zod 是一个 用于创建和验证 JavaScript 对象的模式验证库。

FormSchema 对象包含以下字段：

  • id: 字符串类型
  • customerId: 字符串类型
  • amount: 数字类型，使用 z.coerce.number() 将输入强制转换为数字
  • status: 枚举类型，只能是 'pending' 或 'paid'
  • date: 字符串类型

之后，创建了一个新的模式 CreateInvoice，它是 FormSchema 的子集，但省略了 id 和 date 字段。

在函数中，首先从 formData 中获取 customerId、amount 和 status 字段的值。

然后，使用 CreateInvoice.parse 方法验证，检查是否符合 CreateInvoice 模式。如不符合，则会抛出一个错误。

打印 amount 的类型，由于它是通过 z.coerce.number() 强制转换为数字的，所以这里应该会打印 'number'。

5. 将数据插入数据库，并处理任何错误。 ​

ts
import { z } from 'zod';
import { sql } from '@vercel/postgres';

// ...

export async function createInvoice(formData: FormData) {
  const { customerId, amount, status } = CreateInvoice.parse({
    customerId: formData.get('customerId'),
    amount: formData.get('amount'),
    status: formData.get('status'),
  });
  const amountInCents = amount * 100;
  const date = new Date().toISOString().split('T')[0];

  await sql`
    INSERT INTO invoices (customer_id, amount, status, date)
    VALUES (${customerId}, ${amountInCents}, ${status}, ${date})
  `;
}
sql 标签函数解读
ts
await sql`
INSERT INTO invoices (customer_id, amount, status, date)
VALUES (${customerId}, ${amountInCents}, ${status}, ${date})
`;

在JavaScript和TypeScript中，标签函数是一种特殊的函数，它可以用来解析模板字符串。模板字符串是用反引号(``)包围的字符串，可以包含占位符，占位符由${}包围。

标签函数的名称（在这个例子中是sql）紧跟在模板字符串的前面，没有括号和逗号。这个函数会接收到两个参数：一个包含模板字符串中所有静态文本部分的数组，和一个包含所有占位符表达式的值的数组。

例如，下面的代码定义了一个标签函数tag：

javascript
function tag(strings, ...values) {
  console.log(strings);
  console.log(values);
}

let a = 5;
let b = 10;

tag`Hello ${a + b} world ${a * b}`;

在这个例子中，tag函数会打印出两个数组：['Hello ', ' world ', '']和[15, 50]。第一个数组是模板字符串中的静态文本部分，第二个数组是占位符表达式的值。

在你的代码中，sql函数可能是用来构建和执行SQL查询的。它会接收到模板字符串和占位符的值，然后构建一个安全的、参数化的SQL查询，防止SQL注入攻击。


可参考文档：

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals

6. 重新验证缓存，并将用户重定向回订单页面。 ​

Next.js has a Client-side Router Cache that stores the route segments in the user's browser for a time. Along with prefetching, this cache ensures that users can quickly navigate between routes while reducing the number of requests made to the server.

Since you're updating the data displayed in the invoices route, you want to clear this cache and trigger a new request to the server. You can do this with the revalidatePath function from Next.js:

Next.js 有一种客户端路由缓存机制，它能够在用户浏览器中存储路由信息片段一段时间。结合预取技术，该缓存确保用户能够在不同路由间快速导航，同时减少对服务器发起的请求次数。

由于你需要更新展示在发票路由上的数据，你会希望清除此缓存并触发对服务器的新请求。你可以通过 Next.js 的 revalidatePath 函数来实现这一点。

ts
'use server';

import { z } from 'zod';
import { sql } from '@vercel/postgres';
import { revalidatePath } from 'next/cache';

// ...

export async function createInvoice(formData: FormData) {
  const { customerId, amount, status } = CreateInvoice.parse({
    customerId: formData.get('customerId'),
    amount: formData.get('amount'),
    status: formData.get('status'),
  });
  const amountInCents = amount * 100;
  const date = new Date().toISOString().split('T')[0];

  await sql`
    INSERT INTO invoices (customer_id, amount, status, date)
    VALUES (${customerId}, ${amountInCents}, ${status}, ${date})
  `;

  revalidatePath('/dashboard/invoices');
}

redirect

ts
'use server';

import { z } from 'zod';
import { sql } from '@vercel/postgres';
import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';

// ...

export async function createInvoice(formData: FormData) {
  // ...

  revalidatePath('/dashboard/invoices');
  redirect('/dashboard/invoices');
}

更新发票记录 ​

Updating an invoice

https://nextjs.org/learn/dashboard-app/adding-search-and-pagination#best-practice-debouncing#updating-an-invoice

The updating invoice form is similar to the create an invoice form, except you'll need to pass the invoice id to update the record in your database. Let's see how you can get and pass the invoice id.

These are the steps you'll take to update an invoice:

  1. Create a new dynamic route segment with the invoice id.
  2. Read the invoice id from the page params.
  3. Fetch the specific invoice from your database.
  4. Pre-populate the form with the invoice data.
  5. Update the invoice data in your database.

更新发票的表单与创建发票的表单相似，不同之处在于你需要传递发票的 id 来更新数据库中的记录。让我们来看看如何获取并传递发票的 id。

以下是更新发票时你需要执行的步骤：

  1. 创建一个新的动态路由段，包含发票的 id。
  2. 从页面参数中读取发票 id。
  3. 从你的数据库中拉取特定的发票记录。
  4. 使用发票数据预填充表单。
  5. 在你的数据库中更新发票数据。

1. 创建一个新的动态路由段，包含发票的 id。 ​

Dynamic Route Segment

https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes

2. 从页面params中读取发票 id。 ​

In addition to searchParams, page components also accept a prop called params which you can use to access the id. Update your <Page> component to receive the prop:

tsx
export default async function Page({ params }: { params: { id: string } }) {
  const id = params.id;
  // ...
}

3. 从你的数据库中拉取特定的发票记录、使用发票数据预填充表单 ​

tsx
import Form from '@/app/ui/invoices/edit-form';
import Breadcrumbs from '@/app/ui/invoices/breadcrumbs';
import { fetchInvoiceById, fetchCustomers } from '@/app/lib/data';

export default async function Page({ params }: { params: { id: string } }) {
  const id = params.id;
  const [invoice, customers] = await Promise.all([
    fetchInvoiceById(id),
    fetchCustomers(),
  ]);
  // ...
}

INFO

UUIDs vs. Auto-incrementing Keys

We use UUIDs instead of incrementing keys (e.g., 1, 2, 3, etc.). This makes the URL longer; however, UUIDs eliminate the risk of ID collision, are globally unique, and reduce the risk of enumeration attacks - making them ideal for large databases.

However, if you prefer cleaner URLs, you might prefer to use auto-incrementing keys.

4. 在你的数据库中更新发票数据。 ​

Pass the id to the Server Action

https://nextjs.org/learn/dashboard-app/mutating-data#4-pass-the-id-to-the-server-action

Lastly, you want to pass the id to the Server Action so you can update the right record in your database. You cannot pass the id as an argument like so:

/app/ui/invoices/edit-form.tsx

tsx
// Passing an id as argument won't work
<form action={updateInvoice(id)}>

Instead, you can pass id to the Server Action using JS bind. This will ensure that any values passed to the Server Action are encoded.

Note: Using a hidden input field in your form also works (e.g. <input type="hidden" name="id" value={invoice.id} />). However, the values will appear as full text in the HTML source, which is not ideal for sensitive data like IDs.

‼️ 强制转换为 Number 类型在某些时候会出现问题！需要处理。

    ⨯ node_modules/@neondatabase/serverless/index.js (1539:47) @ execute
    ⨯ NeonDbError: invalid input syntax for type integer: "15794.999999999998"
        at async updateInvoice (./app/lib/actions.ts:63:5)

删除订单 ​

（略去）

https://nextjs.org/learn/dashboard-app/mutating-data#deleting-an-invoice

进一步阅读：

https://nextjs.org/blog/security-nextjs-server-components-actions

Alang.AI - Make Great AI Applications

Copyright © 2025