用 claude code 开发 RESTful API 时对 HTTP 状态码的使用是否正确

那天下午，我用 Claude Code 生成了一个用户登录接口。功能跑通了，前端能拿到 token，测试同事说“接口通了啊”。但当我打开代码，看到所有响应，包括密码错误、账号不存在、甚至服务器内部异常，一律返回 200 OK 加一个 body 里的 "code": 400 时，我默默关掉了浏览器，开始写这份审计报告。

这不是 Claude Code 独有的问题。我过去三个月里分别用 Cursor、Copilot、Claude Code 做了同一批 API 开发任务，然后逐个审计它们返回的 HTTP 状态码。核心结论很简单：没有一个 AI 编程工具默认能正确使用 HTTP 状态码。Claude Code 在语义理解上相对最好，但距离“生产可用”仍然差最后那 20%。

这 20% 是什么？就是当出错场景变复杂时，AI 倾向于走“捷径”，用一个 200 包住所有错误信息，或者把所有异常都扔进 500 Internal Server Error 的筐里。它写出的代码能跑，但作为 RESTful API，它的状态码使用是错的。

接下来，我会用我实际审计过的代码片段、对比表格、以及三个 Claude Code 项目里的真实案例，完整拆解这个问题。

一、我为什么要做这件事：审计动机与测试设计

1.1 这不是一个学术问题，这是一个生产事故隐患

去年我接手过一个项目，前任开发者用 AI 辅助写了整套订单系统 API。接口能调通，联调顺利，直到有一天运维发现监控告警异常：大量 500 错误在凌晨集中爆发。排查后发现，所有参数校验失败、库存不足、用户权限不够的场景，全部返回了 500 Internal Server Error。日志里混在一起，根本分不清哪些是真正的服务器故障，哪些只是业务规则拦截。

HTTP 状态码用错的代价，不只是“不规范”，而是让整个监控体系、告警链路、故障排查流程全部失效。

当你用 Claude Code 快速生成 API 时，这种风险不是降低了，而是因为生成速度变快、审查被跳过，系统性放大了。

1.2 审计实验设计

为了让结论可复现，我设计了一套标准测试环境：

被测对象：Claude Code（2025 年 6 月版本，模型 Claude 4 Sonnet），在 VS Code 插件内使用，未做额外微调或自定义 system prompt。

测试任务：构建一个电商用户中心 API 模块，包含：

• POST /api/users/register ， 用户注册
• POST /api/users/login ， 用户登录
• GET /api/users/{id} ， 获取用户信息
• PUT /api/users/{id}/password ， 修改密码
• DELETE /api/users/{id} ， 注销用户

关键约束：我没有给 Claude Code 任何关于 HTTP 状态码的额外指令。我只描述了业务功能和基本的输入输出字段。我想测试的是：AI 在没有被“教育”的情况下，默认会产生什么样的状态码行为。

审计标准：以 RFC 7231（HTTP/1.1 Semantics and Content）和 RFC 7807（Problem Details for HTTP APIs）为基准，结合行业主流实践（如 Stripe、GitHub、Twilio 的公开 API 规范）。

1.3 审计清单：七个核心锚点

我把审计聚焦在七个最容易出错的状态码决策点上：

这七个点，是我在审查了超过 200 个 AI 生成 API 接口后提炼出的“高频错误区”。接下来，我逐项展示 Claude Code 的表现。

二、审计结果：Claude Code 的详细表现

2.1 及格项：基本的语义认知正确

先说我看到的积极部分。Claude Code 在以下几个场景下，没有任何犹豫地使用了正确的状态码：

资源创建返回 201 Created

这是我给它注册接口的 Prompt：

创建一个用户注册接口，接收 username、email、password 三个字段，
在数据库中创建用户后返回用户信息。

Claude Code 生成的代码（Node.js Express 框架）：

router.post('/register', async (req, res) => {
try {

const { username, email, password } = req.body;

const user = await userService.create({ username, email, password });

res.status(201).json({

id: user.id,

username: user.username,

email: user.email,

createdAt: user.createdAt

});

} catch (error) {

// 异常处理...

}

});

这里有个细节值得注意：它不仅用了 201，还知道不应该返回 password 字段。这说明 Claude Code 对“创建资源”的 HTTP 语义理解是到位的。

认证失败返回 401 Unauthorized

在登录接口中，当密码错误时，生成的代码是：

if (!isPasswordValid) {
return res.status(401).json({

error: 'Invalid credentials'

});

}

401 的使用是正确的。而且它没有画蛇添足地去区分“用户不存在”和“密码错误”，这种模糊化处理恰恰是最佳安全实践（防止用户枚举攻击）。

资源不存在返回 404 Not Found

获取用户信息时，对不存在的用户 ID，生成的代码是：

if (!user) {
return res.status(404).json({

error: 'User not found'

});

}

这三个场景说明：Claude Code 在“教科书级”的典型场景下，状态码使用是准确的。 它是合格的初级开发者水平。问题出在复杂的边界情况。

2.2 红灯区一：200 OK 的滥用，什么时候它开始“偷懒”

当我让 Claude Code 生成一个完整的 API 模块文件后，我发现一个规律：当接口的异常处理逻辑变复杂时，Claude Code 开始在某些分支上退化到“所有响应都包 200”的模式。

具体案例：修改密码接口。我给的 Prompt 是：

创建一个修改密码接口，需要验证旧密码、新密码长度至少 8 位、
不能与旧密码相同，修改成功后发送通知邮件。

Claude Code 生成的代码中，通知邮件发送失败的场景：

// 密码修改成功
await userService.updatePassword(userId, newPassword);

// 发送通知邮件

try {

await emailService.sendPasswordChangeNotification(user.email);

} catch (emailError) {

// 邮件发送失败不影响密码修改结果

return res.status(200).json({

message: 'Password updated successfully',

warning: 'Failed to send notification email'

});

}

res.status(200).json({

message: 'Password updated successfully'

});

业务逻辑本身没问题：邮件失败不应该回滚密码修改。但这两处返回 200 是错的。

正确的做法应该是：

• 邮件发送失败的场景：密码已修改成功，这是部分成功状态，合理的选择是 202 Accepted（密码修改操作已完成，但通知仍在处理中），或者如果你认为前端不需要区分，至少也应该确保主流程的一致性。
• 更严格的设计是：主流程成功用 200，邮件异步处理，接口直接返回 202 表示已接受请求、处理中。

但 Claude Code 选择了最省事的路径：两个分支都 200，让调用方自己看 body 区分。

2.3 红灯区二：500 是个筐，什么都往里装

这是我审计中最严重的问题，也是生产事故的主要来源。

看 Claude Code 对注册接口异常处理生成的代码：

router.post('/register', async (req, res) => {
try {

const { username, email, password } = req.body;

// 参数校验

if (!username || !email || !password) {

throw new Error('Missing required fields');

}

if (password.length < 8) {

throw new Error('Password too short');

}

// 检查用户名是否已存在

const existingUser = await userService.findByUsername(username);

if (existingUser) {

throw new Error('Username already exists');

}

const user = await userService.create({ username, email, password });

res.status(201).json({ /* ... */ });

} catch (error) {

// 问题在这里：

res.status(500).json({

error: error.message

});

}

});

这段代码把所有业务异常全部返回 500 Internal Server Error。 包括“缺少必填字段”、“密码太短”、“用户名已存在”，这些全部是客户端错误，应该是 400 或 409 Conflict，而不是 500。

500 的含义是“服务器遇到了意外情况，无法完成请求”。缺少必填字段绝不是“意外情况”，它是“客户端没有提供完整信息”。

这个问题的根源在于 try-catch 的模式：Claude Code 习惯性地用一个大的 try-catch 包裹所有逻辑，然后在 catch 里统一返回 500。这不是“不懂 HTTP”，而是“写代码太快，没来得及想异常分层”。

2.4 红灯区三：404 和 403 的边界模糊

在用户注销接口的审计中，我发现了另一个值得讨论的问题。

Prompt：

创建用户注销接口，需要验证用户身份后才能注销，注销后标记用户状态为 deleted。
Claude Code 生成的代码：

router.delete('/users/:id', authenticate, async (req, res) => {
try {

const targetUserId = parseInt(req.params.id);

const currentUserId = req.user.id;

// 只能注销自己的账号，管理员除外

if (currentUserId !== targetUserId && req.user.role !== 'admin') {

return res.status(403).json({

error: 'You can only delete your own account'

});

}

const user = await userService.findById(targetUserId);

if (!user) {

return res.status(404).json({

error: 'User not found'

});

}

await userService.softDelete(targetUserId);

res.status(204).send();

} catch (error) {

res.status(500).json({

error: 'Internal server error'

});

}

});

这段代码的两个核心判断：

• 权限不足返回 403：正确。
• 用户不存在返回 404：技术正确，但存在安全隐患。

为什么说存在安全隐患？因为 404 告诉请求方“这个 ID 对应的用户不存在”，攻击者可以利用这个信息进行用户枚举。更好的做法是：当请求者没有权限操作该资源时，统一返回 404，让攻击者分不清是“资源不存在”还是“你没权限”。

同样的逻辑在获取用户信息接口中也存在：隐私设计上，对于无权访问的资源，应该返回 404 而非 403，避免暴露资源是否存在这个事实。

Claude Code 没有做这个安全上的权衡，它按“教科书”做了，但不一定适合你的业务场景。

2.5 红灯区四：201 Created 的“遗忘症”

前面我表扬了 Claude Code 在注册接口正确使用了 201。但当我把任务切换到一个批量操作场景时，它就开始不稳定了。

Prompt：

创建一个批量导入用户接口，接收一个 JSON 数组，每个元素包含 username、email，
成功导入后返回导入结果。

Claude Code 生成的部分响应代码：

// 批量导入结果
const result = {

total: users.length,

success: importedUsers.length,

failed: failedUsers.length,

importedUsers: importedUsers.map(u => ({ id: u.id, username: u.username }))

};

res.status(200).json(result);

这里有两个问题：

1. 批量创建资源，最优实践是返回 200 加详细结果（因为部分成功是常见情况），这个选择不算错。
2. 但如果全部成功，更精确的语义是 201。Claude Code 没有做这个区分，它可能觉得“已经有 200 了，够用了”。

三、问题根源：AI 为什么会写出错误的状态码

3.1 训练数据的“污染”：互联网上大量 API 本身就是错的

这不是为 AI 开脱，而是陈述一个事实：Claude Code 的训练语料里，包含了海量的“滥用 200”和“乱用 500”的代码示例。

我抽查了 GitHub 上 50 个中等 star 数的 Express/Flask API 项目，发现：

• 46% 的项目在所有错误场景下统一返回 200 + 自定义 code
• 32% 的项目在参数校验失败时返回 500
• 仅 22% 的项目遵循了相对严格的 HTTP 状态码规范

当 AI 从这些代码中学习时，它“看到”的世界就是“大家都不太在意状态码”。所以它的默认行为倾向于“能跑就行”。

3.2 生成目标的优先级：功能实现 > 语义正确

Claude Code 在生成代码时，被优化的目标是“让功能跑通”。它优先确保：

1. 代码语法正确，没有编译/运行错误
2. 主流程逻辑符合 Prompt 描述
3. 异常不导致进程崩溃

而“HTTP 状态码的语义正确性”在这个优先级列表里排得很靠后。 因为没有测试用例会因为“返回了 200 而不是 201”而报红。

3.3 缺乏业务上下文：AI 不知道你的“约定”

实际项目中，API 设计有很多“非书面规则”：

• 有些团队约定“所有业务错误用 200 + code”
• 有些团队严格要求“业务错误必须用 4xx”
• 有些安全敏感的团队要求“404 和 403 模糊处理”

Claude Code 不知道你的团队约定是什么。 除非你在 Prompt 或 CLAUDE.md 中明确写下这些规范。

3.4 try-catch 模式的结构性缺陷

这是我观察到的最直接的代码生成问题。Claude Code 生成的异常处理结构通常长这样：

try {
所有业务逻辑

} catch (error) {

res.status(500).json({ error: error.message })

}

这种结构本质上把“预期内的业务异常”和“真正的系统故障”混在了一起。在代码执行时，throw new Error('用户名已存在') 和 throw new Error('数据库连接失败') 走的是同一个 catch 分支。

正确的做法是分层处理：

1. 参数校验 → 立即返回 400

业务规则校验 → 立即返回 409/422
数据库操作 → try-catch，返回 500

Claude Code 不是不会写分层异常处理，如果你在 Prompt 里明确要求“参数校验失败返回 400”、“业务冲突返回 409”，它能写出来。但默认模式下，它不会主动做这个分层。 这是一个“Prompt 够详细就能解决”的问题，但默认不够详细。

四、深度解析：七个高频状态码场景的正确与错误

这一节我会逐一拆解每个状态码的“正确使用姿势”，顺带把 Claude Code 生成代码的典型错误放上来做对比。如果你正在用 AI 写 API，这一节可以作为你的代码审计 checklist。

4.1 200 OK：最被滥用的状态码

正确使用：请求成功，且响应体包含了请求所期望的表述。适用于 GET 获取资源、PUT 更新资源成功、DELETE 删除成功返回结果等场景。

典型滥用：

• 创建资源成功后返回 200 而不是 201
• 请求参数错误时返回 200 加 body 里的错误信息
• 系统异常时返回 200 加 body 里的错误信息

Claude Code 中的表现：在功能简单的场景下正确率高，但在多分支逻辑中，约 22% 的 200 实际上是滥用。

判断原则：问你一个问题，这个响应是“请求成功了”还是“我知道哪里错了”？如果是后者，不要用 200。

4.2 201 Created：被遗忘的成功

正确使用：请求成功且创建了一个或多个新资源。响应应该包含：

• Location 头指向新资源的 URI
• 响应体可选地包含新资源的表述

Claude Code 中的表现：简单创建场景（单个用户注册）表现正确，批量创建和复杂嵌套创建时经常退回到 200。

值得记录的一个细节：Claude Code 从未在 201 响应中自动添加 Location 头。一个完整的 201 响应应该是：

res.status(201)
.set('Location', /api/users/${user.id})

.json({ /* user data */ });

而 Claude Code 生成的代码只有 res.status(201).json(...)。

4.3 400 Bad Request vs 422 Unprocessable Entity

这是最常被问到的区分问题，也是 Claude Code 完全混淆的两个码。

400 Bad Request：请求的语法有误，服务器无法理解。典型场景：

• JSON 格式错误
• 必填字段缺失
• 字段类型错误（期望数字传了字符串）

422 Unprocessable Entity：请求语法正确，但语义上无法处理。典型场景：

• 字段格式正确但值不合法（如 email 格式对但域名不存在）
• 业务规则校验失败（如密码包含连续重复字符）
• 请求的内容与业务逻辑冲突

Claude Code 的表现：它完全不会使用 422。所有校验失败统一用 throw Error 再转 500，或者手动处理时统一用 400。

我的建议：如果你不想搞得太细，统一用 400 是可接受的折中；但如果你想区分，就需要在 Prompt 里明确告诉 AI。

4.4 401 Unauthorized vs 403 Forbidden

这是 Claude Code 处理得最好的部分，它在基础场景下几乎不会搞混。

• 401：未提供认证凭据，或认证凭据无效
• 403：认证凭据有效，但该用户没有执行此操作的权限

但有一个我踩过的坑：当业务逻辑变复杂时，比如“用户只能查看自己的订单详情”，Claude Code 生成的代码有时会返回 401 而不是 403。因为它的 try-catch 里可能把“权限校验的中间件抛出的异常”当成了“认证失败”。

正确做法：认证中间件抛出 401，授权中间件抛出 403，两者必须分两个中间件，不能混。

4.5 404 Not Found

正确使用：请求的资源不存在。但，

• GET 一个不存在的资源：返回 404
• PUT 更新一个不存在的资源：取决于设计，可以 404，也可以 201（创建新资源）
• DELETE 一个不存在的资源：可以 404，也可以 204（幂等性考虑）

安全考量（这是 Claude Code 完全缺失的）：

• 对于需要登录的接口，如果资源存在但用户没有权限，应该返回 404 而不是 403，以防止攻击者探测资源是否存在
• 对于公开接口，区分 404（不存在）和 403（无权限）是可以的

Claude Code 的表现：技术上正确（不存在的资源返回 404），但安全考量为零。

4.6 500 Internal Server Error

正确使用：服务器遇到了未预期的状况，无法完成请求。典型场景：

• 数据库连接失败
• 外部服务调用失败且无法恢复
• 代码逻辑错误（如空指针）

Claude Code 的最大错误：把所有 catch 到的异常都当成 500。

修复方法：创建自定义异常类：

class ValidationError extends Error {
constructor(message) {

super(message);

this.statusCode = 400;

}

}

class BusinessError extends Error {

constructor(message, statusCode = 409) {

super(message);

this.statusCode = statusCode;

}

}

如果你的 Prompt 或 CLAUDE.md 里定义了这个异常体系，Claude Code 能学会正确使用。但默认状态下，它不会主动创建。

4.7 204 No Content

正确使用：请求成功，但响应体为空。典型场景：

• DELETE 成功且不返回被删除的资源
• PUT 更新成功且不需要返回更新后的资源

Claude Code 的表现：注销接口正确使用了 204。但它有时会在 204 响应中意外带上 body，这在 HTTP 语义上是冲突的（204 不应该有响应体）。

五、数据观察：我审计的量化结果

5.1 样本说明

我统计了过去 6 个月使用 Claude Code 开发的 3 个实际项目和 2 个测试项目，共涉及 46 个 API 接口（排除纯静态页面和 SSR 接口）。

对每个接口的状态码返回进行人工审计，标记“严重错误”、“轻微瑕疵”和“正确”。

5.2 错误类型分布

最严重的两个问题：“异常 catch 统一返回 500”和“参数校验失败返回 500”，加起来影响了 43.5% 的接口。也就是说，几乎每两个 AI 生成的接口，就有一个在出错时会返回误导性的 500。

5.3 不同 Prompt 质量下的对比

我也做了对照实验：用同样功能需求，但 Prompt 详细程度不同，看状态码质量的变化。

关键发现：当你在 Prompt 或 CLAUDE.md 里明确写入了状态码规范，Claude Code 的表现可以从“不及格”跳到“优秀”。这说明它不是不会，而是“默认情况下不觉得这很重要”。

六、解决方案：如何“教会”Claude Code 正确使用状态码

6.1 在 CLAUDE.md 里写入状态码规范

这是最有效的方法。CLAUDE.md 是 Claude Code 的项目级记忆文件，放在项目根目录下，每次对话它都会读取。

我现在的 CLAUDE.md 里有一个固定的“HTTP 状态码规范”部分，直接分享给你：

## HTTP 状态码使用规范
2xx 成功

200: GET 成功、PUT 更新成功、DELETE 成功且有返回体

201: POST 创建资源成功，必须包含 Location 头

202: 异步处理已接受，返回任务 ID 用于查询进度

204: 操作成功且无返回体（如 DELETE 后不返回内容）

4xx 客户端错误

400: 请求格式错误（JSON 语法、必填字段缺失）

401: 未提供认证头或 Token 无效/过期

403: 认证有效但权限不足

404: 请求的资源不存在（含权限不足时模糊处理）

409: 业务冲突（用户名已存在、库存不足等）

422: 格式正确但语义错误（邮箱格式对但已注销等）

5xx 服务器错误

500: 仅用于未预期的内部错误（数据库连接失败、外部服务崩溃）

502: 上游服务返回无效响应

503: 服务暂时不可用（维护、过载）

关键规则

禁止在所有异常场景下统一返回 500
参数校验失败立即返回 400，不要进入 try-catch
业务规则违反返回 409 或 422，不要进入 try-catch
只有真正的系统异常进入 catch 返回 500
创建资源必须返回 201 加 Location 头
认证失败 401，授权失败 403，不得混淆
对于需认证的接口，无权访问的资源应返回 404

加入这个配置后，Claude Code 生成的状态码质量从约 24% 的正确率提升到约 91%。

6.2 在 Prompt 中直接给出状态码指令

如果不方便改 CLAUDE.md（比如是多人协作的项目），在每次 Prompt 里直接指定状态码要求也有效。

对比一下：

• ❌ 模糊 Prompt：创建一个登录接口
• ✅ 精确 Prompt：创建一个登录接口，验证用户名和密码。认证成功返回 200 和 JWT token；凭据无效返回 401；参数缺失返回 400；其他异常返回对应 4xx 或 500，禁止在业务错误时返回 200 或 500

6.3 建立代码审查的“状态码专项检查点”

我现在的习惯是，每次 AI 生成完代码，在做常规 Code Review 之前，先过一次状态码专项检查：

Step 1：搜索所有 res.status( 或 response.status = 的出现位置

Step 2：逐个核对：这个响应在什么场景下触发？状态码是否符合语义？

Step 3：特别注意所有 catch 块里的 500，它们有多少其实是业务异常？

Step 4：检查是否有 200 后面跟着错误信息对象的情况

这个检查流程我通常 10 分钟完成，但能发现约 70% 的状态码问题。

6.4 用自动化测试“锁死”状态码规范

审查是一次性的，自动化测试是持续的。我在每个 API 项目中都会写一个简单的 Pytest/Jest 测试文件，专门验证状态码：

# test_http_status.py
def test_register_success_returns_201():

response = client.post('/api/users/register', json={

'username': 'newuser',

'email': 'new@example.com',

'password': 'ValidPass123'

})

assert response.status_code == 201

assert 'Location' in response.headers

def test_register_missing_fields_returns_400():

response = client.post('/api/users/register', json={

'username': 'incomplete'

})

assert response.status_code == 400

def test_login_invalid_credentials_returns_401():

response = client.post('/api/users/login', json={

'email': 'wrong@example.com',

'password': 'wrong'

})

assert response.status_code == 401

def test_get_user_not_found_returns_404():

response = client.get('/api/users/99999', headers=auth_header)

assert response.status_code == 404

这组测试的价值：它能防止你或 AI 在后续修改中不小心把状态码改错。每次 CI 跑过，状态码规范就被强制执行了一次。

七、边界权衡：不是所有“不规范”都是错

在前面的分析里，我严格按 HTTP 规范来评审。但在实际项目中，有些“不规范”是有意为之。这一节讨论几个值得权衡的场景。

7.1 企业内部 API：200 + code 模式是否一定错？

很多企业内部系统（尤其是中国互联网公司）习惯用这样的响应格式：

{
"code": 0,

"message": "success",

"data": {}

}

从 HTTP 语义角度，这样做是错的，HTTP 状态码 200 应该表示“请求成功”，不应该包含业务错误。但从工程角度，这不是没有道理：

1. 统一格式便于前端拦截器处理
2. 某些中间件/网关只对 200 做正常转发
3. 历史遗留问题，改不动

我的判断：如果是纯内部系统，团队已有约定俗成的格式，维持一致性比追求 HTTP 规范更重要。但如果是开放 API、对第三方暴露的接口，必须严格使用 HTTP 状态码。

关键不是说“哪种对”，而是“别混着用”。 同一个 API 系统里，一部分接口用 HTTP 状态码表达错误，另一部分用 200 + code，这才是真正让人崩溃的。

7.2 GraphQL：状态码的规则不一样

如果你的 API 是 GraphQL 而非 REST，200 包裹错误的模式是官方的推荐做法。GraphQL 的规范里，即使查询执行出错，HTTP 层面通常也返回 200，错误信息放在 errors 数组里。

这是 Claude Code 容易误判的场景：如果你让它写一个 GraphQL API，它可能套用 REST 的状态码习惯，该用 200 的地方用了 400。

7.3 安全与语义的冲突

前面提到的：权限不足时返回 404 还是 403？

• 语义优先：返回 403，明确告诉调用方“你有认证，但没权限”
• 安全优先：返回 404，模糊处理，让攻击者无法探测资源是否存在

我现在的实践：对内部管理后台 API，用 403；对用户端 API，用 404。这个决策需要你在 Prompt 里明确告诉 AI，它自己不会做这个权衡。

八、与人类开发者的对比：到底是 AI 的问题还是人的问题

8.1 我对比了三组代码

为了排除“HTTP 状态码本来就没人在意”的质疑，我做了三组对比：

A 组：三个中级后端开发工程师（3-5 年经验）手写同一批 API 接口

B 组：Claude Code 在无额外 Prompt 下生成

C 组：Claude Code 在配置了 CLAUDE.md 状态码规范后生成

结果：

解读：

• 在基础场景下，Claude Code 和中级工程师差距不大
• 复杂场景下，默认 AI 显著落后于人工
• 但有了规范配置后，AI 的表现超过了中级工程师

8.2 问题不在 AI，在“怎么用 AI”

看完上面的对比，我的观点很明确：把 Claude Code 当成“会自己注意状态码的资深工程师”是错误的。把它当成“会严格按照你给的规范执行的超强初级工程师”是正确的。

默认状态下的 Claude Code，状态码能力约等于一个刚毕业、看过几本教材但没在生产环境背过锅的应届生。但你给它一份清晰的规范文档，它的执行力远超大多数中级工程师，因为人会有“改不动”、“懒得改”、“这又不影响功能”的心态，而 AI 会忠实执行每一条你写下的规范。

九、行动建议：你的 API 项目现在该做什么

基于以上所有分析，我给出可直接操作的建议。

9.1 如果你正在用 Claude Code 开发新 API

立即行动（今天就能做）：

1. 把第六节的 CLAUDE.md 状态码规范复制到你的项目根目录
2. 每次生成接口后，按 6.3 的四步检查法快速审查
3. 给每个接口写 1-2 个状态码断言测试

本周内完成：

1. 创建一个自定义异常类（ValidationError、BusinessError），让 Claude Code 在整个项目中使用
2. 在你的 API 文档生成模板中加入状态码部分

9.2 如果你在用 AI 维护现有 API

第一步：先把现有接口跑一遍状态码审计。你可能已经有大量 200 + 内部 code 或者 500 滥用的问题。

第二步：区分“可以改的”和“不能改的”。对外的、历史久远的接口，如果改动会影响下游，保持现状。新接口严格执行规范。

第三步：在新功能开发中逐步切换，不要试图一次重构所有旧接口。

9.3 如果你是技术管理者

提高 AI 代码审查标准：在 Code Review checklist 中显式加入“HTTP 状态码审查”条目。不要假设 AI 生成的代码状态码是对的。

建立规范文档：在团队 wiki 中明确你们的 API 状态码使用标准。这个标准会自动进入 CLAUDE.md，间接“训练”每个开发者使用的 AI。

投资自动化测试：状态码测试的 ROI 极高，一次写完，永久防止退化。

十、结论与反思

回到标题的问题：用 Claude Code 开发 RESTful API 时对 HTTP 状态码的使用是否正确？

答案是：默认不正确，但它可以被纠正。

Claude Code 在基础场景下的状态码意识是合格的，它知道创建该返回 201，找不到该返回 404，认证失败该返回 401。但它在复杂场景下会暴露出致命的懒散：把所有异常扔进 500，在批量操作时退化成 200 + 内部 code，完全忽略 Location 头，从未考虑安全场景。

这些问题不是 Claude Code 独有的。我测试过的每一个 AI 编程工具都有类似问题。这不是 AI 的 bug，这是 AI 的“默认心态”，快速完成、跑通就行、细节不重要。

但 HTTP 状态码从来不是“细节”。它是 API 的语言，是监控系统的眼睛，是客户端处理逻辑的决策依据。在 RESTful API 中，状态码用错，等于说话时把“不行”说成“好”，对方会完全误解你的意思。

作为用 AI 写代码的开发者，我们不是“代码打字员”。我们是 AI 产出的审核者、质量的守门人。工具越快，我们的审查意识反而需要越强。

下一步：打开你最近用 Claude Code 生成的 API 项目，搜索 res.status(500)，看看里面有多少其实是参数校验。搜索 res.status(200) 后面跟着 code 或 error 的情况，你会惊讶自己放过了多少问题。

然后，把我第六节的 CLAUDE.md 规范复制进去。10 分钟之后，你再让 Claude Code 生成一个新接口，对比一下状态码质量。到那时候，你对这篇文章的判断会有自己的答案。

工具越强大，规范和审查就越重要。在 AI 时代写 API，你不是在写代码，你是在守底线。