一、为什么请求方法会“打架”？

在 API 开发里，请求方法和状态码的搭配经常让人头疼。有人用 POST 去更新数据，用 GET 去删除数据，返回状态码一律 200。前端拿到响应之后还得自己猜到底成没成功，后端写起来倒是省事，可前后端协作就像两个人各说各话，时间一长必然出乱子。

打个比方：你去餐厅吃饭，菜单上写着“1号菜、2号菜”，结果你跟服务员说“来一份3号”，服务员却端上来一碗汤，还说“3号就是汤，你没看新菜单吧？”问题就出在——大家没按同一个规则沟通。HTTP 请求方法和状态码，就是前后端之间约定好的“菜单”。如果谁都不看菜单，最终就是一团乱麻。

1.1 生活里的比喻

把请求方法想象成你回家开门的方式：

  • GET：从猫眼往外看。只看不碰，安全无害。
  • POST：往门里塞快递。每次塞一个新东西，多塞几次，门里就多几个盒子。
  • PUT：把门整个拆下来换一扇新门。不管原来什么样，换了之后就是全新的。
  • PATCH：门掉漆了，拿油漆补一下。只修坏掉的地方。
  • DELETE：把门锁拆了扔掉。东西没了，别指望还能找回来。

这么一对比，是不是立刻明白了几分？HTTP 的方法不多，可很多人只会背名字，真正用的时候却完全不分。就像一个人认识几个汉字，组词时全都乱了。

1.2 语义冲突的常见场景

常见的冲突场景其实就那么几种：

  • 用 GET 做删除操作。浏览器会缓存 GET 请求，爬虫也会顺着链接抓取，稍不注意数据就没了。
  • 用 POST 做所有操作。新增用 POST，更新也用 POST，删除还用 POST。服务端只能靠一个额外字段判断意图，代码越写越乱。
  • 不管什么结果都返回 200。明明资源不存在也返回 200，前端只能在响应体里翻来翻去找错误标记。

这些冲突的本质，就是没想清楚“动词”和“反馈”的关系。接下来我们逐个拆解。

二、请求方法到底该怎么用？

技术栈：Node.js + Express（示例代码基于 v4.x）。下面的代码片段都是同一个 app.js 文件里的内容，按顺序拼接即可运行。

2.1 GET：去书架拿书

GET 是安全的，也是幂等的。所谓幂等，就是无论请求多少次，服务端数据都不会变，结果都一样。适合查列表、查详情。比如拿一本书的信息：

// 导入 Express 并创建应用
const express = require('express');
const app = express();

// 模拟一个数据库：图书列表
let books = [
  { id: 1, name: '活着', price: 30 },
  { id: 2, name: '三体', price: 99 }
];

// GET /books 获取所有图书
app.get('/books', (req, res) => {
  res.status(200).json(books); // 200 表示成功，返回图书数组
});

// GET /books/:id 获取指定图书
app.get('/books/:id', (req, res) => {
  const id = Number(req.params.id);
  const book = books.find(item => item.id === id);

  if (!book) {
    // 找不到资源，返回 404，比返回 200 更诚实
    res.status(404).json({ message: '这本书不存在' });
    return;
  }

  res.status(200).json(book); // 找到就返回这本书的数据
});

2.2 POST：往盒子里放新东西

POST 通常用来创建资源。它不是幂等的，因为你每次 POST，都会多出一条新数据。比如新增一本书：

// 让 Express 能解析 JSON 请求体
app.use(express.json());

// POST /books 新增一本书
app.post('/books', (req, res) => {
  const { name, price } = req.body;

  if (!name || price === undefined) {
    // 客户端给的数据不全，返回 400
    res.status(400).json({ message: '缺少书名或价格' });
    return;
  }

  const newBook = {
    id: books.length + 1,
    name,
    price
  };
  books.push(newBook);
  // 201 表示“创建成功”，比 200 更贴切
  res.status(201).json(newBook);
});

2.3 PUT：整个换新

PUT 的意思是“把这个资源整体替换掉”。客户端需要提供完整的资源信息，不提供就相当于把没给的字段清空。PUT 是幂等的，执行一次和十次，最终结果一样。比如用 PUT 更新一本书的全部字段：

// PUT /books/:id 整体替换一本书
app.put('/books/:id', (req, res) => {
  const id = Number(req.params.id);
  const index = books.findIndex(item => item.id === id);

  if (index === -1) {
    res.status(404).json({ message: '书不存在' });
    return;
  }

  const { name, price } = req.body;
  // 整体替换，name 和 price 必须都给
  if (!name || price === undefined) {
    res.status(400).json({ message: '需要提供完整的 name 和 price' });
    return;
  }

  books[index] = { id, name, price };
  res.status(200).json(books[index]);
});

因为 PUT 是幂等的，所以网络超时后重试也没关系，反正最终结果一样。可如果用 POST 做更新，重试一次就多发一次请求，可能造成重复更新，还得靠额外字段去重。

2.4 PATCH：小修小补

PATCH 是部分更新。只修改客户端传过来的字段，其他字段原样保留。比如只改价格：

// PATCH /books/:id 部分更新一本书
app.patch('/books/:id', (req, res) => {
  const id = Number(req.params.id);
  const book = books.find(item => item.id === id);

  if (!book) {
    res.status(404).json({ message: '书不存在' });
    return;
  }

  // 只更新传入的字段，没传的就保持原样
  if (req.body.price !== undefined) {
    book.price = req.body.price;
  }
  if (req.body.name !== undefined) {
    book.name = req.body.name;
  }

  res.status(200).json(book);
});

2.5 DELETE：扔东西

DELETE 用来删除资源。严格来说，DELETE 也是幂等的，但幂等不意味着每次都能成功，而是说删除第二次时应该返回合理的结果，比如 404。看示例：

// DELETE /books/:id 删除一本书
app.delete('/books/:id', (req, res) => {
  const id = Number(req.params.id);
  const index = books.findIndex(item => item.id === id);

  if (index === -1) {
    // 本来就不存在，返回 404 比返回 200 更准确
    res.status(404).json({ message: '要删除的书不存在' });
    return;
  }

  books.splice(index, 1);
  // 204 表示“没有内容”，删除成功且无需返回 body
  res.status(204).send();
});

三、状态码其实在讲故事

状态码是服务端给客户端的“反馈”。客户端看到数字，就该知道大概发生了什么。用生活化的理解：状态码就是服务员在你点完菜后告诉你的结果。200 是“好的，马上来”；404 是“这个菜我们没有”；500 是“厨房着火了，我们也很无奈”。

HTTP 状态码就像红绿灯：2xx 是绿灯，一路畅通；4xx 是黄灯，你的请求有问题；5xx 是红灯，服务端出了状况。

3.1 2xx：一切正常

  • 200 最常用，表示“响应成功，这是你要的数据”。
  • 201 表示“创建成功”，通常用在 POST 之后，比 200 更精准。
  • 204 表示“没有内容”，适合删除操作，或者只需要告诉客户端“成了，但没什么数据给你”。

3.2 4xx：你（客户端）搞错了

客户端发来的请求有问题，或者权限不够。常见的有：

  • 400：请求格式不对，比如 JSON 解析失败、缺字段。
  • 401：没登录，或者登录凭证失效。
  • 403：登录了但没有权限，比如普通用户想删管理员。
  • 404：资源不存在，或者路径写错了。
  • 405：方法不对，比如只开放了 GET，你非要 POST。
  • 409：资源状态冲突，比如要注册的用户名已经被占用了。

3.3 5xx：我（服务端）出问题了

5xx 表示服务端处理请求时发生了错误。常见的是 500 内部错误，还有 502 网关错误、503 服务暂时不可用。遇到 5xx，客户端最好不要马上重试，等一等再说。

四、避免语义冲突的最佳实践

把请求方法和状态码配合起来，才能讲出一个完整的故事。下面是几个核心做法。

4.1 让请求方法做对事

  • 查询用 GET，新增用 POST，整体更新用 PUT，部分更新用 PATCH，删除用 DELETE。
  • 不要用 GET 去修改数据，因为 GET 会被浏览器缓存、预加载，甚至被爬虫抓取。你把删除操作写在 GET 里，搜索引擎一爬，数据全没了。
  • POST 可以做“非标准”操作，比如触发退款、发送邮件。因为 POST 不要求幂等，也允许带请求体，灵活性最高。

4.2 让状态码说对话

  • 成功不只有 200，创建用 201，删除用 204。
  • 失败要诚实：缺参数给 400，没登录给 401，没权限给 403，找不到给 404。
  • 不要在 200 里塞错误信息，比如写 return res.status(200).json({ code: 0, message: 'error' })。这会让前端被迫检查 body 里的错误标记。如果 HTTP 状态码已经表达错误，前端只需要判断 status 就够了。

4.3 组合拳示例

下面用一个“注册用户”的接口，把方法和状态码的配合完整串起来。技术栈依然是 Node.js + Express。

// 模拟已存在的用户名
const existingUsers = ['tom', 'jerry'];

// POST /register 注册
app.post('/register', (req, res) => {
  const { username, password } = req.body;

  // 缺字段：400
  if (!username || !password) {
    res.status(400).json({ message: '用户名和密码都不能为空' });
    return;
  }

  // 用户名被占用：409 冲突，比 400 更准确
  if (existingUsers.includes(username)) {
    res.status(409).json({ message: '用户名已被注册' });
    return;
  }

  // 注册成功：201
  existingUsers.push(username);
  res.status(201).json({ message: '注册成功' });
});

// 统一处理未知路径：404
app.use((req, res) => {
  res.status(404).json({ message: '接口不存在' });
});

// 统一错误处理：500
app.use((err, req, res, next) => {
  console.error(err); // 打印日志，便于排查
  res.status(500).json({ message: '服务器开小差了' });
});

// 启动服务，监听 3000 端口
app.listen(3000, () => {
  console.log('服务已启动：http://localhost:3000');
});

这个例子展示了 400、409、201、404、500 五个状态码的典型用法。前端只需要根据 HTTP 状态码做判断，逻辑会非常清晰。

接下来，用 Node.js 内置的 fetch 写一个测试脚本，看看接口表现。技术栈依然是 JavaScript（Node.js 18+）。

// 测试脚本：test-register.js
const baseUrl = 'http://localhost:3000';

async function testRegister() {
  // 第一次：缺少密码，预期返回 400
  const res1 = await fetch(baseUrl + '/register', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username: 'alice' })
  });
  console.log('第一次请求状态码：', res1.status);

  // 第二次：正常注册，预期返回 201
  const res2 = await fetch(baseUrl + '/register', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username: 'alice', password: '123456' })
  });
  console.log('第二次请求状态码：', res2.status);

  // 第三次：重复注册，预期返回 409
  const res3 = await fetch(baseUrl + '/register', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username: 'alice', password: '123456' })
  });
  console.log('第三次请求状态码：', res3.status);
}

testRegister();

运行这个测试脚本的前提是先启动上面的 Express 服务。你会发现，不用看返回内容，只看状态码就能立刻判断出每一次请求的结果。这就是语义清晰带来的好处。

4.4 反模式对照

再总结几个常见的“反模式”，帮你躲开坑：

  • 反模式：删除操作返回 200 + 一个 JSON 里写删除成功。其实返回 204 更好，因为客户端不需要任何内容。
  • 反模式：未登录也返回 401 和 200 都有。正确的是明确用 401 告诉前端“去跳登录页”。
  • 反模式：参数校验失败返回 500。这是服务端的错，不是客户端的错，应该返回 400。
  • 反模式：POST 和 PUT 混用。有些团队觉得“反正前端能看见 body”，于是 POST 也用来替换资源。这会让缓存、日志、后端语义全乱掉。

五、应用场景与优缺点分析

5.1 适合这样用的场景

  • 前后端分离的项目：前端通过 fetch 或 axios 调用接口，HTTP 状态码可以直接决定 UI 的展示逻辑。
  • 开放 API 平台：第三方开发者需要靠明确的语义来对接，方法和状态码一旦含糊，文档就得写得很复杂。
  • 微服务架构：服务之间互相调用，如果每个服务都有自己的一套“状态码黑话”，排查问题会非常痛苦。

5.2 这样做的优点

  • 沟通成本降低：前端看到 201 就知道创建成功，看到 404 就知道参数里的 id 有问题，连代码都不用细看。
  • 缓存和代理友好：GET 配合状态码，可以天然利用 HTTP 缓存机制，减少不必要的请求。
  • 错误排查更快：服务端日志里记录的是“POST /books 返回 500”，你立刻知道是服务端炸了，而不是前端传参问题。
  • 符合 RESTful 风格，团队成员换人之后，学习成本低，代码读起来像文档。

5.3 可能带来的麻烦

  • 严格区分 PUT 和 PATCH 需要多写一些判断逻辑，代码量略增。
  • 有的团队已经习惯用 200 + 自定义 code 做业务错误，突然改成 HTTP 状态码，前端需要统一封装，会有迁移成本。
  • 某些老旧的浏览器或代理服务器会对 4xx、5xx 做特殊处理，比如拦截响应体，偶尔会踩坑。

但这些麻烦，相比语义混乱带来的维护成本，是值得的。

六、注意事项

实际开发中，有几个细节要特别注意。

第一，不要过度追求“标准”。比如严格 REST 主义者会把登录设计成 POST /login，而不是 GET /login，很多大厂也这么做。这没问题，只要团队内部统一就好。

第二，幂等性要理解透彻。PUT 和 DELETE 是幂等的，POST 不是。如果你用 POST 实现更新操作，网络超时后前端重试，可能造成重复更新。用 PUT 就不怕重试，因为结果都一样。

第三，状态码不是越多越好。对外提供的 API，把常用的 200、201、204、400、401、403、404、409、500 处理好，已经覆盖绝大多数场景。不要为了炫技硬套 418 这种“你可能是个茶壶”的笑话状态码。

第四，错误信息要友好。虽然状态码能表达分类，但 body 里最好还有人类可读的说明，比如 { message: '用户名太短' }，这样前端能直接提示给用户。

第五，处理 5xx 时要记录日志，并尽量返回通用的错误信息。不要把堆栈信息直接暴露给客户端，这是安全底线。

第六，团队协作时要把这套规范写进接口文档，并且用代码评审去约束。不然规则再好，没人遵守也白搭。

七、总结

请求方法和状态码是 HTTP 协议给我们的“共同语言”。方法决定了“你想做什么”，状态码决定了“做成了没有”。把它们用得规范，前后端协作就能像两个默契的同事一样，不用反复确认。这里的关键就是：方法别乱用，状态码别掩盖错误，错误信息要清楚。刚开始你可能觉得多写几个分支很麻烦，但一旦形成习惯，API 会变得优雅、可维护，也让你自己少接凌晨三点的报警电话。如果你正在为接口风格不统一而烦恼，不妨从今天开始，重新整理一遍你的请求方法和状态码。你会发现，原来让接口“说人话”并不难，难的是你愿不愿意先立下规矩。