XState guard与action怎样分工

在 XState 里，guard 和 action 不是两个都能“顺便写点逻辑”的配置项。可以把它们记成一句话：guard 负责回答“这条 transition 能不能走”，action 负责回答“走了以后要改变什么或安排什么副作用”。前者应该是同步、可重复计算的判断，后者才承接更新 context、记录日志或通知外部系统。

官方地址：https://stately.ai/docs

遇到“应该放 guard 还是 action”的问题，先看这段逻辑是否会改变状态选择：会，就放 guard；不会，只是在已选中的 transition 上更新数据或安排工作，就放 action。异步请求不要放进 guard，应由 actor 处理结果，再用 guard 判断结果。

先分清：guard 决定路径，action 执行处理

假设一个反馈表单收到 submit 事件。邮箱格式不合法时，机器应该留在编辑态；合法时才进入提交态。这是 guard 的工作。进入提交态以后，把提交次数加一、清空提示或发送埋点，是 action 的工作。

因此两者的判断标准不同：

官方文档中的 guarded transition 只有在 guard 返回真时才会被选中；action 不负责替代路由判断。把判断藏在 action 里，状态机仍可能已经走到了错误的状态，后续排查会变得困难。

用一个提交表单例子拆开两种职责

下面的示例以 XState v5 常用写法为边界。isValidEmail 只读取传入的数据并返回布尔值；saveSubmit 使用 assign 更新 context。代码里的中文注释只解释关键边界，不把每一行都翻译一遍。

import { assign, setup } from 'xstate';

const feedbackMachine = setup({
  types: {
    context: {} as { email: string; submitCount: number; error: string },
    events: {} as
      | { type: 'change'; value: string }
      | { type: 'submit' },
  },
  guards: {
    // guard 只做同步判断，不发请求、不写日志，也不改 context。
    isValidEmail: ({ context }) =>
      /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(context.email),
  },
  actions: {
    // action 在 transition 被选中后更新数据；更新应保持不可变。
    saveSubmit: assign({
      submitCount: ({ context }) => context.submitCount + 1,
      error: () => '',
    }),
    // 这个 action 只负责把校验提示写回 context，不决定目标状态。
    showInvalidEmail: assign({
      error: () => '请输入有效邮箱',
    }),
  },
}).createMachine({
  id: 'feedback',
  initial: 'editing',
  context: { email: '', submitCount: 0, error: '' },
  states: {
    editing: {
      on: {
        change: { actions: assign({ email: ({ event }) => event.value }) },
        submit: [
          {
            guard: 'isValidEmail',
            target: 'submitting',
            actions: 'saveSubmit',
          },
          {
            // 兜底分支没有 target，仍停留在 editing。
            actions: 'showInvalidEmail',
          },
        ],
      },
    },
    submitting: {},
  },
});

这里最值得记住的是 submit 的两个候选 transition：第一条 guard 通过才会把状态送到 submitting，第二条是失败时的兜底 action。showInvalidEmail 可以更新提示，但它没有资格“假装提交成功”；成功与否仍由 transition 的 target 表达。

遇到异步逻辑时，别把请求塞进 guard

例如提交前要向服务端检查优惠码是否可用。guard 不应该直接 await 请求，因为它需要在 transition 选择阶段同步给出结果，而且网络失败、超时和重试本身都属于状态机需要表达的状态。

更稳妥的拆法是：先进入 checking，由 invoked actor 请求服务；actor 产出 VALID 或 INVALID 事件后，再用 guard 判断本地结果，最后用 action 保存消息或记录埋点。这样“等待外部结果”和“根据结果选择路径”不会混在同一个函数里。

如果只需要根据当前 context 分支，可以使用命名 guard；如果只是把结果写入 context，使用 assign action；如果要通知别的 actor，使用 sendTo 等内置 action。内置 action creator 返回的是由状态机解释的 action 对象，不要在普通自定义 action 函数里调用后却不把它交给状态机。

三个容易混用的边界

• 校验失败提示：校验条件属于 guard，写入提示文本属于 action；不要让 action 自己决定是否跳转。
• 更新 context：属于 action，优先用 assign，不要直接修改当前 context 对象。
• 副作用：日志、埋点、发消息属于 action 或 actor；需要等待结果的工作放到 actor，而不是让 guard 变成隐藏的网络客户端。

还要留意版本边界。本文示例采用 XState v5 的 guard 属性和 action 配置；官方站点同时提供 v6 alpha 文档，v6 的 transition function 会在函数内部判断并返回目标，不能把那套示例中的写法直接拼到 v5 配置里。项目升级时应先确认依赖版本，再按对应迁移文档调整。

速查：到底该把代码放哪里

实际写代码时，先在纸上写出“事件—条件—目标状态—处理动作”四列。条件放 guard，目标写在 transition，处理动作放 action，外部等待放 actor。这样状态图会继续表达业务决策，action 也不会变成一个塞满分支和请求的万能函数。

相关问题

XState 的 guard 可以读取 event 吗？

可以。guard 可以根据 context 和 event 做同步判断，但应只读取所需数据，不在判断过程中产生副作用。

action 能不能决定下一个状态？

不建议。下一个状态应由 transition 的 target 和 guard 共同表达；action 负责选中之后的更新或副作用。